diff options
570 files changed, 26632 insertions, 16229 deletions
diff --git a/.commit-template b/.commit-template index 6e0e3a4..589ca89 100644 --- a/.commit-template +++ b/.commit-template @@ -5,6 +5,6 @@ # ---[ Fields ]-----------------[ uncomment and edit as applicable ]---| #Task-number: -Reviewed-by: pending +#Reviewed-by: # ==================================[ please wrap at 72 characters ]===| @@ -7,6 +7,7 @@ examples/*/*/* examples/*/*/*[.]app !examples/declarative/* !examples/tutorials/* +!examples/tutorials/*/* !examples/ja_JP/*/* demos/*/* !demos/spectrum/* @@ -4780,12 +4780,7 @@ if true; then ###[ '!' -f "$outpath/bin/qmake" ]; #mkspecs/default is used as a (gasp!) default mkspec so QMAKESPEC needn't be set once configured rm -rf mkspecs/default - if [ "$XPLATFORM_SYMBIAN_SBSV2" = "yes" ]; then -#Link is not supported for Symbian build system - cp -a mkspecs/`echo $XQMAKESPEC | sed "s,^${relpath}/mkspecs/,,"` mkspecs/default - else - ln -s `echo $XQMAKESPEC | sed "s,^${relpath}/mkspecs/,,"` mkspecs/default - fi + ln -s `echo $XQMAKESPEC | sed "s,^${relpath}/mkspecs/,,"` mkspecs/default # fix makefiles for mkfile in GNUmakefile Makefile; do EXTRA_LFLAGS= @@ -8256,12 +8251,7 @@ else mv "$outpath/src/corelib/global/qconfig.h.new" "$outpath/src/corelib/global/qconfig.h" chmod -w "$outpath/src/corelib/global/qconfig.h" for conf in "$outpath/include/QtCore/qconfig.h" "$outpath/include/Qt/qconfig.h"; do - if [ "$XPLATFORM_SYMBIAN_SBSV2" = "yes" ]; then - [ -e "$conf" ] && rm -rf "$conf" - cp -a "$outpath/src/corelib/global/qconfig.h" "$conf" - elif [ '!' -f "$conf" ]; then - ln -s "$outpath/src/corelib/global/qconfig.h" "$conf" - fi + ln -s "$outpath/src/corelib/global/qconfig.h" "$conf" done fi #------------------------------------------------------------------------------- diff --git a/demos/qtdemo/examplecontent.cpp b/demos/qtdemo/examplecontent.cpp index 64737c3..5385259 100644 --- a/demos/qtdemo/examplecontent.cpp +++ b/demos/qtdemo/examplecontent.cpp @@ -83,8 +83,10 @@ QString ExampleContent::loadDescription() int errorLine, errorColumn; QDomDocument exampleDoc; - if (!exampleDoc.setContent(ba, false, &errorMsg, &errorLine, &errorColumn)) { - qDebug() << errorMsg << errorLine << errorColumn; + if (ba.isEmpty()) { + qDebug() << "No documentation found for" << name << "Is the documentation built?"; + } else if (!exampleDoc.setContent(ba, false, &errorMsg, &errorLine, &errorColumn)) { + qDebug() << "Error loading documentation for " << name << ": " << errorMsg << errorLine << errorColumn; } QDomNodeList paragraphs = exampleDoc.elementsByTagName("p"); diff --git a/demos/spectrum/spectrum.pri b/demos/spectrum/spectrum.pri index 5773900..75c0113 100644 --- a/demos/spectrum/spectrum.pri +++ b/demos/spectrum/spectrum.pri @@ -41,9 +41,9 @@ win32 { # ..$${spectrum_build_dir} # without the result having a trailing slash where spectrum_build_dir # is undefined. - spectrum_build_dir = /release - if (!debug_and_release|build_pass): CONFIG(debug, debug|release) { - spectrum_build_dir = /debug + build_pass { + CONFIG(release, release|debug): spectrum_build_dir = /release + CONFIG(debug, release|debug): spectrum_build_dir = /debug } } diff --git a/dist/changes-4.7.3 b/dist/changes-4.7.3 index fa8a71e..1ff23c6 100644 --- a/dist/changes-4.7.3 +++ b/dist/changes-4.7.3 @@ -16,6 +16,16 @@ Qt Bug Tracker: http://bugreports.qt.nokia.com Merge Request: http://qt.gitorious.org **************************************************************************** +* Library * +**************************************************************************** + +QtNetwork +--------- + +- SSL +* [QTBUG-18338] blacklist fraudulent SSL certificates + +**************************************************************************** * Platform Specific Changes * **************************************************************************** @@ -38,6 +48,8 @@ QtMobility QtBearer depending applications * [QTBUG-17786] BC between Qt 4.7.3 and 4.6.3 QTreeView::indexRowSizeHint doesn't return correct value on Symbian for row when QPushButton widget is inserted in the treeview +* [QTBUG-4953] QMessageBox can not be closed/dismissed on touch phones if any +widget is fullscreen - Painting * [QTBUG-17907] tst_QGraphicsTransform::rotation3d test case from diff --git a/doc/src/classes.qdoc b/doc/src/classes.qdoc index a1b5282..90a783e 100644 --- a/doc/src/classes.qdoc +++ b/doc/src/classes.qdoc @@ -153,7 +153,7 @@ \brief A Qt namespace contains enum types, functions, and sometimes classes. - This is a list of the main namespaces in Qt. + This is a list of the main namespaces in Qt. \generatelist{namespaces} */ diff --git a/doc/src/classes/phonon-api.qdoc b/doc/src/classes/phonon-api.qdoc index c9f7a66..95e20dd 100644 --- a/doc/src/classes/phonon-api.qdoc +++ b/doc/src/classes/phonon-api.qdoc @@ -691,11 +691,11 @@ Example where data is written repeatedly. - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 0 + \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 0 Example where data is written once: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 1 + \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 1 \sa Phonon::MediaSource, Phonon::MediaObject @@ -811,7 +811,7 @@ The function is necessary for the case where a non-seekable MediaStream is played more than once. For a seekable stream the implementation can simply call - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 2 + \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 2 \sa writeData(), needData() */ @@ -1003,7 +1003,7 @@ send an URL or filename directly to the constructors of the \l{Phonon::}{MediaObject}. - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 3 + \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 3 A MediaSource object cannot be reused for another multimedia source. It is possible to play the same source again, and also @@ -1382,7 +1382,7 @@ immediately after you call the play() function. A play and forget code example: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 4 + \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 4 \sa {Phonon Module}, MediaObject */ @@ -1471,7 +1471,7 @@ If you need low latency between calling play() and the sound actually starting to play on your output device you need to use MediaObject and be able to set the URL before calling play(). Note that - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 5 + \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 5 doesn't make a difference: the application should be idle between the load and play calls so that the backend can start preloading the media and fill audio buffers. @@ -1612,13 +1612,13 @@ queue; the new source is then removed from the queue. The queue can be altered at any time. - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 7 + \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 7 You can also make use of the \l{Phonon::MediaObject::}{aboutToFinish()} signal, which is guaranteed to be emitted in time for altering the queue. - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 8 + \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 8 When playback is finishing, i.e., when a media source has been played to the end and the queue is empty, several signals are @@ -1715,9 +1715,9 @@ \warning The back-end is free to choose a different tick interval close to what you asked for. This means that the following code \c may fail: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 9 + \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 9 On the other hand the following is guaranteed: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 10 + \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 10 \sa tick() */ @@ -1745,7 +1745,7 @@ media object gets a new source. Listen to the hasVideoChanged() signal instead. - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 11 + \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 11 Returns \c true if the media contains video data; otherwise, returns \c false. @@ -1763,7 +1763,7 @@ media object gets a new media source. The hasVideoChanged() signal is emitted after this information is available. - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 12 + \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 12 Returns \c true if the current media may be seeked; otherwise, returns \c false. @@ -1786,7 +1786,7 @@ A typical usage looks like this: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 13 + \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 13 */ /*! @@ -1867,7 +1867,7 @@ We show an example: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 14 + \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 14 \sa currentSource(), MediaSource */ @@ -2126,7 +2126,7 @@ You can use this signal to show a progress bar to the user when in BufferingState: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 15 + \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 15 Note that the \l{Phonon::}{BufferingState} is commonly used when waiting for data over a network connection, but this might not be @@ -2270,7 +2270,7 @@ happen if the user has requested a backend change. To connect to this signal do the following: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 16 + \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 16 \sa Notifier::capabilitiesChanged() */ @@ -2362,10 +2362,10 @@ An example use case would be to give the user a QComboBox to select the output device: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 17 + \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 17 And to retrieve the selected AudioOutputDevice: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 18 + \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 18 */ @@ -2565,7 +2565,7 @@ In order to use an effect, insert it into the path as follows: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 19 + \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 19 The effect will immediately begin applying it's transformations on the path. To stop it, remove the Effect from the path. @@ -3108,7 +3108,7 @@ The following code example shows how to create a path between two media nodes and insert an effect on that path. - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 20 + \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 20 \sa Phonon::MediaNode, Phonon::MediaObject, Phonon::AudioOutput, Phonon::VideoWidget, {Phonon Module} @@ -4085,7 +4085,7 @@ A typical example of usage follows below: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 21 + \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 21 \sa {Phonon Module} */ diff --git a/doc/src/declarative/anchor-layout.qdoc b/doc/src/declarative/anchor-layout.qdoc index 0655fdb..4dd5eb9 100644 --- a/doc/src/declarative/anchor-layout.qdoc +++ b/doc/src/declarative/anchor-layout.qdoc @@ -28,15 +28,16 @@ /*! \page qml-anchor-layout.html \target anchor-layout -\title Anchor-Based Layout in QML - -\section1 Overview +\contentspage QML Features +\previouspage {Using QML Positioner and Repeater Items}{Component Layouts} +\nextpage {QML Mouse Events}{Mouse Events} +\title Anchor-based Layout in QML In addition to the more traditional \l Grid, \l Row, and \l Column, QML also provides a way to layout items using the concept of \e anchors. Each item can be thought of as having a set of 7 invisible "anchor lines": \l {Item::anchors.left}{left}, \l {Item::anchors.horizontalCenter}{horizontalCenter}, -\l {Item::anchors.right}{right}, \l {Item::anchors.top}{top}, +\l {Item::anchors.right}{right}, \l {Item::anchors.top}{top}, \l {Item::anchors.verticalCenter}{verticalCenter}, \l {Item::anchors.baseline}{baseline}, and \l {Item::anchors.bottom}{bottom}. diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc index 59bf8f6..129fa34 100644 --- a/doc/src/declarative/animation.qdoc +++ b/doc/src/declarative/animation.qdoc @@ -27,308 +27,214 @@ /*! \page qdeclarativeanimation.html -\title QML Animation +\ingroup qml-features +\contentspage QML Features +\previouspage {QML States}{States} +\nextpage {QML Data Models}{Structuring Data with Models} +\title QML Animation and Transitions + +\keyword qml-animation-elements +\section1 Animation and Transitions Elements +\list +\o \l {Transition} - Animates transitions during state changes +\o \l {SequentialAnimation} - Runs animations sequentially +\o \l {ParallelAnimation} - Runs animations in parallel +\o \l {Behavior} - Specifies a default animation for property changes +\o \l {PropertyAction} - Sets immediate property changes during animation +\o \l {PauseAnimation} - Introduces a pause in an animation +\o \l {SmoothedAnimation} - Allows a property to smoothly track a value +\o \l {SpringAnimation} - Allows a property to track a value in a spring-like motion +\o \l {ScriptAction} - Runs scripts during an animation +\endlist +\keyword qml-property-animation-elements +Elements that animate properties based on data types +\list +\o \l {PropertyAnimation} - Animates property changes +\o \l {NumberAnimation} - Animates properties of type qreal +\o \l {Vector3dAnimation} - Animates properties of type QVector3d +\o \l {ColorAnimation} - Animates color changes +\o \l {RotationAnimation} - Animates rotations +\o \l {ParentAnimation} - Animates parent changes +\o \l {AnchorAnimation} - Animates anchor changes +\endlist -In QML, animations are created by applying animation objects to object property -values to gradually change them over time. Animation objects are created from -the built-in set of animation elements, which can be used to animate various -types of property values. In addition, animation objects can be applied in -different ways depending on the context in which they are required. +In QML, animations are created by applying animation elements to property +values. Animation elements will interpolate property values to create smooth +transitions. As well, state transitions may assign animations to state changes. To create an animation, use an appropriate animation element for the type of the property that is to be animated, and apply the animation depending on the -type of behavior that is required. This page describes the \l {Types of -Animations} that can be created and the \l {Animation Elements} that are used -to create these animations. - - -\section1 Types of Animations - -An animation is created in different ways depending on the context in which it -is required. Suppose a \l Rectangle's movement - that is, changes in its \c x -or \c y property values - should be animated. The semantics of the animation -differ depending on whether you want to create: - -\list -\o An animation that moves the \l Rectangle as soon as it is created, to a -known position -\o An animation that only triggers when the \l Rectangle is moved by external -sources - for example, when the mouse is clicked, animate the movement to the -mouse position -\o An animation that triggers when a particular signal is received -\o A standalone animation that is not bound to the \l Rectangle's movement, but -instead can be started and stopped from script as required -\o An animation that only triggers during \l{QML States}{state changes} -\endlist +type of behavior that is required. -To support these different types of animation methods, QML provides several -methods for defining an animation. These are: +\keyword qml-triggering-animations +\section1 Triggering Animations -\list -\o Creating an \l{Animations as Property Value Sources}{animation using -property value sources}, to immediately animate a specific property -\o Using \l{Behavioral Animations}{behavioral animations}, which are triggered -when a property changes value -\o \l{Animations in a Signal Handler}{Within a signal handler}, to be triggered -when a signal is received -\o As a \l{Standalone Animation}{standalone animation}, that can be -started/stopped from script and can be rebound to different objects -\o Using \l{Transitions}{transitions}, to provide animations between \l{QML -States}{state changes} -\endlist +There are several ways of setting animation to an object. -These methods are demonstrated below. Notice these examples use -PropertyAnimation, which is one of several QML elements that can be used to -create an animation. See the \l {Animation Elements} section further below for -details. +\keyword qml-direct-animation +\section2 Direct Property Animation +To create an immediate movement or animated movement, set the property value +directly. This may be done in signal handlers or attached properties. +\snippet doc/src/snippets/declarative/animation.qml direct property change -\section2 Animations as Property Value Sources +However, to create more control, \e {property animations} apply smooth movements +by interpolating values between property value changes. Property animations +provide timing controls and allows different interpolations through +\l{qml-easing-animation}{easing curves}. -An animation is applied as a \l{QDeclarativePropertyValueSource}{property value -source} using the \e Animation \bold on \e Property syntax. Here is a \l -Rectangle whose movement is animated using this method: +\snippet doc/src/snippets/declarative/animation.qml property animation -\snippet doc/src/snippets/declarative/animation-propertyvaluesource.qml 0 - -This applies a PropertyAnimation to the \l Rectangle's \c x and \c y properties -to animate from their current values (i.e. zero) to 50, over 1000 milliseconds. -The animation starts as soon as the \l Rectangle is loaded. To animate from -specific values rather than the current \c x and \c y values, set the -PropertyAnimation's \l {PropertyAnimation::}{from} property. - -Specifying an animation as a property value source is useful for animating a -property to a particular value as soon as the object is loaded. - - -\section2 Behavioral Animations - -Often an animation should be applied whenever a particular property value -changes. In these cases, a \l Behavior can be used to specify a default -animation for a property change. Here is an example: - -\snippet doc/src/snippets/declarative/animation-behavioral.qml 0 - -This \l Rectangle has \l Behavior objects applied to its \c x and \c y -properties. Whenever these properties change (in this case, when the mouse is -clicked within the parent \l Item), the PropertyAnimation objects defined -within the behaviors will be applied to these properties, thus animating the \l -Rectangle's movement to its new position. Unlike the method of \l {Animations -as Property Value Sources}{defining an animation as a property value source}, -which creates a one-time animation that animates a property to a known value, a -behavioral animation is an animation that is triggered \e {in response to} a -value change. - -Any changes to these properties will trigger their animations. If \c x or \c y -were bound to other properties, and those properties changed, the animation -would be triggered. The \l{Behavior::}{enabled} property can be used to force a -\l Behavior to only apply under certain circumstances. - -Notice that unlike for property value source animations, the -PropertyAnimation's \l {PropertyAnimation::}{from} and \l -{PropertyAnimation::}{to} properties do not need to be defined because these -values are already provided, respectively, by the \l Rectangle's current values -and the new values set in the \c onClicked handler. If these properties were -defined anyway, they would override the default values. +Specialized \l{qml-property-animation-elements}{property animation elements} +have more efficient implementations than the \l{PropertyAnimation} element. They +are for setting animations to different QML types such as \c int, \c color, and +rotations. Similarly, the \l{ParentAnimation} can animate parent changes. -See the \l {declarative/animation/behaviors}{Behaviors example} for a -demonstration of behavioral animations. +See the \l {qml-controlling-animations}{Controlling Animations} section for more +information about the different animation properties. +\keyword qml-transition-animations +\section2 Transitions during State Changes -\section2 Animations in a Signal Handler +\l{QML States}{States} are property configurations where a property may have different values to reflect different states. State changes introduce +abrupt property changes; animations smooth transitions to produce visually +appealing state changes. -An animation can be created within a signal handler to be triggered when the -signal is received. For example: - -\snippet doc/src/snippets/declarative/animation-signalhandler.qml 0 +The \l{Transition} element can contain +\l{qml-animation-elements}{animation elements} to interpolate property changes +caused by state changes. To assign the transition to an object, bind it to the +\c transitions property. -The PropertyAnimation is triggered when the MouseArea is clicked, animating the -\c x and \c y properties to a value of 50 over 1000 milliseconds. Since the -animation is not bound to a particular object or property, it must define the -\l {PropertyAnimation::}{target} and \l {PropertyAnimation::}{property} (or \l -{PropertyAnimation::}{targets} and \l{PropertyAnimation::}{properties}) values. -The \l {PropertyAnimation::}{to} property is also required to specify the new -\c x and \c y values. +A button might have two states, the \c pressed state when the user clicks on the +button and a \c released state when the user releases the button. We can assign +different property configurations for each state. A transition would animate the +change from the \c pressed state to the \c released state. Likewise, there would +be an animation during the change from the \c released state to the \c pressed +state. +\snippet doc/src/snippets/declarative/animation.qml transition animation -\section2 Standalone Animations +Binding the \c to and \c from properties to the state's name will assign that +particular transition to the state change. For simple or symmetric transitions, +setting the to \c to property to the wild card symbol, "\c{*}", denotes +that the transition applies to any state change. -Animations can also be created as ordinary QML objects that are not bound to -any particular objects and properties. Here is an example, using a -PropertyAnimation object. The animation is explicitly started when the -\l Rectangle is clicked: +\snippet doc/src/snippets/declarative/animation.qml wildcard animation -\snippet doc/src/snippets/declarative/animation-standalone.qml 0 +\section2 Default Animation as Behaviors -A standalone animation object is not running by default and must be started explicitly -using the \l {Animation::}{running} property or \l {Animation::}{start()} and -\l {Animation::}{stop()} methods. Since the animation is not bound to a -particular object or property, it must define the \l -{PropertyAnimation::}{target} and \l {PropertyAnimation::}{property} (or \l -{PropertyAnimation::}{targets} and \l{PropertyAnimation::}{properties}) values. -The \l {PropertyAnimation::}{to} property is also required to specify the new -\c x and \c y values. (The \l {PropertyAnimation::}{from} value can optionally -be provided.) +Default property animations are set using \e {behavior animations}. Animations +declared in \l {Behavior} elements apply to the property and animates any +property value changes. However, Behavior elements have an +\c enabled property to purposely enable or disable the behavior animations. -Standalone animations are useful when an animation is not targeted towards a -single object property and the animation should be explicitly started and -stopped. +A ball component might have a behavior animation assigned to its \c x, \c y, and +\c color properties. The behavior animation could be set up to simulate an +elastic effect. In effect, this behavior animation would apply the elastic +effect to the properties whenever the ball moves. +\snippet doc/src/snippets/declarative/animation.qml behavior animation -\section2 Transitions +There are several methods of assigning behavior animations to properties. The +\c{Behavior on <property>} declaration is a convenient way of assigning a +behavior animation onto a property. -Transitions are used to describe the animations to be applied when a \l {QML -States}{state change} occurs. To create a transition, define a \l Transition -object and add it to an item's \l {Item::}{transitions} property. An example: +See the \l {declarative/animation/behaviors}{Behaviors example} for a +demonstration of behavioral animations. -\snippet doc/src/snippets/declarative/animation-transitions.qml 0 +\section1 Playing Animations in Parallel or in Sequence -The PropertyChanges object in the \e moved state defines that when the -\l Rectangle is in this state, its position should be changed -to (50, 50). When the \l Rectangle changes to the \e moved state, the -\l Transition will be triggered, and the transition's \l PropertyAnimation will -animate the changes in the \c x and \c y properties to their new values. -The animation will not be applied at any time other than during the state -change. +Animations can run \e {in parallel} or \e {in sequence}. Parallel animations +will play a group of animations at the same time while sequential animations +play a group of animations in order: one after the other. Grouping animations in +\l{SequentialAnimation} and \l{ParallelAnimation} will play the animations in +sequence or in parallel. -Notice the example does not set any \l {PropertyAnimation::}{from} and \l -{PropertyAnimation::}{to} values for the PropertyAnimation. As a convenience, -these properties are automatically set to the values of \c x and \c y before -and after the state change, respectively. However, they can be explicitly set -if these values should be overrided. +A banner component may have several icons or slogans to display, one after the +other. The \c opacity property could transform to \c 1.0 denoting an opaque +object. Using the \l{SequentialAnimation} element, the opacity animations will +play after the preceding animation finishes. The \l{ParallelAnimation} element +will play the animations at the same time. -Also notice the PropertyAnimation does not need to specify a \l -{PropertyAnimation::}{target} object; any \c x or \c y value of any object that -has changed during the state change will be animated. However, the target can -be set if the animation should be restricted to certain objects. +\snippet doc/src/snippets/declarative/animation.qml sequential animation -The top-level animations in a \l Transition are run in parallel. To run them -one after the other, use a SequentialAnimation, as shown below in \l {Grouping -Animations}. +Once individual animations are placed into a SequentialAnimation or +ParallelAnimation, they can no longer be started and stopped independently. The +sequential or parallel animation must be started and stopped as a group. -See the \l Transition documentation for more information. +The \l SequentialAnimation element is also useful for playing +\l{qml-transition-animations}{transition animations} because animations are +played in parallel inside transitions. +See the \l {declarative/animation/basics}{Animation basics example} for a +demonstration of creating and combining multiple animations in QML. -\section1 Animation Elements +\keyword qml-controlling-animations +\section1 Controlling Animations -To create an animation, choose from one of the built-in QML animation elements. -While the above examples are demonstrated using PropertyAnimation, they could -have used other elements depending on the type of the property to be animated -and whether a single or multiple animations are required. +There are different methods to control animations. -All animation elements inherit from the \l Animation element. It is not +\section2 Animation Playback +All \l{qml-animation-elements}{animation elements} inherit from the \l Animation element. It is not possible to create \l Animation objects; instead, this element provides the -essential properties and methods for animation elements. For example, it allows -animations to be started and stopped through the \l {Animation::}{running} -property and the \l{Animation::}{start()} and \l{Animation::}{stop()} methods. -It can also define the number of \l {Animation::}{loops} for an animation. +essential properties and methods for animation elements. Animation elements have +\c{start()}, \c{stop()}, \c{resume()}, \c{pause()}, \c {restart()}, and +\c{complete()} -- all of these methods control the execution of animations. +\keyword qml-easing-animation +\section2 Easing -\section2 Property Animation Elements +Easing curves define how the animation will interpolate between the start value +and the end value. Different easing curves might go beyond the defined range of +interpolation. The easing curves simplify the creation of animation effects such +as bounce effects, acceleration, deceleration, and cyclical animations. -PropertyAnimation is the most basic animation element for animating a property. -It can be used to animate \c real, \c int, \c color, \c rect, \c point, \c size, and -\c vector3d properties. It is inherited by NumberAnimation, ColorAnimation, -RotationAnimation and Vector3dAnimation: NumberAnimation provides a more -efficient implementation for animating \c real and \c int properties, and -Vector3dAnimation does the same for \c vector3d properties. ColorAnimation -and RotationAnimation provide more specific attributes for animating color -and rotation changes. +A QML object may have different easing curve for each property animation. There +are also different parameters to control the curve, some of which are exclusive +to a particular curve. For more information about the easing curves, visit the +\l {PropertyAnimation::easing.type}{easing} documentation. -A ColorAnimation allows color values for the \l {ColorAnimation::}{from} -and \l {ColorAnimation::}{to} properties. The -following animates the rectangle's \l {Rectangle::}{color} property: - -\snippet doc/src/snippets/declarative/animation-elements.qml color +The \l{declarative/animation/easing}{easing example} visually demonstrates each +of the different easing types. -RotationAnimation allows a rotation's direction to be specified. The following -animates the rectangle's \l {Item::rotation} property: +\section2 Other Animation Elements -\snippet doc/src/snippets/declarative/animation-elements.qml rotation +In addition, QML provides several other elements useful for animation: -In addition, the following specialized animation elements are available: +\list +\o PauseAnimation: enables pauses during animations +\o ScriptAction: allows JavaScript to be executed during an animation, and can +be used together with StateChangeScript to reused existing scripts +\o PropertyAction: changes a property \e immediately during an animation, +without animating the property change +\endlist +These are specialized animation elements that animate different property types \list -\o SmoothedAnimation: a specialized NumberAnimation that provides smooth +\o SmoothedAnimation: a specialized NumberAnimation that provides smooth changes in animation when the target value changes -\o SpringAnimation: provides a spring-like animation with specialized -attributes such as \l {SpringAnimation::}{mass}, +\o SpringAnimation: provides a spring-like animation with specialized +attributes such as \l {SpringAnimation::}{mass}, \l{SpringAnimation::}{damping} and \l{SpringAnimation::}{epsilon} \o ParentAnimation: used for animating a parent change (see ParentChange) \o AnchorAnimation: used for animating an anchor change (see AnchorChanges) \endlist -See their respective documentation pages for more details. - - -\section3 Easing - -Any PropertyAnimation-based animations can specify \l -{PropertyAnimation::easing.type}{easing attributes} to control the -easing curve applied when a property value is animated. These control the -effect of the animation on the property value, to provide visual effects like -bounce, acceleration and deceleration. - -For example, this modified version of an \l {Animations as Property Value -Sources}{earlier example} uses \c Easing.OutBounce to create a bouncing effect -when the animation reaches its target value: - -\snippet doc/src/snippets/declarative/animation-easing.qml 0 - -The \l{declarative/animation/easing}{easing example} visually demonstrates each -of the different easing types. +*/ -\section2 Grouping Animations -Multiple animations can be combined into a single animation using one of the -animation group elements: ParallelAnimation or SequentialAnimation. As their -names suggest, animations in a ParallelAnimation are run at the same time, -while animations in a SequentialAnimation are run one after the other. -To run multiple animations, define the animations within an animation group. -The following example creates a SequentialAnimation that runs three animations -one after the other: a NumberAnimation, a PauseAnimation and another -NumberAnimation. The SequentialAnimation is applied as a \l{Animations as -Property Value Sources}{property value source animation} on the image's \c y -property, so that the animation starts as soon as the image is loaded, moving -the image up and down: +\snippet doc/src/snippets/declarative/animation-elements.qml color +\snippet doc/src/snippets/declarative/animation-propertyvaluesource.qml 0 +\snippet doc/src/snippets/declarative/animation-signalhandler.qml 0 +\snippet doc/src/snippets/declarative/animation-standalone.qml 0 +\snippet doc/src/snippets/declarative/animation-transitions.qml 0 \snippet doc/src/snippets/declarative/animation-groups.qml 0 -\image propanim.gif - -Since the SequentialAnimation is applied to the \c y property, the individual -animations within the group are automatically applied to the \c y property as -well; it is not required to set their \l{PropertyAnimation::}{properties} -values to a particular property. - -Animation groups can be nested. Here is a rather complex animation making use -of both sequential and parallel animations: \snippet doc/src/snippets/declarative/animation-groups.qml 1 +\snippet doc/src/snippets/declarative/animation-groups.qml 0 +\image propanim.gif -Once individual animations are placed into a SequentialAnimation or -ParallelAnimation, they can no longer be started and stopped independently. The -sequential or parallel animation must be started and stopped as a group. - -See the \l {declarative/animation/basics}{Animation basics example} for a -demonstration of creating and combining multiple animations in QML. - - - -\section2 Other Animation Elements - -In addition, QML provides several other elements useful for animation: - -\list -\o PauseAnimation: enables pauses during animations -\o ScriptAction: allows JavaScript to be executed during an animation, and can -be used together with StateChangeScript to reused existing scripts -\o PropertyAction: changes a property \e immediately during an animation, -without animating the property change -\endlist - -See their respective documentation pages for more details. - -*/ diff --git a/doc/src/declarative/basicelements.qdoc b/doc/src/declarative/basicelements.qdoc new file mode 100644 index 0000000..0146591 --- /dev/null +++ b/doc/src/declarative/basicelements.qdoc @@ -0,0 +1,114 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qmlbasicelements.html +\ingroup qml-features +\contentspage QML Features +\previouspage QML Features +\nextpage {QML Basic Types}{Data Types} + +\title QML Basic Elements + +QML's basic elements allow the easy inclusion of objects into the +scene. + +\section1 Basic Elements +This is a list of some of the elements readily available for users. +\list +\o \l {Item} +\o \l {Rectangle} +\o \l {Image} +\o \l {Text} +\o \l {TextInput} +\o \l {TextEdit} +\o \l {FocusScope} +\o \l {Component} +\o \l {MouseArea} +\endlist + +For a complete list of QML elements, please visit the \l {QML Elements} page. + +\section1 Properties and Qt Declarative Module + +When using QML elements, keep in mind that elements may possess properties that +other elements also possess. This is because QML and its underlying engine is +implemented in C++ using Qt. More importantly, the chain of property inheritance +is directly due to QML's use of the \l {Qt Declarative Module} and Qt's +\l {Meta-Object System}{meta-object} and \l {The Property System}{property} systems. For example, visual elements that have C++ implementation are sublcasses of +\l {QDeclarativeItem}. As a result, elements such as \l {Rectangle} and +\l {Text} elements inherit properties such as \c clip and \c smooth. + +\section1 Item Element + +Many QML elements inherit \l Item properties. \c Item possesses important properties +such as \c focus, \c children, and dimension properties such as \c width and +\c height. Although \c Item has physical properties, it is not a visual element. +Using \c Item as the top-level QML element (as the screen) will not produce a +visual result, use the \l {Rectangle} element instead. Use the \c Item to create +opacity effects, such as when creating an invisible container to hold other +components. + +\section1 Rectangle Element + +The \l Rectangle element is the basic visual element, for displaying different +types of items onto the screen. The \c Rectangle is customizable and utilizes +other elements such as \l Gradient and \l BorderImage for displaying advanced +customized graphics. + +\section1 Image Element + +To insert an image into a QML scene, merely declare an \l Image element. The +\c Image element can load images in formats supported by Qt. + +\section1 Text Elements + +The \l Text and \l TextEdit elements display formatted text onto the screen. +\c TextEdit features multi-line editing while the \l TextInput element is for +single line text input. + +\keyword qml-top-level-component +\section1 Using Elements as the Top-Level Component + +For creating components (or displaying a simple scene), there are different +elements that could be used as the top-level component. To display a simple scene, +a \l Rectangle as the top-level component may suffice. \l Rectangle, +\l FocusScope, \l Component, \l {QML:QtObject} {QtObject}, \l Item, are some of +the commonly used elements as the top-level component. + +When importing components, the top-level component is important because the +top-level component's properties are the only properties exposed to the parent. + +For example, a \c Button component may be implemented using different elements as +its top-level component. When this component is loaded into another QML scene, +the component will retain the top-level component's properties. If a non-visual +component is the top-level component, the visual properties should be aliased to +the top-level to display the component properly. + +For more information on how to build upon QML elements, see the +\l{Importing Reusable Components} document. +*/ diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc index 8503f4e..4792bba 100644 --- a/doc/src/declarative/basictypes.qdoc +++ b/doc/src/declarative/basictypes.qdoc @@ -27,23 +27,26 @@ /*! \page qdeclarativebasictypes.html + \ingroup qml-features + \contentspage QML Features + \previouspage {QML Basic Elements} + \nextpage Property Binding \title QML Basic Types QML has a set of primitive types, as listed below, that are used throughout the \l {QML Elements}. - Some of these types can also be used for defining - \c property values in QML. See \l{Writing QML Components: Properties, Methods and Signals} for the - list of types that can be used for \c property values. - \annotatedlist qmlbasictypes + + To create additional types, such as data types created in C++, read the + \l{Extending QML Functionalities using C++} article. */ /*! \qmlbasictype int \ingroup qmlbasictypes - \brief An integer is a whole number, e.g. 0, 10, or -20. + \brief An integer is a whole number, e.g. 0, 10, or -20. An integer is a whole number, e.g. 0, 10, or -20. The possible \c int values range from around -2000000000 to around 2000000000, @@ -137,7 +140,7 @@ \qmlbasictype url \ingroup qmlbasictypes - \brief A URL is a resource locator, like a file name. + \brief A URL is a resource locator, like a file name. A URL is a resource locator, like a file name. It can be either absolute, e.g. "http://qt.nokia.com", or relative, e.g. @@ -150,9 +153,6 @@ Image { source: "pics/logo.png" } \endqml - \raw HTML - \endraw - \sa {QML Basic Types} */ @@ -215,7 +215,7 @@ /*! \qmlbasictype size \ingroup qmlbasictypes - + \brief A size type has width and height attributes A \c size type has \c width and \c height attributes. @@ -254,7 +254,7 @@ For example, to read the \l {Item::childrenRect.x}{Item::childrenRect} \c rect property: \qml - Rectangle { + Rectangle { width: childrenRect.width height: childrenRect.height @@ -290,7 +290,7 @@ MyDatePicker { minDate: "2000-01-01"; maxDate: "2020-12-31" } \endqml - To read a date value returned from a C++ extension class, use + To read a date value returned from a C++ extension class, use \l{QML:Qt::formatDate()}{Qt.formatDate()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}. \sa {QML Basic Types} @@ -309,7 +309,7 @@ MyTimePicker { time: "14:22:15" } \endqml - To read a time value returned from a C++ extension class, use + To read a time value returned from a C++ extension class, use \l{QML:Qt::formatTime()}{Qt.formatTime()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}. \sa {QML Basic Types} @@ -399,8 +399,9 @@ \c child1, \c child2 and \c child3 will be added to the children list in the order in which they appear. - List \l {Adding Properties}{properties} can be declared as \c list<Type> - type, where \c Type is the type of the object in the list: + List \l {Property Binding}{properties} can be created as a + \c variant type, or as a \c list<Type> type, where \c Type is the + type of the object in the list: \qml Item { @@ -503,7 +504,7 @@ \qml Item { - property variant attributes: { ''color': 'red', 'width': 100 } + property variant attributes: { 'color': 'red', 'width': 100 } Component.onCompleted: { // Change the value of attributes.color to 'blue': @@ -570,7 +571,7 @@ \qml Text { horizontalAlignment: "AlignRight" } \endqml - + or as \c {<Element>.<value>}: \qml Text { horizontalAlignment: Text.AlignRight } diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc index 3962514..93571bd 100644 --- a/doc/src/declarative/declarativeui.qdoc +++ b/doc/src/declarative/declarativeui.qdoc @@ -31,12 +31,10 @@ \ingroup qt-gui-concepts \brief Qt Quick provides a declarative framework for building highly -dynamic, custom user interfaces. - -\section1 Introduction +dynamic user interfaces. Qt Quick is a collection of technologies that are designed to help -developers create the kind of intuitive, modern-looking, fluid user +developers create the kind of intuitive, modern, fluid user interfaces that are increasingly used on mobile phones, media players, set-top boxes and other portable devices. @@ -45,115 +43,108 @@ language for describing user interfaces and a language runtime. A collection of C++ APIs is used to integrate these high level features with classic Qt applications. -\section2 QML, Elements and the Qt Declarative Module - -User interfaces and their behavior are described using QML, an extension to -\l{About JavaScript}{JavaScript} that lets developers and designers -use a declarative syntax to specify each user interface in terms of -\l{QML Elements}{QML elements}. These elements are a sophisticated set of -graphical and behavioral building blocks that can be combined together in -\l{QML Documents}{QML documents} to build components ranging in complexity -from simple buttons and sliders, to complete Internet-enabled applications. - -QML improves the integration between JavaScript and Qt's existing -QObject-based type system, adds support for automatic -\l{Property Binding}{property bindings} and provides -\l{Network Transparency}{network transparency} at the language level. - -The Qt Declarative module implements the interface between the QML language -and the elements available to it. It also provides a C++ API that can be -used to load and interact with QML files from within Qt applications. - -Qt Quick builds on \l{QML for Qt programmers}{Qt's existing strengths}. -QML can be be used to incrementally extend an existing application or -to build completely new applications. QML is fully -\l{Extending QML in C++}{extensible from C++} through the Qt Declarative -Module. - \section1 Getting Started \list -\o \l{What's new in Qt Quick} -\o \l{Introduction to the QML language} -\o \l{QML for Qt Programmers} +\o \l{Intro to Qt Quick}{Introduction to Qt Quick} +\o \l{QML for Qt Programmers}{QML Programming for Qt Programmers} \o \l{Getting Started Programming with QML} -\o \l{Intro to Qt Quick} -\endlist -\list -\o \l{QML Tutorial}{Tutorial: "Hello World"} -\o \l{QML Advanced Tutorial}{Tutorial: "Same Game"} +\o \l{What's new in Qt Quick}{What's New in the Qt Quick Release} \o \l{QML Examples and Demos} \endlist -\section1 QML Concepts +\section1 QML Features \list -\o \l{QML Documents} +\o \l{QML Basic Elements}{Basic Elements} +\o \l{QML Basic Types}{Data Types} \o \l{Property Binding} -\o \l{Anchor-Based Layout in QML} -\o \l{Writing QML Components: Properties, Methods and Signals} -\o \l{QML Scope} -\o \l{QML Modules} +\o \l{Using QML Positioner and Repeater Items}{Component Layouts} +\o \l{Anchor-based Layout in QML}{Layouts using Anchors} +\o \l{QML Mouse Events}{Mouse Events} +\o \l{QML Text Handling and Validators}{Text Handling and Validators} +\o \l{Keyboard Focus in QML}{Keyboard Focus} +\o \l{QML Signal and Handler Event System}{Signal and Handler Event System} +\o \l{Importing Reusable Components} +\o \l{QML States}{States} +\o \l{QML Animation and Transitions}{Animation and Transitions} +\o \l{QML Data Models}{Structuring Data with Models} +\o \l{Presenting Data with Views} +\o \l{Extending QML Functionalities using C++} +\o \l{Using QML Bindings in C++ Applications} +\o \l{Integrating QML Code with Existing Qt UI Code} +\o \l{Dynamic Object Management in QML}{Dynamic Object Management} +\o \l{Network Transparency}{Loading Resources in QML} +\o \l{QML Internationalization}{Internationalization} \endlist -\section1 User Interaction +\section1 QML Add-Ons \list -\o \l{Keyboard Focus in QML} -\o \l{QML States} -\o \l{QML Animation} +\o \l{QtWebKit QML Module} +\o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/qml-plugins.html}{Mobility QML Plugins} \endlist -\section1 Handling Data +\section1 Qt Quick Tools \list -\o \l{QML Basic Types}{QML Basic Data Types} -\o \l{Using QML Positioner and Repeater Items} -\o \l{QML Data Models} -\o \l{Presenting Data with QML} -\o \l{Network Transparency} +\o \l{Debugging QML} +\o \l{external: Developing Qt Quick Applications with Creator}{Developing with Qt Creator} +\o \l{QML Viewer} \endlist -\section1 Architecture +\section1 Reference \list -\o \l{Qt Declarative UI Runtime} -\o \l{Integrating JavaScript} -\o \l{Dynamic Object Management in QML} +\o \l{Introduction to the QML language}{QML Syntax} +\o \l{QML Elements} +\o \l{Qt Declarative Module} +\o \l{QML Basic Types}{QML Data Types} +\o \l{QML Coding Conventions} +\o \l{external: Qt Creator Manual}{Qt Creator Manual} +\o \l{Programming with Qt} +\o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/index.html}{Qt Mobility Documentation} \endlist -\section1 Using QML with C++ +\section1 Architecture \list \o \l{Qt Declarative UI Runtime} -\o \l{Using QML in C++ Applications} -\o \l{Integrating QML with existing Qt UI code} -\o \l{Tutorial: Writing QML extensions with C++} -\o \l{Extending QML in C++} -\endlist - -\section1 Reference - -\list -\o \l{QML Elements} -\o \l{QML Basic Types} +\o \l{Integrating JavaScript} +\o \l{QML Scope} +\o \l{QML Modules} +\o \l{QML Documents} \o \l{QML Global Object} \o \l{QML Internationalization} \o \l{QML Right-to-left User Interfaces} \o \l{QML Security} \o \l{Qt Declarative Module} -\o \l{Debugging QML} -\o \l{QML Viewer} -\o \l{QML Performance} -\o \l{QML Coding Conventions} \endlist -\section1 Online Examples +\section1 Examples \list +\o \l{QML Tutorial}{"Hello World" Tutorial} +\o \l{Getting Started Programming with QML} +\o \l{QML Advanced Tutorial}{Tutorial: "Same Game"} +\o \l{Tutorial: Writing QML extensions with C++} +\o \l{QML Examples and Demos} + \o Forum Nokia: \l{http://wiki.forum.nokia.com/index.php/Qt_Quick_examples_for_porting}{Qt Quick examples for porting} \endlist + +\section1 Best Practices + +\list +\o \l{QML Best Practices: Coding Conventions}{Coding Tips} +\o \l{QML Performance}{Performance Tips} +\endlist + +\section1 License Information +\list +\o \l{Qt Quick Licensing Information} +\endlist */ diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc index f2ca0fd..90fb715 100644 --- a/doc/src/declarative/dynamicobjects.qdoc +++ b/doc/src/declarative/dynamicobjects.qdoc @@ -27,13 +27,17 @@ /*! \page qdeclarativedynamicobjects.html +\ingroup qml-features +\contentspage {QML Features} +\previouspage {Integrating QML Code with Existing Qt UI Code} +\nextpage {Network Transparency}{Loading Resources in QML} \title Dynamic Object Management in QML -QML provides a number of ways to dynamically create and manage QML objects. +QML provides a number of ways to dynamically create and manage QML objects. The \l{Loader}, \l{Repeater}, \l{ListView}, \l{GridView} and \l{PathView} elements -all support dynamic object management. Objects can also be created and managed +all support dynamic object management. Objects can also be created and managed from C++, and this is the preferred method for hybrid QML/C++ applications -(see \l{Using QML in C++ Applications}). +(see \l{Using QML Bindings in C++ Applications}). QML also supports the dynamic creation of objects from within JavaScript code. This is useful if the existing QML elements do not fit the needs of your @@ -45,24 +49,24 @@ of the concepts discussed on this page. \section1 Creating Objects Dynamically -There are two ways to create objects dynamically from JavaScript. You can either call +There are two ways to create objects dynamically from JavaScript. You can either call \l {QML:Qt::createComponent()}{Qt.createComponent()} to dynamically create a \l Component object, or use \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} to create an item from a string of QML. -Creating a component is better if you have an existing component defined in a \c .qml +Creating a component is better if you have an existing component defined in a \c .qml file, and you want to dynamically create instances of that component. Otherwise, -creating an item from a string of QML is useful when the item QML itself is generated +creating an item from a string of QML is useful when the item QML itself is generated at runtime. -\section2 Creating a Component dynamically +\section2 Creating a Component Dynamically -To dynamically load a component defined in a QML file, call the -\l {QML:Qt::createComponent()}{Qt.createComponent()} function on the \l{QML Global Object}. +To dynamically load a component defined in a QML file, call the +\l {QML:Qt::createComponent()}{Qt.createComponent()} function on the \l{QML Global Object}. This function takes the URL of the QML file as its only argument and creates a \l Component object from this URL. -Once you have a \l Component, you can call its \l {Component::createObject()}{createObject()} method to create an instance of +Once you have a \l Component, you can call its \l {Component::createObject()}{createObject()} method to create an instance of the component. This function can take one or two arguments: \list \o The first is the parent for the new item. Since graphical items will not appear on the scene without a parent, it is @@ -96,25 +100,27 @@ in case the QML file is loaded over a network and thus is not ready immediately. \codeline \snippet doc/src/snippets/declarative/componentCreation.js finishCreation -If you are certain the QML file to be loaded is a local file, you could omit the \c finishCreation() +If you are certain the QML file to be loaded is a local file, you could omit the \c finishCreation() function and call \l {Component::createObject()}{createObject()} immediately: \snippet doc/src/snippets/declarative/componentCreation.js func \snippet doc/src/snippets/declarative/componentCreation.js local \snippet doc/src/snippets/declarative/componentCreation.js func-end -Notice in both instances, \l {Component::createObject()}{createObject()} is called with +Notice in both instances, \l {Component::createObject()}{createObject()} is called with \c appWindow passed as an argument so that the created object will become a child of the \c appWindow item in \c main.qml. Otherwise, the new item will not appear in the scene. When using files with relative paths, the path should be relative to the file where \l {QML:Qt::createComponent()}{Qt.createComponent()} is executed. -To connect signals to (or receive signals from) dynamically created objects, use the signal -\c connect() method. See \l {Connecting signals to methods and other signals} for more information. +To connect signals to (or receive signals from) dynamically created objects, +use the signal \c connect() method. See +\l{QML Signal and Handler Event System#Connecting Signals to Methods and Signals} +{Connecting Signals to Methods and Signals} for more information. -\section2 Creating an object from a string of QML +\section2 Creating an Object from a String of QML If the QML is not defined until runtime, you can create a QML item from a string of QML using the \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} function, as in the following example: @@ -164,7 +170,7 @@ items that you did not dynamically create yourself. Items can be deleted using the \c destroy() method. This method has an optional argument (which defaults to 0) that specifies the approximate delay in milliseconds -before the object is to be destroyed. +before the object is to be destroyed. Here is an example. The \c application.qml creates five instances of the \c SelfDestroyingRect.qml component. Each instance runs a NumberAnimation, and when the animation has finished, calls @@ -198,7 +204,7 @@ Item { } \endqml -This would result in an error, since items can only be dynamically +This would result in an error, since items can only be dynamically destroyed if they were dynamically created. Objects created with \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} @@ -206,6 +212,4 @@ can similarly be destroyed using \c destroy(): \snippet doc/src/snippets/declarative/createQmlObject.qml 0 \snippet doc/src/snippets/declarative/createQmlObject.qml destroy - */ - diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc index e2d9350..8fb64c1 100644 --- a/doc/src/declarative/elements.qdoc +++ b/doc/src/declarative/elements.qdoc @@ -31,7 +31,8 @@ \title QML Elements \brief A listing of standard QML elements. -These are the functionally grouped lists of QML elements. +These are the functionally grouped lists of QML elements as part of +\l{Qt Quick}. Elements are declared with the their name and two curly braces. Elements may be nested in elements, thereby creating a parent-child relationship between the @@ -44,7 +45,7 @@ To see the QML elements listed by functional area, see the \list \o \l {Item} - Basic item element inherited by QML elements \o \l {Component} - Encapsulates QML elements during importing -\o \l {QML:QtObject} {QtObject} - Basic element containing only the objectName property +\o \l {QML:QtObject} {QtObject} - Basic element containing only the \c {objectName} property \endlist \section1 Graphics @@ -54,7 +55,7 @@ To see the QML elements listed by functional area, see the \o \l {BorderImage} - Allows the use of images as borders \o \l {AnimatedImage} - For playing animations stored in a series of frames \o \l {Gradient} - For defining a color gradient -\o \l {GradientStop} - Used to define a color within a \l {Gradient} +\o \l {GradientStop} - Used to define a color within a \l {Gradient} \o \l {SystemPalette} - Provides access to the Qt palettes \endlist @@ -74,7 +75,7 @@ To see the QML elements listed by functional area, see the \o \l {MouseArea} - Sets up an area for mouse interaction \o \l {Keys} - Provides components with attached properties to handle key input. \o \l {FocusScope} - Element that mediate keyboard focus changes -\o \l {Flickable} - Provides a surface that can be "flicked" +\o \l {Flickable} - Provides a surface that can be "flicked" \o \l {Flipable} - Provides a surface that produces "flipping" effects \o \l {PinchArea} - Enables simple pinch gesture handling \endlist diff --git a/doc/src/declarative/example-slideswitch.qdoc b/doc/src/declarative/example-slideswitch.qdoc index 27c8f58..201ff2b 100644 --- a/doc/src/declarative/example-slideswitch.qdoc +++ b/doc/src/declarative/example-slideswitch.qdoc @@ -33,8 +33,6 @@ This example shows how to create a reusable switch component in QML. The code for this example can be found in the \c $QTDIR/examples/declarative/ui-components/slideswitch directory. -\section1 Overview - The elements that compose the switch are: \list @@ -123,7 +121,7 @@ For more information on scripts see \l{Integrating JavaScript}. At this point, when the switch toggles between the two states the knob will instantly change its \c x position between 1 and 78. In order for the the knob to move smoothly we add a transition that will animate the \c x property with an easing curve for a duration of 200ms. -For more information on transitions see \l{qdeclarativeanimation.html#transitions}{QML Transitions}. +For more information on transitions see \l{QML Animation and Transitions}. \section1 Usage The switch can be used in a QML file, like this: diff --git a/doc/src/declarative/examples.qdoc b/doc/src/declarative/examples.qdoc index b359877..b7420e0 100644 --- a/doc/src/declarative/examples.qdoc +++ b/doc/src/declarative/examples.qdoc @@ -146,7 +146,6 @@ The examples can be found in Qt's \c examples/declarative directory. \section2 Touch Interaction \list -\o \l{declarative/touchinteraction/gestures}{Gestures} \o \l{declarative/touchinteraction/mousearea}{MouseArea} \endlist diff --git a/doc/src/declarative/extending-tutorial.qdoc b/doc/src/declarative/extending-tutorial.qdoc index 4caa631..0ddc430 100644 --- a/doc/src/declarative/extending-tutorial.qdoc +++ b/doc/src/declarative/extending-tutorial.qdoc @@ -27,13 +27,13 @@ /*! \page qml-extending-tutorial-index.html -\title Tutorial: Writing QML extensions with C++ +\title Tutorial: Writing QML Extensions with C++ The Qt Declarative module provides a set of APIs for extending QML through C++ extensions. You can write extensions to add your own QML types, extend existing Qt types, or call C/C++ functions that are not accessible from ordinary QML code. -This tutorial shows how to write a QML extension using C++ that includes +This tutorial shows how to write a QML extension using C++ that includes core QML features, including properties, signals and bindings. It also shows how extensions can be deployed through plugins. @@ -45,7 +45,7 @@ Tutorial chapters: \list 1 \o \l{declarative/tutorials/extending/chapter1-basics}{Creating a New Type} \o \l{declarative/tutorials/extending/chapter2-methods}{Connecting to C++ Methods and Signals} -\o \l{declarative/tutorials/extending/chapter3-bindings}{Adding Property Bindings} +\o \l{declarative/tutorials/extending/chapter3-bindings}{Property Binding} \o \l{declarative/tutorials/extending/chapter4-customPropertyTypes}{Using Custom Property Types} \o \l{declarative/tutorials/extending/chapter5-listproperties}{Using List Property Types} \o \l{declarative/tutorials/extending/chapter6-plugins}{Writing an Extension Plugin} @@ -67,18 +67,18 @@ like network programming that are not accessible through built-in QML features. In this tutorial, we will show how to use the C++ classes in the Qt Declarative module to extend QML. The end result will be a simple Pie Chart display implemented by -several custom QML types connected together through QML features like bindings and +several custom QML types connected together through QML features like bindings and signals, and made available to the QML runtime through a plugin. To begin with, let's create a new QML type called "PieChart" that has two properties: a name and a color. We will make it available in a \l {Modules}{module} called "Charts", with -a module version of 1.0. +a module version of 1.0. We want this \c PieChart type to be usable from QML like this: \code import Charts 1.0 - + PieChart { width: 100; height: 100 name: "A simple pie chart" @@ -99,16 +99,16 @@ Here is our \c PieChart class, defined in \c piechart.h: \snippet declarative/tutorials/extending/chapter1-basics/piechart.h 0 -The class inherits from QDeclarativeItem because we want to override +The class inherits from QDeclarativeItem because we want to override QDeclarativeItem::paint() in order to draw. If the class just represented some data type and was not an item that actually needed to be displayed, it could simply inherit -from QObject. Or, if we want to extend the functionality of an existing QObject-based +from QObject. Or, if we want to extend the functionality of an existing QObject-based class, it could inherit from that class instead. The \c PieChart class defines the two properties, \c name and \c color, with the Q_PROPERTY macro, -and overrides QDeclarativeItem::paint(). The class implementation in \c piechart.cpp -simply sets and returns the \c m_name and \c m_color values as appropriate, and -implements \c paint() to draw a simple pie chart. It also turns off the +and overrides QDeclarativeItem::paint(). The class implementation in \c piechart.cpp +simply sets and returns the \c m_name and \c m_color values as appropriate, and +implements \c paint() to draw a simple pie chart. It also turns off the QGraphicsItem::ItemHasNoContents flag to enable painting: \snippet declarative/tutorials/extending/chapter1-basics/piechart.cpp 0 @@ -150,19 +150,19 @@ Try it yourself with the code in Qt's \c examples/tutorials/extending/chapter1-b At the moment, the \c app.qml is run from within a C++ application. This may seem odd if you're used to running QML files with the \l {QML Viewer}. -Later on, we'll show how to create a plugin so that you can run \c app.qml using the +Later on, we'll show how to create a plugin so that you can run \c app.qml using the \l {QML Viewer} instead. */ /*! -\title Chapter 2: Connecting to C++ Methods and Signals +\title Chapter 2: Connecting to C++ Methods and Signals \example declarative/tutorials/extending/chapter2-methods Suppose we want \c PieChart to have a "clearChart()" method that erases the -chart and then emits a "chartCleared" signal. Our \c app.qml would be able +chart and then emits a "chartCleared" signal. Our \c app.qml would be able to call \c clearChart() and receive \c chartCleared() signals like this: \snippet declarative/tutorials/extending/chapter2-methods/app.qml 0 @@ -210,7 +210,7 @@ Property bindings is a powerful feature of QML that allows values of different elements to be synchronized automatically. It uses signals to notify and update other elements' values when property values are changed. -Let's enable property bindings for the \c color property. That means +Let's enable property bindings for the \c color property. That means if we have code like this: \snippet declarative/tutorials/extending/chapter3-bindings/app.qml 0 @@ -224,7 +224,7 @@ updates to the same value. When the window is clicked, the \c onClicked handler in the MouseArea changes the color of \c chartA, thereby changing both charts to the color blue. -It's easy to enable property binding for the \c color property. +It's easy to enable property binding for the \c color property. We add a \l{Qt's Property System}{NOTIFY} feature to its Q_PROPERTY() declaration to indicate that a "colorChanged" signal is emitted whenever the value changes. @@ -244,7 +244,7 @@ It's important for \c setColor() to check that the color value has actually chan before emitting \c colorChanged(). This ensures the signal is not emitted unnecessarily and also prevents loops when other elements respond to the value change. -The use of bindings is essential to QML. You should always add NOTIFY +The use of bindings is essential to QML. You should always add NOTIFY signals for properties if they are able to be implemented, so that your properties can be used in bindings. Properties that cannot be bound cannot be automatically updated and cannot be used as flexibly in QML. Also, since @@ -286,7 +286,7 @@ int-type property to store an identifier for each chart: \endcode We can also use various other property types. QML has built-in support for the types -listed in the \l{Adding Properties} documentation, which includes the following: +listed in the \l{QML Basic Types} documentation, which includes the following: \list \o bool, unsigned int, int, float, double, qreal @@ -299,7 +299,7 @@ listed in the \l{Adding Properties} documentation, which includes the following: If we want to create a property whose type is not supported by QML by default, we need to register the type with QML. -For example, let's replace the use of the \c property with a type called +For example, let's replace the use of the \c property with a type called "PieSlice" that has a \c color property. Instead of assigning a color, we assign an \c PieSlice value which itself contains a \c color: @@ -358,10 +358,10 @@ have a \c slices property that accepts a list of \c PieSlice items: \image extending-tutorial-chapter5.png To do this, we replace the \c pieSlice property in \c PieChart with a \c slices property, -declared as a QDeclarativeListProperty type. The QDeclarativeListProperty class enables the +declared as a QDeclarativeListProperty type. The QDeclarativeListProperty class enables the creation of list properties in QML extensions. We replace the \c pieSlice() -function with a \c slices() function that returns a list of slices, and add -an internal \c append_slice() function (discussed below). We also use a QList to +function with a \c slices() function that returns a list of slices, and add +an internal \c append_slice() function (discussed below). We also use a QList to store the internal list of slices as \c m_slices: \snippet declarative/tutorials/extending/chapter5-listproperties/piechart.h 0 @@ -409,7 +409,7 @@ To create a plugin library, we need: \list \o A plugin class that registers our QML types -\o A project file that describes the plugin +\o A project file that describes the plugin \o A \l{Writing a qmldir file}{qmldir} file that tells the QML engine to load the plugin \endlist @@ -468,8 +468,9 @@ In this tutorial, we've shown the basic steps for creating a QML extension: \endlist -The \l {Extending QML in C++} reference documentation shows other useful features that can be added to -QML extensions. For example, we could use \l{Default Property}{default properties} to allow +The \l {Extending QML Functionalities using C++} reference documentation shows +other useful features that can be added to QML extensions. For example, we +could use \l{Default Property}{default properties} to allow slices to be added without using the \c slices property: \code @@ -489,7 +490,8 @@ Or randomly add and remove slices from time to time using \l{Property Value Sour \endcode -See the \l{Extending QML in C++}{reference documentation} for more information. +See the \l{Extending QML Functionalities using C++} reference documentation +for more information. */ diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc index 80b6e72..c417c04 100644 --- a/doc/src/declarative/extending.qdoc +++ b/doc/src/declarative/extending.qdoc @@ -27,7 +27,11 @@ /*! \page qml-extending.html -\title Extending QML in C++ +\ingroup qml-features +\contentspage QML Features +\previouspage {Presenting Data with Views} +\nextpage {Using QML Bindings in C++ Applications} +\title Extending QML Functionalities using C++ The QML syntax declaratively describes how to construct an in-memory object tree. In Qt, QML is mainly used to describe a visual scene graph, but it is @@ -82,7 +86,7 @@ Types can be registered by libraries, application code, or by plugins Once registered, all \l {Qt's Property System}{properties} of the supported types are available in QML. QML has intrinsic support for -properties of the types listed in the \l{Adding Properties} +properties of the types listed in the \l{QML Basic Types} document, which includes the following: \list @@ -429,28 +433,28 @@ pointers to invalid objects. QML makes the following guarentees: \list \o An object assigned to a QObject (or QObject-derived) pointer property will be -valid at the time of assignment. +valid at the time of assignment. -Following assignment, it is the responsibility of the class to subsequently guard +Following assignment, it is the responsibility of the class to subsequently guard this pointer, either through a class specific method or the generic QPointer class. -\o An object assigned to a QVariant will be valid at the time of assignment. +\o An object assigned to a QVariant will be valid at the time of assignment. -When assigning an object to a QVariant property, QML will always use a QMetaType::QObjectStar -typed QVariant. It is the responsibility of the class to guard the pointer. A -general rule when writing a class that uses QVariant properties is to check the -type of the QVariant when it is set and if the type is not handled by your class, +When assigning an object to a QVariant property, QML will always use a QMetaType::QObjectStar +typed QVariant. It is the responsibility of the class to guard the pointer. A +general rule when writing a class that uses QVariant properties is to check the +type of the QVariant when it is set and if the type is not handled by your class, reset it to an invalid variant. -\o An object assigned to a QObject (or QObject-derived) list property will be -valid at the time of assignment. +\o An object assigned to a QObject (or QObject-derived) list property will be +valid at the time of assignment. -Following assignment, it is the responsibility of the class to subsequently guard +Following assignment, it is the responsibility of the class to subsequently guard this pointer, either through a class specific method or the generic QPointer class. \endlist Elements should assume that any QML assigned object can be deleted at any time, and -respond accordingly. If documented as such an element need not continue to work in +respond accordingly. If documented as such an element need not continue to work in this situation, but it must not crash. \section1 Signal Support @@ -477,7 +481,7 @@ but different parameters cannot be distinguished. 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 +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. @@ -498,7 +502,7 @@ on<Property-name>Changed, regardless of the name used for the NOTIFY signal in C++. We recommend using <property-name>Changed() for the NOTIFY signal in C++. -See also \l {Writing QML Components: Properties, Methods and Signals} +See also \l {Importing Reusable Components} \section1 Methods @@ -701,478 +705,4 @@ public: } }; \endcode - -*/ - -/*! -\page qml-extending-types.html -\title Writing QML Components: Properties, Methods and Signals - -One of the key concepts in QML is the ability to define your own QML components that suit -the purposes of your application. The standard \l {QML Elements} provide the essential components -for creating a QML application; beyond these, you can write your own custom components that can -be created and reused, without the use of C++. - -Components are the building blocks of a QML project. When writing a QML application, whether -large or small, it is best to separate QML code into smaller components that perform specific -sets of operations, instead of creating mammoth QML files with large, combined functionality -that is more difficult to manage and may contain duplicated code. - - -\section1 Defining New Components - -A component is a reusable type with a well-defined interface, built entirely in QML. -Any snippet of QML code can become a component, by placing the code in a file "<Name>.qml" where -<Name> is the new component name, beginning with an uppercase letter. These QML files automatically -become available as new QML element types to other QML components and applications in the same directory. - -For example, one of the simplest and most common components you can build in QML is a -button-type component. Below, we implement this component as a \l Rectangle with a clickable -\l MouseArea, in a file named \c Button.qml: - -\snippet doc/src/snippets/declarative/qml-extending-types/components/Button.qml 0 - -Now this component can be reused by another file within the same directory. Since the file is -named \c Button.qml, the component is referred to as \c Button: - -\table -\row -\o \snippet doc/src/snippets/declarative/qml-extending-types/components/application.qml 0 -\o \image qml-extending-types.png -\endtable - -The root object in \c Button.qml defines the attributes that are available to users of the -\c Button component. In this case, the root object is a \l Rectangle, so any properties, methods -and signals of \l Rectangle are made available, allowing \c application.qml to -customize the \c width, \c height, \c radius and \c color properties of \c Button objects. - - -If \c Button.qml was not in the same directory, \c application.qml would need to load it as a -\l {Modules}{module} from a specific filesystem path or \l{QDeclarativeExtensionPlugin}{plugin}. -Also, note the letter case of the component file name is significant on some (notably UNIX) -filesystems. It is recommended the file name case matches the case of the QML component name -exactly - for example, \c Box.qml and not \c BoX.qml - regardless of the platform to which the -QML component will be deployed. - -To write a useful component, it is generally necessary to provide it with custom attributes that store and -communicate specific data. This is achieved by adding the following attributes to your components: - -\list -\o \bold Properties that can be accessed externally to modify an object (for example, \l Item has - \l {Item::}{width} and \l {Item::}{height} properties) and used in \l {Property Binding} -\o \bold Methods of JavaScript code can be invoked internally or externally (for example, - \l Animation has a \l {Animation::}{start()} method) -\o \bold Signals to notify other objects when an event has occurred (for example, MouseArea has a - \c clicked signal) -\endlist - -The following sections show how these attributes can be added to QML components. - - -\section1 Adding Properties - -A property is a value of a QML component that can be read and modified by other objects. For -example, a \l Rectangle component has \l {Item::}{width}, \l {Item::}{height} and \l -{Rectangle::}{color} properties. Significantly, properties be used with \l {Property Binding}, where -a property value is automatically updated using the value of another property. - -The syntax for defining a new property is: - -\code -[default] property <type> <name>[: defaultValue] -\endcode - -A \c property declaration can appear anywhere within a QML component definition, but it is customary -to place it at the top. A component cannot declare more than one property with the same name. (It is -possible to have a property name that is the same as an existing property in a type, but this is not -recommended as the existing property becomes hidden and inaccessible.) - -Below is an example. The \c ImageViewer component has defined a \c string type property named -\c currentImage, and its initial value is "default-image.png". This property is used to set the image -displayed in the child \l Image object. Another file, \c application.qml, can create -an \c ImageViewer object and read or modify the \c currentImage value: - -\table -\row -\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/ImageViewer.qml 0 -\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/application.qml 0 -\endtable - -It is optional for a property to have a default value. The default value is a convenient shortcut, and is -behaviorally identical to doing it in two steps, like this: - -\qml -Item { - // Use default value - property int myProperty: 10 - - // Longer, but behaviorally identical - property int myProperty - myProperty: 10 -} -\endqml - - -\section2 Supported property types - -All QML properties are typed. The examples above show properties with \c int and \c string types; -notice that the type of the property must be declared. The type is used to determine the property -behavior, and how the property is defined in C++. - -A number of property types are supported by default. These are listed in the table below, -with their default values and the corresponding C++ type: - -\table -\header \o QML Type Name \o Default value \o C++ Type Name -\row \o \l int \o 0 \o int -\row \o \l bool \o \c false \o bool -\row \o \l double \o 0.0 \o double -\row \o \l real \o 0.0 \o double -\row \o \l string \o "" (empty string) \o QString -\row \o \l url \o "" (empty url) \o QUrl -\row \o \l color \o #000000 (black) \o QColor -\row \o \l date \o \c undefined \o QDateTime -\row \o \l variant \o \c undefined \o QVariant -\endtable - -QML object types can also be used as property types. This includes -\l {Defining new QML elements}{custom QML types} implemented in C++. Such properties are -defined like this: - -\qml -Item { - property Item itemProperty - property QtObject objectProperty - property MyCustomType customProperty -} -\endqml - -Such object-type properties default to an \c undefined value. - -It is also possible to store a copy of a JavaScript object using the \c variant -property type. This creates some restrictions on how the property should be used; -see the \l {variant}{variant type documentation} for details. - -\l{list}{List properties} are created with the \c list<Type> syntax, and default to an empty -list: - -\qml -Item { - property list<Item> listOfItems -} -\endqml - -Note that list properties cannot be modified like ordinary JavaScript -arrays. See the \l {list}{list type documentation} for details. - - -\section2 Property change signals - -Adding a \c property to an item automatically adds a \e {value changed} -signal handler to the item. To connect to this signal, use a \l {Signal Handlers}{signal handler} -named with the \c on<Property>Changed syntax, using upper case for the first letter of the -property name. - -For example, the following \c onMyNumberChanged signal handler is automatically called whenever the -\c myNumber property changes: - -\snippet doc/src/snippets/declarative/qml-extending-types/properties/property-signals.qml 0 - - -\section2 Default properties - -The optional \c default attribute for a property marks it as the \e {default property} -for a type. This allows other items to specify the default property's value -as child elements. For example, the \l Item element's default property is its -\l{Item::children}{children} property. This allows the children of an \l Item -to be set like this: - -\qml -Item { - Rectangle {} - Rectangle {} -} -\endqml - -If the \l{Item::children}{children} property was not the default property for -\l Item, its value would have to be set like this instead: - -\qml -Item { - children: [ - Rectangle {}, - Rectangle {} - ] -} -\endqml - -See the \l{declarative/ui-components/tabwidget}{TabWidget} example for a -demonstration of using default properties. - -Specifying a default property overrides any existing default property (for -example, any default property inherited from a parent item). Using the -\c default attribute twice in the same type block is an error. - - -\section2 Property aliases - -Property aliases are a more advanced form of property declaration. Unlike a -property definition, which allocates a new, unique storage space for the -property, a property alias connects the newly declared property (called the -aliasing property) as a direct reference to an existing property (the aliased property). Read -operations on the aliasing property act as read operations on the aliased -property, and write operations on the aliasing property as write operations on -the aliased property. - -A property alias declaration looks a lot like an ordinary property definition: -\code - [default] property alias <name>: <alias reference> -\endcode - -As the aliasing property has the same type as the aliased property, an explicit -type is omitted, and the special "alias" keyword is used. Instead of a default -value, a property alias includes a compulsory alias reference. The alias -reference is used to locate the aliased property. While similar to a property -binding, the alias reference syntax is highly restricted. - -An alias reference takes one of the following forms: -\code - <id>.<property> - <id> -\endcode - -where <id> must refer to an object id within the same component as the type -declaring the alias, and, optionally, <property> refers to a property on that object. - -For example, below is a \c Button.qml component with a \c buttonText aliased property which is -connected to the child Text object's \c text property: - -\snippet doc/src/snippets/declarative/qml-extending-types/properties/alias.qml 0 - -The following code would create a \c Button with a defined text string for the -child \l Text object: - -\qml -Button { buttonText: "This is a button" } -\endqml - -Here, modifying \c buttonText directly modifies the \c textItem.text value; it does not -change some other value that then updates \c textItem.text. - -In this case, the use of aliased properties is essential. If \c buttonText was not an alias, -changing its value would not actually change the displayed text at all, as -\l {Property Binding}{property bindings} are not bi-directional: the \c buttonText value would -change when \c textItem.text changes, but not the other way around. - -Aliased properties are also useful for allowing external objects to directly modify and -access child objects in a component. For example, here is a modified version of the \c ImageViewer -component shown \l {Adding Properties}{earlier} on this page. The \c currentImage property has -been changed to an alias to the child \l Image object: - -\table -\row -\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/alias/ImageViewer.qml 0 -\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/alias/application.qml 0 -\endtable - -Instead of being limited to setting the \l Image source, \c application.qml can now directly -access and modify the child \l Image object and its properties. - -Obviously, exposing child objects in this manner should be done with care, as it allows external -objects to modify them freely. However, this use of aliased properties can be quite useful in -particular situations, such as for the \l {declarative/ui-components/tabwidget}{TabWidget} -example, where new tab items are actually parented to a child object that displays the current tab. - - -\section3 Considerations for property aliases - -Aliases are only activated once the component specifying them is completed. The -most obvious consequence of this is that the component itself cannot generally -use the aliased property directly during creation. For example, this will not work: - -\code - // Does NOT work - property alias buttonText: textItem.text - buttonText: "Some text" // buttonText is not yet defined when this value is set -\endcode - -A second, much less significant, consequence of the delayed activation of -aliases is that an alias reference cannot refer to another aliasing property -declared within the same component. This will not work: - -\code - // Does NOT work - id: root - property alias buttonText: textItem.text - property alias buttonText2: root.buttonText -\endcode - -At the time the component is created, the \c buttonText value has not yet been assigned, -so \c root.buttonText would refer to an undefined value. (From outside the component, -however, aliasing properties appear as regular Qt properties and consequently can be -used in alias references.) - -It is possible for an aliased property to have the same name as an existing property. For example, -the following component has a \c color alias property, named the same as the built-in -\l {Rectangle::color} property: - -\snippet doc/src/snippets/declarative/qml-extending-types/properties/alias-override.qml 0 - -Any objects that use this component and refer to its \c color property will be -referring to the alias rather than the ordinary \l {Rectangle::color} property. Internally, -however, the rectangle can correctly set this property to "red" and refer to the actual defined -property rather than the alias. - - -\section1 Adding Methods - -A QML component can define methods of JavaScript code. These methods can be invoked -either internally or by other objects. - -The syntax for defining a method is: - -\code -function <name>([<parameter name>[, ...]]) { <body> } -\endcode - -This declaration may appear anywhere within a type body, but it is customary to -include it at the top. Attempting to declare two methods or signals with the -same name in the same type block is an error. However, a new method may reuse -the name of an existing method on the type. (This should be done with caution, -as the existing method may be hidden and become inaccessible.) - -Unlike \l{Adding Signals}{signals}, method parameter types do not have to be declared as they -default to the \c variant type. The body of the method is written in JavaScript and may access -the parameters by name. - -Here is an example of a component with a \c say() method that accepts a single \c text argument: - -\snippet doc/src/snippets/declarative/qml-extending-types/methods/app.qml 0 - -A method can be connected to a signal so that it is automatically invoked whenever the signal -is emitted. See \l {Connecting signals to methods and other signals} below. - -Also see \l {Integrating JavaScript} for more information on using JavaScript with QML. - - -\section1 Adding Signals - -Signals provide a way to notify other objects when an event has occurred. For example, the MouseArea -\c clicked signal notifies other objects that the mouse has been clicked within the area. - -The syntax for defining a new signal is: - -\code -signal <name>[([<type> <parameter name>[, ...]])] -\endcode - -This declaration may appear anywhere within a type body, but it is customary to -include it at the top. Attempting to declare two signals or methods with the -same name in the same type block is an error. However, a new signal may reuse -the name of an existing signal on the type. (This should be done with caution, -as the existing signal may be hidden and become inaccessible.) - -Here are three examples of signal declarations: - -\code -Item { - signal clicked - signal hovered() - signal performAction(string action, variant actionArgument) -} -\endcode - -If the signal has no parameters, the "()" brackets are optional. If parameters are used, the -parameter types must be declared, as for the \c string and \c variant arguments for the \c -performAction signal above; the allowed parameter types are the same as those listed in the \l -{Adding Properties} section on this page. - -Adding a signal to an item automatically adds a \l {Signal Handlers}{signal handler} as well. -The signal hander is named \c on<SignalName>, with the first letter of the signal being upper -cased. The above example item would now have the following signal handlers: - -\list -\o onClicked -\o onHovered -\o onPerformAction -\endlist - -To emit a signal, simply invoke it in the same way as a method. Below left, when the \l MouseArea is -clicked, it emits the parent \c buttonClicked signal by invoking \c rect.buttonClicked(). The -signal is received by \c application.qml through an \c onButtonClicked signal handler: - -\table -\row -\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/basic.qml 0 -\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/no-parameters.qml 0 -\endtable - -If the signal has parameters, they are accessible by parameter name in the signal handler. -In the example below, \c buttonClicked is emitted with \c xPos and \c yPos parameters instead: - -\table -\row -\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/Button.qml 0 -\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/parameters.qml 0 -\endtable - - -\section2 Connecting signals to methods and other signals - -Signal objects have a \c connect() method that can be used to a connect a signal to a method or -another signal. When a signal is connected to a method, the method is automatically invoked -whenever the signal is emitted. (In Qt terminology, the method is a \e slot that is connected -to the \e signal; all methods defined in QML are created as Qt slots.) This enables a signal -to be received by a method instead of a \l {Signal Handlers}{signal handler}. - -For example, the \c application.qml above could be rewritten as: - -\snippet doc/src/snippets/declarative/qml-extending-types/signals/connectslots.qml 0 - -The \c myMethod() method will be called whenever the \c buttonClicked signal is received. - -In many cases it is sufficient to receive signals through signal handlers rather than using -the \c connect() function; the above example does not provide any improvements over using a -simple \c onButtonClicked handler. However, if you are \l{Dynamic Object Management in QML}{creating objects dynamically}, -or \l {Integrating JavaScript}{integrating JavaScript code}, then you will find the -\c connect() method useful. For example, the component below creates three \c Button -objects dynamically, and connects the \c buttonClicked signal of each object to the -\c myMethod() function: - -\snippet doc/src/snippets/declarative/qml-extending-types/signals/connectdynamic.qml 0 - -In the same way, you could connect a signal to methods defined in a dynamically -created object, or \l {Receiving QML Signals in JavaScript}{connect a signal to a JavaScript method}. - -There is also a corresponding \c disconnect() method for removing connected signals. The following -code removes the connection created in \c application.qml above: - -\qml -// application.qml -Item { - // ... - - function removeSignal() { - button.clicked.disconnect(item.myMethod) - } -} -\endqml - - -\section3 Forwarding signals - -The \c connect() method can also connect a signal to other signals. This has the effect -of "forwarding" a signal: it is automatically emitted whenever the relevant signal is emitted. For -example, the MouseArea \c onClicked handler in \c Button.qml above could have been replaced with -a call to \c connect(): - -\qml -MouseArea { - anchors.fill: parent - Component.onCompleted: clicked.connect(item.buttonClicked) -} -\endqml - -Whenever the \l MouseArea \c clicked signal is emitted, the \c rect.buttonClicked signal will -automatically be emitted as well. */ diff --git a/doc/src/declarative/focus.qdoc b/doc/src/declarative/focus.qdoc index 599d63c..940f864 100644 --- a/doc/src/declarative/focus.qdoc +++ b/doc/src/declarative/focus.qdoc @@ -28,11 +28,16 @@ /*! \target qmlfocus \page qdeclarativefocus.html +\ingroup qml-features +\contentspage QML Features +\previouspage {QML Text Handling and Validators}{Text Handling and Validators} +\nextpage {QML Signal and Handler Event System}{Signal and Handler Event System} + \title Keyboard Focus in QML When a key is pressed or released, a key event is generated and delivered to the focused QML \l Item. To facilitate the construction of reusable components -and to address some of the cases unique to fluid user interfaces, the QML items add a +and to address some of the cases unique to fluid user interfaces, the QML items add aged \e scope based extension to Qt's traditional keyboard focus model. \tableofcontents diff --git a/doc/src/declarative/integrating.qdoc b/doc/src/declarative/integrating.qdoc index f0d3a37..c2f55f5 100644 --- a/doc/src/declarative/integrating.qdoc +++ b/doc/src/declarative/integrating.qdoc @@ -27,7 +27,11 @@ /*! \page qml-integration.html -\title Integrating QML with existing Qt UI code +\ingroup qml-features +\previouspage {Using QML Bindings in C++ Applications} +\nextpage {Dynamic Object Management in QML}{Dynamic Object Management} +\contentspage QML Features +\title Integrating QML Code with Existing Qt UI Code There are a number of ways to integrate QML into QWidget-based UI applications, depending on the characteristics of your existing UI code. @@ -37,8 +41,8 @@ depending on the characteristics of your existing UI code. If you have an existing QWidget-based UI, QML widgets can be integrated into it using QDeclarativeView. QDeclarativeView is a subclass of QWidget so you -can add it to your user interface like any other QWidget. Use -QDeclarativeView::setSource() to load a QML file into the view, then add the +can add it to your user interface like any other QWidget. Use +QDeclarativeView::setSource() to load a QML file into the view, then add the view to your UI: \code @@ -52,7 +56,7 @@ layout->addWidget(qmlView); The one drawback to this approach is that QDeclarativeView is slower to initialize and uses more memory than a QWidget, and creating large numbers of QDeclarativeView -objects may lead to performance degradation. If this is the case, it may be +objects may lead to performance degradation. If this is the case, it may be better to rewrite your widgets in QML, and load the widgets from a main QML widget instead of using QDeclarativeView. @@ -70,7 +74,7 @@ of simple and dynamic elements. If you have an existing UI based on the \l{Graphics View Framework}, you can integrate QML widgets directly into your QGraphicsScene. Use QDeclarativeComponent to create a QGraphicsObject from a QML file, and -place the graphics object into your scene using \l{QGraphicsScene::addItem()}, or +place the graphics object into your scene using \l{QGraphicsScene::addItem()}, or reparent it to an item already in the \l{QGraphicsScene}. For example: @@ -95,12 +99,13 @@ of QML UIs: \section2 Loading QGraphicsWidget objects in QML -An alternative approach is to expose your existing QGraphicsWidget objects to +An alternative approach is to expose your existing QGraphicsWidget objects to QML and construct your scene in QML instead. See the \l {declarative-cppextensions-qgraphicslayouts.html}{graphics layouts example} which shows how to expose Qt's graphics layout classes to QML in order to use QGraphicsWidget with classes like QGraphicsLinearLayout and QGraphicsGridLayout. To expose your existing QGraphicsWidget classes to QML, use \l {qmlRegisterType()}. -See \l{Extending QML in C++} for further information on using C++ types in QML. +See \l{Extending QML Functionalities using C++} for further information on +how to use C++ types in QML. */ diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc index 65877f9..f78f3c2 100644 --- a/doc/src/declarative/javascriptblocks.qdoc +++ b/doc/src/declarative/javascriptblocks.qdoc @@ -205,7 +205,7 @@ component destruction. Property bindings can be created in JavaScript by assigning the property with a \c function that returns the required value. -See \l {Binding Properties from JavaScript} for details. +See \l {qml-javascript-assignment}{Property Assignment versus Property Binding} for details. \section1 Receiving QML Signals in JavaScript @@ -224,7 +224,8 @@ in \c script.js: The \c jsFunction() will now be called whenever MouseArea's \c clicked signal is emitted. -See \l {Connecting signals to methods and other signals} for more information. +See \l{QML Signal and Handler Event System#Connecting Signals to Methods and Signals} +{Connecting Signals to Methods and Signals} for more information. \section1 QML JavaScript Restrictions @@ -292,8 +293,8 @@ To run code after the environment setup has completed, refer to \o The value of \c this is currently undefined in QML in the majority of contexts -The \c this keyword is supported when \l {Binding Properties from JavaScript} -{binding properties from JavaScript}. In all other situations, the value of +The \c this keyword is supported when binding properties from JavaScript. +In all other situations, the value of \c this is undefined in QML. To refer to any element, provide an \c id. For example: diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc index f1ebd00..dbc8806 100644 --- a/doc/src/declarative/modules.qdoc +++ b/doc/src/declarative/modules.qdoc @@ -51,16 +51,14 @@ example, an \c import statement is required to use: An \c import statement includes the module name, and possibly a version number. This can be seen in the snippet commonly found at the top of QML files: -\qml -import QtQuick 1.0 -\endqml +\snippet doc/src/snippets/declarative/imports/qtquick-1.0.qml import This imports version 1.0 of the "QtQuick" module into the global namespace. (The QML library itself must be imported to use any of the \l {QML Elements}, as they are not included in the global namespace by default.) The \c Qt module is an \e installed module; it is found in the -\l{The QML import path}{import path}. There are two types of QML modules: +\l{#import-path}{import path}. There are two types of QML modules: located modules (defined by a URL) and installed modules (defined by a URI). @@ -94,24 +92,25 @@ MyQMLProject \endcode \o -\code +\qml import "../MyComponents" Window { - Slider { ... } - CheckBox { ... } + Slider { + // ... + } + CheckBox { + // ... + } } -\endcode +\endqml \endtable Similarly, if the directory resided on a network source, it could be imported like this: -\code - import "http://www.my-server.com/MyQMLProject/MyComponents" - import "http://www.my-server.com/MyQMLProject/MyComponents" 1.0 -\endcode +\snippet doc/src/snippets/declarative/imports/network-imports.qml imports A located module can also be imported as a network resource if it has a \l{Writing a qmldir file}{qmldir file} in the directory that specifies the QML files @@ -127,14 +126,18 @@ Window 1.0 Window.qml If the \c MyComponents directory was then hosted as a network resource, it could be imported as a module, like this: -\code +\qml import "http://the-server-name.com/MyQMLProject/MyComponents" Window { - Slider { ... } - CheckBox { ... } + Slider { + // ... + } + CheckBox { + // ... + } } -\endcode +\endqml with an optional "1.0" version specification. Notice the import would fail if a later version was used, as the \c qmldir file specifies that these elements @@ -145,7 +148,8 @@ defined in QML files; components defined by C++ \l{QDeclarativeExtensionPlugin}{ are not available. -\section1 Installed modules +\target import-path +\section1 Installed Modules Installed modules are modules that are made available through the QML import path, as defined by QDeclarativeEngine::importPathList(), or modules defined within @@ -156,10 +160,7 @@ path or network resource URL. When importing an installed module, an un-quoted URI is used, with a mandatory version number: -\code - import QtQuick 1.0 - import com.nokia.qml.mymodule 1.0 -\endcode +\snippet doc/src/snippets/declarative/imports/installed-module.qml imports When a module is imported, the QML engine searches the QML import path for a matching module. The root directory of the module must contain a @@ -190,7 +191,7 @@ Additional import paths can be added through QDeclarativeEngine::addImportPath() can also use the \c -I option to add an import path. -\section2 Creating installed modules +\section2 Creating Installed Modules As an example, suppose the \c MyQMLProject directory in the \l{Located Modules}{previous example} was located on the local filesystem at \c C:\qml\projects\MyQMLProject. The \c MyComponents @@ -211,8 +212,12 @@ without referring to the module's absolute filesystem location: import projects.MyQMLProject.MyComponents 1.0 Window { - Slider { ... } - CheckBox { ... } + Slider { + // ... + } + CheckBox { + // ... + } } \endqml @@ -225,22 +230,20 @@ defined in QML files; components defined by C++ \l{QDeclarativeExtensionPlugin}{ are not available. -\section2 Creating installed modules in C++ +\section2 Creating Installed Modules in C++ C++ applications can define installed modules directly within the application using qmlRegisterType(). For example, the \l {Tutorial: Writing QML extensions with C++}{Writing QML extensions with C++ tutorial} defines a C++ class named \c PieChart and makes this type available to QML by calling qmlRegisterType(): -\qml +\code qmlRegisterType<PieChart>("Charts", 1, 0, "PieChart"); -\endqml +\endcode This allows the application's QML files to use the \c PieChart type by importing the declared \c Charts module: -\qml -import Charts 1.0 -\endqml +\snippet doc/src/snippets/declarative/imports/chart.qml import For \l{QDeclarativeExtensionPlugin}{QML plugins}, the module URI is automatically passed to QDeclarativeExtensionPlugin::registerTypes(). This method @@ -253,9 +256,7 @@ example: Once the plugin is built and installed, and includes a \l{Writing a qmldir file}{qmldir file}, the module can be imported from QML, like this: -\code -import com.nokia.TimeExample 1.0 -\endcode +\snippet doc/src/snippets/declarative/imports/timeexample.qml import Unlike QML types defined by QML files, a QML type defined in a C++ extension plugin cannot be loaded by a module that is imported as a network resource. @@ -269,47 +270,34 @@ By default, when a module is imported, its contents are imported into the global To import a module into a specific namespace, use the \e as keyword: -\qml - import QtQuick 1.0 as QtLibrary - import "../MyComponents" as MyComponents - import com.nokia.qml.mymodule 1.0 as MyModule -\endqml +\snippet doc/src/snippets/declarative/imports/named-imports.qml imports Types from these modules can then only be used when qualified by the namespace: -\qml - QtLibrary.Rectangle { ... } - - MyComponents.Slider { ... } - - MyModule.SomeComponent { ... } -\endqml +\snippet doc/src/snippets/declarative/imports/named-imports.qml imported items Multiple modules can be imported into the same namespace in the same way that multiple modules can be imported into the global namespace: -\qml - import QtQuick 1.0 as Nokia - import Ovi 1.0 as Nokia -\endqml +\snippet doc/src/snippets/declarative/imports/merged-named-imports.qml imports -\section2 JavaScript files +\section2 JavaScript Files JavaScript files must always be imported with a named import: \qml - import "somescript.js" as MyScript +import "somescript.js" as MyScript - Item { - //... - Component.onCompleted: MyScript.doSomething() - } +Item { + //... + Component.onCompleted: MyScript.doSomething() +} \endqml The qualifier ("MyScript" in the above example) must be unique within the QML document. Unlike ordinary modules, multiple scripts cannot be imported into the same namespace. -\section1 Writing a qmldir file +\section1 Writing a qmldir File A \c qmldir file is a metadata file for a module that maps all type names in the module to versioned QML files. It is required for installed modules, and diff --git a/doc/src/declarative/mouseevents.qdoc b/doc/src/declarative/mouseevents.qdoc new file mode 100644 index 0000000..ade6760 --- /dev/null +++ b/doc/src/declarative/mouseevents.qdoc @@ -0,0 +1,120 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page mouseevents.html +\title QML Mouse Events +\ingroup QML Features +\previouspage {Anchor-based Layout in QML}{Layouts using Anchors} +\nextpage {QML Text Handling and Validators}{Text Handling and Validators} +\contentspage QML Features + +\tableofcontents + +\section1 Mouse Elements + +\list +\o \l{MouseArea} Element +\o \l{MouseEvent} Object +\endlist + +\section1 Mouse Event Handling + +QML uses \l{QML Signal and Handler Event System}{signals and handlers} to +deliver mouse interactions. Specifically, the \l MouseArea and \l MouseEvent +elements provide QML components with signal handlers to accept mouse events +within a defined area. + +\section1 Defining a Mouse Area + +The \l MouseArea element receives events within a defined area. One quick way +to define this area is to anchor the \c MouseArea to its parent's area using the +\c anchors.fill property. If the parent is a \l Rectangle (or any \l Item +component), then the MouseArea will fill the area defined by the parent's +dimensions. Alternatively, an area smaller or larger than the parent is +definable. +\snippet doc/src/snippets/declarative/mousearea/mousearea-snippet.qml anchor fill + +\section1 Receiving Events + +The MouseArea element provides +\l{QML Signal and Handler Event System}{signals and handlers} to detect different +mouse events. The \l MouseArea element documentation describes these +gestures in greater detail: + +\list +\o canceled +\o clicked +\o doubleClicked +\o entered +\o exited +\o positionChanged +\o pressAndHold +\o pressed +\o released +\endlist + +These signals have signal handlers that are invoked when the signals are emitted. +\snippet doc/src/snippets/declarative/mousearea/mousearea-snippet.qml mouse handlers + +\section1 Enabling Gestures +Some mouse gestures and button clicks need to be enabled before they send or +receive events. Certain \l MouseArea and \l MouseEvent properties enable these +gestures. + +To listen to (or explicitly ignore) a certain mouse button, set the appropriate +mouse button to the \l {MouseArea::acceptedButtons}{acceptedButtons} property. + +Naturally, the mouse events, such as button presses and mouse positions, are +sent during a mouse click. For example, the \c containsMouse property will only +retrieve its correct value during a mouse press. The +\l {MouseArea::hoverEnabled}{hoverEnabled} will enable mouse events and +positioning even when there are no mouse button presses. Setting the +\c hoverEnabled property to \c true, in turn will enable the \c entered, +\c exited, and \c positionChanged signal and their respective signal handlers. + +\snippet doc/src/snippets/declarative/mousearea/mousearea-snippet.qml enable handlers +Additionally, to disable the whole mouse area, set the \c MouseArea +element's \c enabled property to \c false. + +\section1 MouseEvent Object + +Signals and their handlers receive a \l MouseEvent object as a parameter. The +\c mouse object contain information about the mouse event. For example, the +mouse button that started the event is queried through the +\l {MouseEvent::button}{mouse.button} property. + +The \c MouseEvent object can also ignore a mouse event using its \c accepted +property. + +\section2 Accepting Further Signals +Many of the signals are sent multiple times to reflect various mouse events +such as double clicking. To facilitate the classification of mouse clicks, the +MouseEvent object has an \c accepted property to disable the event propagation. + +To learn more about QML's event system, please read the \l {QML Signal and Handler Event System} document. +*/ diff --git a/doc/src/declarative/network.qdoc b/doc/src/declarative/network.qdoc index 675a0aa..1b2934a 100644 --- a/doc/src/declarative/network.qdoc +++ b/doc/src/declarative/network.qdoc @@ -27,6 +27,10 @@ /*! \page qdeclarativenetwork.html +\ingroup qml-features +\previouspage {Dynamic Object Management in QML}{Dynamic Object Management} +\nextpage {QML Internationalization}{Internationalization} +\contentspage QML Features \title Network Transparency QML supports network transparency by using URLs (rather than file names) for all @@ -57,7 +61,7 @@ Network transparency is supported throughout QML, for example: Even QML types themselves can be on the network - if the \l {QML Viewer} is used to load \tt http://example.com/mystuff/Hello.qml and that content refers to a type "World", the engine will load \tt http://example.com/mystuff/qmldir and resolve the type just as it would for a local file. -For example if the qmldir file contains the line "World World.qml", it will load +For example if the qmldir file contains the line "World World.qml", it will load \tt http://example.com/mystuff/World.qml Any other resources that \tt Hello.qml referred to, usually by a relative URL, would similarly be loaded from the network. diff --git a/doc/src/declarative/positioners.qdoc b/doc/src/declarative/positioners.qdoc index 5493d4a..763bc88 100644 --- a/doc/src/declarative/positioners.qdoc +++ b/doc/src/declarative/positioners.qdoc @@ -27,9 +27,12 @@ /*! \page qml-positioners.html +\ingroup qml-features +\previouspage Property Binding +\nextpage Anchor-based Layout in QML +\contentspage QML Features \title Using QML Positioner and Repeater Items -\section1 Introduction Positioner items are container items that manage the positions and sizes of items in a declarative user interface. Positioners behave in a similar way to @@ -53,7 +56,7 @@ graphical elements: \section2 Column -\div{float-right} +\div {class="float-right"} \inlineimage qml-column.png \enddiv @@ -70,7 +73,7 @@ must be added to a parent Rectangle, if desired. \section2 Row -\div{float-right} +\div {class="float-right"} \inlineimage qml-row.png \enddiv @@ -87,7 +90,7 @@ left around the edges of the horizontally centered Row item. \section2 Grid -\div{float-right} +\div {class="float-right"} \inlineimage qml-grid-spacing.png \enddiv @@ -97,7 +100,7 @@ in a 2-by-2 grid. As with the other positioners, the spacing between items can be specified using the \l{Grid::spacing}{spacing} property. \clearfloat -\snippet doc/src/snippets/declarative/grid/grid-spacing.qml document +\snippet doc/src/snippets/declarative/grid-spacing.qml document There is no difference between horizontal and vertical spacing inserted between items, so any additional space must be added within the items @@ -108,7 +111,7 @@ at the appropriate places in the Grid definition. \section2 Flow -\div{float-right} +\div {class="float-right"} \inlineimage qml-flow-text1.png \inlineimage qml-flow-text2.png \enddiv @@ -137,7 +140,7 @@ control of spacing between items and between lines of items. \section1 Repeaters -\div{float-right} +\div {class="float-right"} \inlineimage qml-repeater-grid-index.png \enddiv diff --git a/doc/src/declarative/propertybinding.qdoc b/doc/src/declarative/propertybinding.qdoc index 379a4ec..88ec5c3 100644 --- a/doc/src/declarative/propertybinding.qdoc +++ b/doc/src/declarative/propertybinding.qdoc @@ -27,192 +27,298 @@ /*! \page propertybinding.html +\ingroup qml-features +\contentspage QML Features +\previouspage {QML Basic Types}{Data Types} +\nextpage {Using QML Positioner and Repeater Items}{Component Layouts} \title Property Binding -Property binding is a declarative way of specifying the value of a property. Binding allows -a property's value to be expressed as an JavaScript expression that defines the value relative -to other property values or data accessible in the application. The property value is -automatically kept up to date if the other properties or data values change. +\section1 Properties -Property bindings are created implicitly in QML whenever a property is assigned an JavaScript -expression. The following QML uses two property bindings to connect the size of the rectangle -to that of \c otherItem. +QML components have \e properties that can be read and modified by other objects. +In QML, properties serve many purposes but their main function is to bind to +values. Values may be a \l{QML Basic Types}{basic type}, or other QML elements. -\code -Rectangle { - width: otherItem.width - height: otherItem.height -} -\endcode +The syntax for properties is: -QML extends a standards compliant JavaScript engine, so any valid JavaScript expression can be -used as a property binding. Bindings can access object properties, make function calls and even -use builtin JavaScript objects like \e {Date} and \e {Math}. Assigning a constant value to a -property can even be thought of as a binding - after all, a constant is a valid JavaScript -expression! Here are some examples of more complex bindings: - -\code -Rectangle { - function calculateMyHeight() { - return Math.max(otherItem.height, thirdItem.height); - } - - anchors.centerIn: parent - width: Math.min(otherItem.width, 10) - height: calculateMyHeight() - color: { if (width > 10) "blue"; else "red" } -} -\endcode +\tt{[default] property <type> <name>[: defaultValue]} -While syntactically bindings can be of arbitrary complexity, if a binding starts to become -overly complex - such as involving multiple lines, or imperative loops - it may be better -to refactor the component entirely, or at least factor the binding out into a separate -function. +Elements already possess useful properties but, to create custom properties, +precede the property name with the keyword \c property. -\section1 Changing Bindings - -The \l PropertyChanges element can be used within a state change to modify the bindings on -properties. - -This example modifies the \l Rectangle's width property binding to be \c {otherItem.height} -when in the "square" state. When it returns to its default state, width's original property -binding will have been restored. - -\code -Rectangle { - id: rectangle - width: otherItem.width - height: otherItem.height - - states: State { - name: "square" - PropertyChanges { - target: rectangle - width: otherItem.height - } - } -} -\endcode +\snippet doc/src/snippets/declarative/properties.qml parent begin +\snippet doc/src/snippets/declarative/properties.qml inherited properties +\snippet doc/src/snippets/declarative/properties.qml custom properties +\snippet doc/src/snippets/declarative/properties.qml parent end +QML property rules coincide with many of JavaScript's property rules, for example, +property names must begin with a lowercase letter. +\l {JavaScript Reserved Words}{JavaScript reserved words} are not valid property +names. -\section1 Binding Properties from JavaScript +\section1 Property Binding -When working with both QML and JavaScript, it is important to differentiate between -\l {Property Binding} syntax in QML and simple \e {property assignment} in JavaScript. Take -the example below, which uses property binding to ensure the item's \c height is always twice -its \c width: - -\qml -Item { - width: 100 - height: width * 2 -} -\endqml - -On the other hand, take the following JavaScript code snippet, which \e assigns, rather -than \e binds, the value of the \c height property: - -\code -Item { - width: 100 - - Component.onCompleted: { - height = width * 2 // if width changes later, height is not updated! - } -} -\endcode +Property binding is a declarative way of specifying the value of a property. Binding allows +a property's value to be expressed as an JavaScript expression that defines the value relative +to other property values or data accessible in the application. The property value is +automatically kept up to date if the other properties or data values change. -Instead of creating a property binding, this simply sets the \c height property to the correct -value \e {at the time that} the JavaScript code is invoked. Unlike the first example, the -\c height will never change if \c width changes. +Property bindings are created in QML using the colon "\c {:}" before the value: +\snippet doc/src/snippets/declarative/properties.qml property binding +The property binding causes the width of the \c Rectangle to update whenever the +\c {parent}'s width changes. -The \e {property : value} syntax for property binding is QML-specific and cannot be used in -JavaScript. Instead, to bind a property from JavaScript, assign a \e function to the property -that returns the required value. The following code correctly sets the property binding -created in the first example, but creates the binding in JavaScript rather than QML: +QML extends a standards compliant JavaScript engine, so any valid JavaScript expression can be +used as a property binding. Bindings can access object properties, make function calls and even +use built-in JavaScript objects such as \c {Date} and \c {Math}. +\snippet doc/src/snippets/declarative/properties.qml JavaScript sample -\qml -Item { - width: 100 +While syntactically bindings can be of arbitrary complexity, if a binding starts to become +overly complex - such as involving multiple lines, or imperative loops - it may be better +to refactor the component entirely, or at least factor the binding out into a separate +function. - Component.onCompleted: { - height = (function() { return width * 2 }) - } -} -\endqml +\keyword qml-javascript-assignment +\section1 Property Assignment versus Property Binding +When working with both QML and JavaScript, it is important to differentiate between +QML property binding and JavaScript value assignment. In QML, a property +binding is created using the colon "\c {:}". +\snippet doc/src/snippets/declarative/properties.qml property binding +The property binding causes the width of the \c Rectangle to update whenever the +\c {parent}'s width changes. -\section2 Using \c this to create a binding +Assigning a property value (using the equals sign "\c {=}") does not create a +property binding. +\snippet doc/src/snippets/declarative/properties.qml property assignment -When creating a property binding from JavaScript, QML allows the use of the \c this keyword to -refer to the object to which the property binding will be assigned. This allows one to -explicitly refer to a property within an object when there may be ambiguity about the exact -property that should be used for the binding. +Instead of creating a property binding, the assignment simply sets the \c Rectangle +\c width value to a number when the \c Component.onCompleted code is invoked. -For example, the \c Component.onCompleted handler below is defined within the scope of the -\l Item, and references to \c width within this scope would refer to the \l Item's width, rather -than that of the \l Rectangle. To bind the \l Rectangle's \c height to its own \c width, the -function needs to explicitly refer to \c this.width rather than just \c width. Otherwise, the -height of the \l Rectangle would be bound to the width of the \l Item and not the \l Rectangle. +Assigning a value to a property that is already bound will remove the previous binding. +A property can only have one value at a time (a list of property is one value), +and if any code explicitly re-sets this value, the property binding is removed. -\qml -Item { - width: 500 - height: 500 +There is no way to create a property binding directly from imperative JavaScript code, +although it is possible to use the \l {Using the Binding Element}{Binding} element. - Rectangle { - id: rect - width: 100 - color: "yellow" - } +\section1 Types of Properties - Component.onCompleted: { - rect.height = (function() { return this.width * 2 }) - } -} -\endqml +Properties may bind to different types, but they are are \e type-safe. That is, +properties only allow you to assign a value that matches the property type. For +example, if a property is a real, and if you try to assign a string to it you +will get an error. -(In this case, the function could also have referred to \c rect.width rather than \c this.width.) +\badcode +property real volume: "four" //generates an error +\endcode -Note that the value of \c this is not defined outside of its use in property binding. -See \l {QML JavaScript Restrictions} for details. +Certain properties bind to more complex types such as other elements and objects. + +\keyword qml-basic-property-types +\section2 Basic Property Types +Basic types such as \l int, \l real, and other Qt structures may be bound to +properties. For a list of types, visit the \l {QML Basic Types} document. -\section2 Effects of property assignment +\keyword qml-id-property +\section2 The \c id Property + +Each QML object may be given a special unique property called an \c id. +No other object within the same QML component (see \l{QML Documents}) can have +the same \c id value. QML objects may then access an object using the \c id +property. +\snippet doc/src/snippets/declarative/properties.qml id property +A component may readily access its parent's properties by using the \c parent +property. -Note that assigning a value to a property that is currently bound will remove the binding. -A property can only have one value at a time, and if any code explicitly sets this value, the -binding is removed. In the following example, although \c width has been bound to \c height, -the binding is removed by the JavaScript code that assigns \c width to 50: +Note that an \c id must begin with a lower-case letter or an underscore. The +\c id cannot contain characters other than letters, numbers, underscores, and +\l {JavaScript Reserved Words}{JavaScript reserved words}. + +\section2 Elements and Objects as Property Values -\code -Item { - width: height * 2 - height: 100 +Many properties bind to objects. For example, the \l Item element has a +\c states property that can bind to \l State elements. This type of property +binding allows elements to carry additional non-children elements. \c Item's +\c transitions property behaves in a similar way; it can bind to \l Transition +elements. + +Care must be taken when referring to the parent of an object property binding. +Elements and components that are bound to properties are not necessarily set +as children of the properties' component. + +\snippet doc/src/snippets/declarative/properties.qml object binding +The code snippet has a \l Gradient element that attempts to print its parent's +\c width value. However, the \c Gradient element is bound to the \c gradient +property, not the \c children property of the \c Rectangle. As a result, the +\c Gradient does not have the \c Rectangle as its parent. Printing the value +of \c{parent.width} generates an error. Printing the \c Rectangle object's +first child's \c name will print \c {childrectangle} because the second +\c Rectangle is bound to the \c children property. + +For more information about the \c children property, please read the +\l {Default Properties} section. + +\keyword attached-properties +\section2 Attached Properties + +Certain objects provide additional properties by \e attaching properties to other +objects. For example, the \l Keys element have properties that can \e attach to other QML +objects to provide keyboard handling. + +\snippet doc/src/snippets/declarative/properties.qml list attached property +The element \l ListView provides the delegate, \c listdelegate, the property +\c isCurrentItem as an attached property. The \c ListView.isCurrentItem +\e{attached property} provides highlight information to the delegate. +Effectively, the \l ListView element attaches the \c ListView.isCurrentItem +property to each delegate it creates. + +\keyword attached-signalhandlers +\section2 Attached Signal Handlers + +\e {Attached signal handlers} are similar +to \l{Attached Properties}{attached properties} in that they attach to objects +to provide additional functionality to objects. Two prominent elements, +\l Component and \l Keys element provide +\l{QML Signal and Handler Event System}{signal handlers} as attached signal +handlers. +\snippet doc/src/snippets/declarative/properties.qml attached signal handler + +Read the \l{QML Signal and Handler Event System} and the \l{Keyboard Focus in QML} +articles for more information. + +\section2 List properties + +Some properties may accept a binding to a list property, where more than one +component can bind to the property. List properties allow multiple +\l {State}{States}, \l {Gradient}{Gradients}, and other components to bind to a +single property. +\snippet doc/src/snippets/declarative/properties.qml list property +The list is enclosed in square brackets, with a comma separating the +list elements. In cases where you are only assigning a single item to a +list, you may omit the square brackets. +\snippet doc/src/snippets/declarative/properties.qml single property + +To access the list, use the \c index property. +\snippet doc/src/snippets/declarative/properties.qml print list property +The snippet code simply prints the name of the first state, \c FETCH. + + See the \l{list}{list type} documentation +for more details about list properties and their available operations. + +\keyword qml-grouped-properties +\section2 Grouped Properties + +In some cases properties form a logical group and use either the \e dot notation +or \e group notation. + +Grouped properties may be written both ways: +\snippet doc/src/snippets/declarative/properties.qml grouped properties + +In the element documentation grouped properties are shown using the dot notation. + +\section2 Property Aliases + +Unlike a property definition, which allocates a new, unique storage space for +the property, a property alias connects the newly declared property, called the +\e{aliasing property} as a direct reference to an existing property, the +\e{aliased property}. Read or write operations on the aliasing property results +in a read or write operations on the aliased property, respectively. + +A property alias declaration is similar to an ordinary property definition: + +\tt{[default] property alias <name>: <alias reference>} + +As the aliasing property has the same type as the aliased property, an explicit +type is omitted, and the special \c alias keyword is before the property name. +Instead of a default value, a property alias has a compulsory alias reference. +Accessing the aliasing property is similar to accessing a regular property. In +addition, the optional \c default keyword indicates that the aliasing property +is a \l{Default Properties}{default property}. + +\snippet doc/src/snippets/declarative/Button.qml property alias +When importing the component as a \c Button, the \c buttonlabel is directly +accessible through the \c label property. +\snippet doc/src/snippets/declarative/properties.qml alias usage +In addition, the \c id property may also be aliased and referred outside the +component. +\snippet doc/src/snippets/declarative/Button.qml parent begin +\snippet doc/src/snippets/declarative/Button.qml id alias +\snippet doc/src/snippets/declarative/Button.qml parent end +The \c imagebutton component has the ability to modify the child \l Image object + and its properties. +\snippet doc/src/snippets/declarative/properties.qml image alias + +Using aliases, properties may be exposed to the +\l{qml-top-level-component}{top level component}. Exposing properties to the +top-level component allows components to have interfaces similar to Qt widgets. + +\section3 Considerations for property aliases + +Aliases are only activated once the component +\l{Component::onCompleted}{completes} its initialization. An error is generated +when an uninitialized alias is referenced. Likewise, aliasing an aliasing +property will also result in an error. + +\snippet doc/src/snippets/declarative/properties.qml alias complete + +When importing the component, however, aliasing properties appear as regular Qt +properties and consequently can be used in alias references. + +It is possible for an aliasing property to have the same name as an existing +property, effectively overwriting the existing property. For example, +the following component has a \c color alias property, named the same as the built-in +\l {Rectangle::color} property: + +\snippet doc/src/snippets/declarative/properties.qml alias overwrite + +Any object that use this component and refer to its \c color property will be +referring to the alias rather than the ordinary \l {Rectangle::color} property. +Internally, however, the \c coloredrectangle can correctly set its \c color +property and refer to the actual defined property rather than the alias. + +The \l{declarative/ui-components/tabwidget}{TabWidget} example uses +aliases to reassign children to the \l ListView, creating a tab effect. + +\keyword default-properties +\section2 Default Properties - Component.onCompleted: { - width = 50; - } -} -\endcode +When imported, QML components will bind declared children to their designated +\e{default properties}. The optional \c default attribute specifies a property +as the \e {default property}. For example, the State element's default property +is its \l{State::changes}{changes} property. \l PropertyChanges elements +may simply be placed as the \c{State}'s children and they will be bound to the +\c changes property. +\snippet doc/src/snippets/declarative/properties.qml state default + +Similarly, the \l Item element's default property is its +\l{Item::data}{data} property. The \c data property manages Item's +\c children and \c resources properties. This way, different data types may be +placed as direct children of the \c Item. +\snippet doc/src/snippets/declarative/properties.qml default property +Reassigning a default property is useful when a component is reused. For +example, the \l{declarative/ui-components/tabwidget}{TabWidget} example uses +the \c default attribute to reassign children to the \l ListView, creating +a tab effect. -\section1 The Binding Element +\section1 Using the Binding Element -The implicit binding syntax shown previously is easy to use and works perfectly for most uses -of bindings. In some advanced cases, it is necessary to create bindings explicitly using the -\l Binding element. +In some advanced cases, it may be necessary to create bindings explicitly with +the\l Binding element. -For example, to bind a property exposed from C++ (\c system.brightness) to a value -coming from QML (\c slider.value), you could use the Binding element as follows: -\qml -Binding { - target: system - property: "brightness" - value: slider.value -} -\endqml +For example, to bind a property exposed from C++ (\c system.brightness) to a +value written in QML (\c slider.value), you could use the \l Binding element as +follows: +\snippet doc/src/snippets/declarative/properties.qml binding element +\section1 Changing Property Values in States +The \l PropertyChanges element is for setting property bindings within a +\l State element to set a property binding. + +\snippet doc/src/snippets/declarative/properties.qml PropertyChanges element +The rectangle's \c color property will bind to the \c warning component's +\c color property when its \c state is set to the \c WARNING state. */ - diff --git a/doc/src/declarative/qdeclarativedocument.qdoc b/doc/src/declarative/qdeclarativedocument.qdoc index b94e32e..423d77c 100644 --- a/doc/src/declarative/qdeclarativedocument.qdoc +++ b/doc/src/declarative/qdeclarativedocument.qdoc @@ -30,8 +30,6 @@ \title QML Documents \brief A description of QML documents and the kind of content they contain. -\section1 Introduction - A QML document is a block of QML source code. QML documents generally correspond to files stored on a disk or at a location on a network, but they can also be constructed directly from text data. @@ -42,17 +40,17 @@ Here is a simple QML document: QML documents are always encoded in UTF-8 format. -A QML document always begins with one or more import statements. To prevent elements -introduced in later versions from affecting existing QML programs, the element types -available within a document are controlled by the imported QML \l {Modules}. That is, +A QML document always begins with one or more import statements. To prevent elements +introduced in later versions from affecting existing QML programs, the element types +available within a document are controlled by the imported QML \l {Modules}. That is, QML is a \e versioned language. -Syntactically a QML document is self contained; QML does \e not have a preprocessor that -modifies the document prior to presentation to the QML runtime. \c import statements -do not "include" code in the document, but instead instruct the QML runtime on how to -resolve type references found in the document. Any type reference present in a QML -document - such as \c Rectangle and \c ListView - including those made within an -\l {Inline JavaScript}{JavaScript block} or \l {Property Binding}s, are \e resolved based exclusively on the +Syntactically a QML document is self contained; QML does \e not have a preprocessor that +modifies the document prior to presentation to the QML runtime. \c import statements +do not "include" code in the document, but instead instruct the QML runtime on how to +resolve type references found in the document. Any type reference present in a QML +document - such as \c Rectangle and \c ListView - including those made within an +\l {Inline JavaScript}{JavaScript block} or \l {Property Binding}s, are \e resolved based exclusively on the import statements. QML does not import any modules by default, so at least one \c import statement must be present or no elements will be available! @@ -63,12 +61,12 @@ resolved according to the document scope. \section1 Documents as Component Definitions -A QML document defines a single, top-level \l {QDeclarativeComponent}{QML component}. A QML component -is a template that is interpreted by the QML runtime to create an object with some predefined -behaviour. As it is a template, a single QML component can be "run" multiple times to -produce several objects, each of which are said to be \e instances of the component. +A QML document defines a single, top-level \l {QDeclarativeComponent}{QML component}. A QML component +is a template that is interpreted by the QML runtime to create an object with some predefined +behaviour. As it is a template, a single QML component can be "run" multiple times to +produce several objects, each of which are said to be \e instances of the component. -Once created, instances are not dependent on the component that created them, so they can +Once created, instances are not dependent on the component that created them, so they can operate on independent data. Here is an example of a simple "Button" component (defined in a \c Button.qml file) that is instantiated four times by \c application.qml. Each instance is created with a different value for its \c text property: @@ -80,7 +78,7 @@ Each instance is created with a different value for its \c text property: \row \o \snippet doc/src/snippets/declarative/qml-documents/qmldocuments.qml document -\o +\o \qml import QtQuick 1.0 @@ -112,23 +110,23 @@ to other QML components and applications in the same directory. \section1 Inline Components In addition to the top-level component that all QML documents define, and any reusable -components placed in separate files, documents may also -include \e inline components. Inline components are declared using the -\l Component element, as can be seen in the first example above. Inline components share +components placed in separate files, documents may also +include \e inline components. Inline components are declared using the +\l Component element, as can be seen in the first example above. Inline components share all the characteristics of regular top-level components and use the same \c import list as their -containing QML document. Components are one of the most basic building blocks in QML, and are +containing QML document. Components are one of the most basic building blocks in QML, and are frequently used as "factories" by other elements. For example, the \l ListView element uses the \c delegate component as the template for instantiating list items - each list item is just a new instance of the component with the item specific data set appropriately. -Like other \l {QML Elements}, the \l Component element is an object and must be assigned to a +Like other \l {QML Elements}, the \l Component element is an object and must be assigned to a property. \l Component objects may also have an object id. In the first example on this page, -the inline component is added to the \l Rectangle's \c resources list, and then -\l {Property Binding} is used to assign the \l Component to the \l ListView's \c delegate +the inline component is added to the \l Rectangle's \c resources list, and then +\l {Property Binding} is used to assign the \l Component to the \l ListView's \c delegate property. While using property binding allows the \l Component object to be shared (for example, -if the QML document contained multiple \l ListView's with the same delegate), in this case the -\l Component could have been assigned directly to the \l ListView's \c delegate. The QML -language even contains a syntactic optimization when assigning directly to a component property +if the QML document contained multiple \l ListView's with the same delegate), in this case the +\l Component could have been assigned directly to the \l ListView's \c delegate. The QML +language even contains a syntactic optimization when assigning directly to a component property for this case where it will automatically insert the \l Component tag. These final two examples are behaviorally identical to the original document. diff --git a/doc/src/declarative/qdeclarativei18n.qdoc b/doc/src/declarative/qdeclarativei18n.qdoc index 9ca8938..bbee37c 100644 --- a/doc/src/declarative/qdeclarativei18n.qdoc +++ b/doc/src/declarative/qdeclarativei18n.qdoc @@ -27,9 +27,12 @@ /*! \page qdeclarativei18n.html +\ingroup qml-features +\contentspage QML Features +\previouspage {Network Transparency}{Loading Resources in QML} +\nextpage {QML Features} \title QML Internationalization -\section1 Overview Strings in QML can be marked for translation using the qsTr(), qsTranslate(), QT_TR_NOOP(), and QT_TRANSLATE_NOOP() functions. diff --git a/doc/src/declarative/qdeclarativemodels.qdoc b/doc/src/declarative/qdeclarativemodels.qdoc index 9409eaf..23dd390 100644 --- a/doc/src/declarative/qdeclarativemodels.qdoc +++ b/doc/src/declarative/qdeclarativemodels.qdoc @@ -27,10 +27,14 @@ /*! \page qdeclarativemodels.html +\ingroup qml-features +\contentspage QML Features +\previouspage {QML Animation and Transitions}{Animation and Transitions} +\nextpage {Presenting Data with Views} \target qmlmodels \title QML Data Models -QML items such as ListView, GridView and \l Repeater require Data Models +QML items such as ListView, GridView and \l Repeater require Data Models that provide the data to be displayed. These items typically require a \e delegate component that creates an instance for each item in the model. Models may be static, or @@ -38,7 +42,7 @@ have items modified, inserted, removed or moved dynamically. Data is provided to the delegate via named data roles which the delegate may bind to. Here is a ListModel with two roles, \e type and \e age, -and a ListView with a delegate that binds to these roles to display their +and a ListView with a delegate that binds to these roles to display their values: \snippet doc/src/snippets/declarative/qml-data-models/listmodel-listview.qml document @@ -48,7 +52,7 @@ properties, the roles can be accessed with the qualified \e model name instead. For example, if a \l Text element had \e type or \e age properties, the text in the above example would display those property values instead of the \e type and \e age values from the model item. In this case, the properties could have been referenced as -\c model.type and \c model.age instead to ensure the delegate displays the +\c model.type and \c model.age instead to ensure the delegate displays the property values from the model item. A special \e index role containing the index of the item in the model @@ -68,11 +72,13 @@ QML provides several types of data models among the built-in set of QML elements. In addition, models can be created with C++ and then made available to QML components. -The views used to access data models are described in \l{Presenting Data with QML}. +The views used to access data models are described in the +\l{Presenting Data with Views} overview. The use of positioner items to arrange items from a model is covered in \l{Using QML Positioner and Repeater Items}. +\keyword qml-data-models \section1 QML Data Models \section2 ListModel @@ -108,7 +114,7 @@ XmlListModel allows construction of a model from an XML data source. The roles are specified via the \l XmlRole element. The following model has three roles, \e title, \e link and \e description: -\code +\qml XmlListModel { id: feedModel source: "http://rss.news.yahoo.com/rss/oceania" @@ -117,7 +123,7 @@ XmlListModel { XmlRole { name: "link"; query: "link/string()" } XmlRole { name: "description"; query: "description/string()" } } -\endcode +\endqml The \l{demos/declarative/rssnews}{RSS News demo} shows how XmlListModel can be used to display an RSS feed. @@ -125,31 +131,19 @@ be used to display an RSS feed. \section2 VisualItemModel -VisualItemModel allows QML items to be provided as a model. +VisualItemModel allows QML items to be provided as a model. This model contains both the data and delegate; the child items of a -VisualItemModel provide the contents of the delegate. The model +VisualItemModel provide the contents of the delegate. The model does not provide any roles. -\code - VisualItemModel { - id: itemModel - Rectangle { height: 30; width: 80; color: "red" } - Rectangle { height: 30; width: 80; color: "green" } - Rectangle { height: 30; width: 80; color: "blue" } - } - - ListView { - anchors.fill: parent - model: itemModel - } -\endcode +\snippet doc/src/snippets/declarative/models/visual-model-and-view.qml visual model and view Note that in the above example there is no delegate required. The items of the model itself provide the visual elements that will be positioned by the view. - +\keyword qml-c++-models \section1 C++ Data Models Models can be defined in C++ and then made available to QML. This is useful @@ -165,7 +159,7 @@ models. A model may be a simple QStringList, which provides the contents of the list via the \e modelData role. -Here is a ListView with a delegate that references its model item's +Here is a ListView with a delegate that references its model item's value using the \c modelData role: \snippet examples/declarative/modelviews/stringlistmodel/view.qml 0 @@ -184,7 +178,7 @@ the model by calling QDeclarativeContext::setContextProperty() again. \section2 QObjectList-based model -A list of QObject* values can also be used as a model. A QList<QObject*> provides +A list of QObject* values can also be used as a model. A QList<QObject*> provides the properties of the objects in the list as roles. The following application creates a \c DataObject class that with @@ -205,7 +199,7 @@ the ListView delegate: \snippet examples/declarative/modelviews/objectlistmodel/view.qml 0 -Note the use of the fully qualified access to the \c color property. +Note the use of the fully qualified access to the \c color property. The properties of the object are not replicated in the \c model object, since they are easily available via the \c modelData object. @@ -221,10 +215,10 @@ the model by calling QDeclarativeContext::setContextProperty() again. A model can be defined by subclassing QAbstractItemModel. This is the best approach if you have a more complex model that cannot be supported -by the other approaches. A QAbstractItemModel can also automatically +by the other approaches. A QAbstractItemModel can also automatically notify a QML view when the model data has changed. -The roles of a QAbstractItemModel subclass can be exposed to QML by calling +The roles of a QAbstractItemModel subclass can be exposed to QML by calling QAbstractItemModel::setRoleNames(). The default role names set by Qt are: \table @@ -244,9 +238,9 @@ that has \e type and \e size roles. It calls QAbstractItemModel::setRoleNames() role names for accessing the properties via QML: \snippet examples/declarative/modelviews/abstractitemmodel/model.h 0 -\dots +\dots \snippet examples/declarative/modelviews/abstractitemmodel/model.h 1 -\dots +\dots \snippet examples/declarative/modelviews/abstractitemmodel/model.h 2 \codeline \snippet examples/declarative/modelviews/abstractitemmodel/model.cpp 0 @@ -261,14 +255,14 @@ roles: QML views are automatically updated when the model changes. Remember the model must follow the standard rules for model changes and notify the view when -the model has changed by using QAbstractItemModel::dataChanged(), +the model has changed by using QAbstractItemModel::dataChanged(), QAbstractItemModel::beginInsertRows(), etc. See the \l {Model subclassing reference} for more information. The complete example is available in Qt's \l {declarative/modelviews/abstractitemmodel}{examples/declarative/modelviews/abstractitemmodel} directory. QAbstractItemModel presents a hierarchy of tables, but the views currently provided by QML -can only display list data. +can only display list data. In order to display child lists of a hierarchical model the VisualDataModel element provides several properties and functions for use with models of type QAbstractItemModel: @@ -283,14 +277,14 @@ with models of type QAbstractItemModel: \section2 Exposing C++ Data Models to QML -The above examples use QDeclarativeContext::setContextProperty() to set -model values directly in QML components. An alternative to this is to -register the C++ model class as a QML type from a QML C++ plugin using -QDeclarativeExtensionPlugin. This would allow the model classes to be +The above examples use QDeclarativeContext::setContextProperty() to set +model values directly in QML components. An alternative to this is to +register the C++ model class as a QML type from a QML C++ plugin using +QDeclarativeExtensionPlugin. This would allow the model classes to be created directly as elements within QML: \table -\row +\row \o \code @@ -299,7 +293,7 @@ class MyModelPlugin : public QDeclarativeExtensionPlugin public: void registerTypes(const char *uri) { - qmlRegisterType<MyModel>(uri, 1, 0, + qmlRegisterType<MyModel>(uri, 1, 0, "MyModel"); } } @@ -339,7 +333,7 @@ An integer can be used to specify a model that contains a certain number of elements. In this case, the model does not have any data roles. The following example creates a ListView with five elements: -\code +\qml Item { width: 200; height: 250 @@ -355,7 +349,7 @@ Item { } } -\endcode +\endqml \section2 An Object Instance @@ -367,7 +361,7 @@ The example below creates a list with one item, showing the color of the \e myText text. Note the use of the fully qualified \e model.color property to avoid clashing with \e color property of the Text element in the delegate. -\code +\qml Rectangle { width: 200; height: 250 @@ -389,7 +383,7 @@ Rectangle { delegate: myDelegate } } -\endcode +\endqml \section1 Accessing Views and Models from Delegates @@ -408,44 +402,7 @@ In the following example, the delegate shows the property \e{language} of the model, and the color of one of the fields depends on the property \e{fruit_color} of the view. -\code -Rectangle { - width: 200; height: 200 - - ListModel { - id: fruitModel - property string language: "en" - ListElement { - name: "Apple" - cost: 2.45 - } - ListElement { - name: "Orange" - cost: 3.25 - } - ListElement { - name: "Banana" - cost: 1.95 - } - } - - Component { - id: fruitDelegate - Row { - Text { text: " Fruit: " + name; color: ListView.view.fruit_color } - Text { text: " Cost: $" + cost } - Text { text: " Language: " + ListView.view.model.language } - } - } - - ListView { - property color fruit_color: "green" - model: fruitModel - delegate: fruitDelegate - anchors.fill: parent - } -} -\endcode +\snippet doc/src/snippets/declarative/models/views-models-delegates.qml rectangle Another important case is when some action (e.g. mouse click) in the delegate should update data in the model. In this case you can define @@ -457,92 +414,11 @@ a function in the model, e.g.: ...and call it from the delegate using: -\code +\js ListView.view.model.setData(index, field, value) -\endcode +\endjs ...assuming that \e{field} holds the name of the field which should be updated, and that \e{value} holds the new value. */ - -/*! -\page qml-presenting-data.html -\title Presenting Data with QML - -\section1 Introduction - -Qt Quick contains a set of standard items that can be used to present data in a -number of different ways. For simple user interfaces, -\l{Using QML Positioner and Repeater Items#Repeaters}{Repeaters} can be used -in combination with -\l{Using QML Positioner and Repeater Items#Positioners}{Positioners} -to obtain pieces of data and arrange them in a user interface. However, when -large quantities of data are involved, it is often better to use models with -the standard views since these contain many built-in display and navigation -features. - -\section1 Views - -Views are scrolling containers for collections of items. They are feature-rich, -supporting many of the use cases found in typical applications, and can be -customized to meet requirements on style and behavior. - -A set of standard views are provided in the basic set of Qt Quick -graphical elements: - -\list -\o \l{#ListView}{ListView} arranges items in a horizontal or vertical list -\o \l{#GridView}{GridView} arranges items in a grid within the available space -\o \l{#PathView}{PathView} arranges items on a path -\endlist - -Unlike these items, \l WebView is not a fully-featured view item, and needs -to be combined with a \l Flickable item to create a view that performs like -a Web browser. - -\section2 ListView - -\l ListView shows a classic list of items with horizontal or vertical placing -of items. - -\div{float-right} -\inlineimage qml-listview-snippet.png -\enddiv - -The following example shows a minimal ListView displaying a sequence of -numbers (using an \l{QML Data Models#An Integer}{integer as a model}). -A simple delegate is used to define an items for each piece of data in the -model. - -\clearfloat -\snippet doc/src/snippets/declarative/listview/listview-snippet.qml document - - - -\section2 GridView - -\l GridView displays items in a grid like an file manager's icon view. - -\section2 PathView - -\l PathView displays items on a path, where the selection remains in -the same place and the items move around it. - -\section1 Decorating Views - -\section2 Headers and Footers - -\section2 Sections - -\section2 Navigation - -In traditional user interfaces, views can be scrolled using standard -controls, such as scroll bars and arrow buttons. In some situations, it -is also possible to drag the view directly by pressing and holding a -mouse button while moving the cursor. In touch-based user interfaces, -this dragging action is often complemented with a flicking action, where -scrolling continues after the user has stopped touching the view. - -\section1 Further Reading -*/ diff --git a/doc/src/declarative/qdeclarativestates.qdoc b/doc/src/declarative/qdeclarativestates.qdoc index 6d5aebc..655b647 100644 --- a/doc/src/declarative/qdeclarativestates.qdoc +++ b/doc/src/declarative/qdeclarativestates.qdoc @@ -27,197 +27,110 @@ /*! \page qdeclarativestates.html +\ingroup qml-features +\contentspage QML Features +\previouspage {Importing Reusable Components} +\nextpage {QML Animation and Transitions}{Animation and Transitions} \target qmlstates \title QML States -\section1 Overview - -User interfaces are designed to present different interface configurations in -different scenarios, or to modify their appearances in response to user -interaction. Often, there are a set of changes that are made concurrently, such -that the interface could be seen to be internally changing from one \e state to -another. +\section1 States Elements +\list +\o \l State +\o \l PropertyChanges +\o \l StateGroup +\o \l StateChangeScript +\o \l ParentChange +\o \l AnchorChanges +\endlist -This applies generally to interface elements regardless of their complexity. -A photo viewer may initially present images in a grid, and when an image is -clicked, change to a "detailed" state where the individual image is expanded -and the interface is changed to present new options for image editing. On the -other end of the scale, when a simple button is pressed, it may change to a -"pressed" state in which its color and position is modified to give a pressed -appearance. +Many user interface designs are \e state driven; interfaces have configurations +that differ depending on the current state. For example, a traffic signal will +configure its flags or lights depending on its state. While in the signal's +\c stop state, a red light will turn on while the yellow and the green lights +will turn off. In the \c caution state, the yellow light is on while the other +lights are turned off. -In QML, any object can change between different \e states to apply sets of -changes that modify the properties of relevant items. Each \e state could -present a different configuration that could, for example: +In QML, \e states are a set of property configurations defined in a \l State +element. Different configurations could, for example: \list \o Show some UI elements and hide others \o Present different available actions to the user -\o Start, stop or pause animations +\o Start, stop, or pause animations \o Execute some script required in the new state \o Change a property value for a particular item -\o Show a different view or "screen" +\o Show a different view or screen \endlist -Changes between states can be animated using \l {Transitions}{transitions}, as -discussed further below. - -All \l {Item}-based objects have a \e {default state}, and can specify additional -states by adding new \l State objects to the item's \l {Item::}{states} -property. Each state has a \e name that is unique for all states within that -item; the default state's name is an empty string. To change the current state +All \l {Item}-based objects have a \c state property, and can specify additional +states by adding new \c State objects to the item's \l {Item::}{states} +property. Each state within a component has a unique \c name, an empty string +being the default. To change the current state of an item, set the \l {Item::}{state} property to the name of the state. -Non-Item objects can use states through the StateGroup element. - +Non-Item objects may use states through the \l StateGroup element. \section1 Creating States To create a state, add a \l State object to the item's \l {Item::}{states} property, which holds a list of states for that item. -Following is an example. Here, the \l Rectangle is initially placed in the -default (0, 0) position. It has defined an additional state named "moved", in -which a PropertyChanges object repositions the rectangle to (50, 50). Clicking -within the MouseArea changes the state to the "moved" state, thus moving the \l -Rectangle. - -\snippet doc/src/snippets/declarative/states.qml 0 - -The \l State item defines all the changes to be made in the new state. It -could specify additional properties to be changed, or create additional -PropertyChanges for other objects. It can also modify the properties of other -objects, not just the object that owns the state. For example: - -\qml -Rectangle { - // ... - states: [ - State { - name: "moved" - PropertyChanges { target: myRect; x: 50; y: 50; color: "blue" } - PropertyChanges { target: someOtherItem; width: 1000 } - } - ] -} -\endqml - -As a convenience, if an item only has one state, its \l {Item::}{states} -property can be defined as a single \l State, without the square-brace list -syntax: - -\snippet doc/src/snippets/declarative/propertyanimation.qml single state - -A \l State is not limited to performing modifications on property values. It -can also: - +A warning \c signal component may have two states, the \c NORMAL and the +\c CRITICAL state. Suppose that in the \c NORMAL state, the \c color of the +signal should be \c green and the warning \c flag is down. Meanwhile, in the +\c CRITICAL state, the \c color should be \c red and the flag is \c up. We may +model the states using the \c State element and the color and flag +configurations with the \c PropertyChanges element. +\snippet doc/src/snippets/declarative/states.qml signal states +The \l PropertyChanges element will change the values of object properties. +Objects are referenced through their \l {qml-id-property}{id}. Objects outside +the component are also referenced using the \c id property, exemplified by the +property change to the external \c flag object. + +Further, the state may change by assigning the \c state property with the +appropriate signal state. A state switch could be in a \l MouseArea element, +assigning a different state whenever the signal receives a mouse click. +\snippet doc/src/snippets/declarative/states.qml switch states + +The State element is not limited to performing modifications on property values. +It can also: \list -\o Run some script using StateChangeScript -\o Override an existing signal handler for an object using PropertyChanges -\o Re-parent an \l Item using ParentChanges -\o Modify anchor values using AnchorChanges +\o Run some script using \l StateChangeScript +\o Override an existing signal handler for an object using \l PropertyChanges +\o Re-parent an \l Item using \l ParentChange +\o Modify anchor values using \l AnchorChanges \endlist -The \l {declarative/animation/states}{States and Transitions example} -demonstrates how to declare a basic set of states and apply animated -transitions between them. - - \section1 The Default State -Of course, the \l Rectangle in the example above could have simply been moved -by setting its position to (50, 50) in the mouse area's \c onClicked handler. -However, aside from enabling batched property changes, one of the features of -QML states is the ability of an item to revert to its \e {default state}. -The default state contains all of an item's initial property values before -they were modified in a state change. - -For example, suppose the \l Rectangle should move to (50,50) when the mouse is -pressed, and then move back to its original position when the mouse is -released. This can be achieved by using the \l {State::}{when} property, -like this: - -\qml -Rectangle { - // ... - - MouseArea { - id: mouseArea - anchors.fill: parent - } - - states: State { - name: "moved" - when: mouseArea.pressed - // ... - } -} -\endqml - -The \l {State::}{when} property is set to an expression that evaluates to -\c true when the item should be set to that state. When the mouse is pressed, -the state is changed to \e moved. When it is released, the item reverts to its -\e default state, which defines all of the item's original property values. - -Alternatively, an item can be explicitly set to its default state by setting its -\l {Item::}{state} property to an empty string (""). For example, instead of -using the \l {State::}{when} property, the above code could be changed to: - -\qml -Rectangle { - // ... - - MouseArea { - anchors.fill: parent - onPressed: myRect.state = 'moved'; - onReleased: myRect.state = ''; - } - - states: State { - name: "moved" - // ... - } -} -\endqml - -Obviously it makes sense to use the \l {State::}{when} property when possible -as it provides a simpler (and a better, more declarative) solution than -assigning the state from signal handlers. - - -\section1 Animating State Changes +Every \l Item based component has a \c state property and a \e{default state}. +The default state is the empty string (\c{""}) and contains all of an item's +initial property values. The default state is useful for managing property +values before state changes. Setting the \c state property to an empty string +will load the default state. +\section1 The \c when Property -State changes can be easily animated through \l {Transitions}{transitions}. A -\l Transition defines the animations that should be applied when an item -changes from one state to another. +For convenience, the \l State element has a \c when property that can bind to +expressions to change the state whenever the bound expression evaluates to +\c true. The \c when property will revert the state back to the +\l {The Default State}{default state} when the expression evaluates to false. -If the above example was modified to include the following \l Transition, the -movement of the \l Rectangle would be animated: +\snippet doc/src/snippets/declarative/states.qml when property +The \c bell component will change to the \c RINGING state whenever the +\c signal.state is \c CRITICAL. -\qml -Rectangle { - // ... - - MouseArea { - // Handle mouse events... - } +\section1 Animating State Changes - states: [ - // States are defined here... - ] - - transitions: [ - Transition { - NumberAnimation { properties: "x,y"; duration: 500 } - } - ] - } -\endqml +State changes induce abrupt value changes. The \l Transition element allow +smoother changes during state changes. In transitions, animations and +interpolation behaviors are definable. The +\l {QML Animation and Transitions}{Animation and Transitions} article has more +information about creating state animations. -This \l Transition defines that if any \c x or \c y properties have changed -during a state change within this item, their values should be animated over 500 -milliseconds. +The \l {declarative/animation/states}{States and Transitions example} +demonstrates how to declare a basic set of states and apply animated +transitions between them. -See the \l Transitions documentation for more information. */ diff --git a/doc/src/declarative/qml-intro.qdoc b/doc/src/declarative/qml-intro.qdoc deleted file mode 100644 index 3f3e0e4..0000000 --- a/doc/src/declarative/qml-intro.qdoc +++ /dev/null @@ -1,616 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). -** All rights reserved. -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the Technology Preview License Agreement accompanying -** this package. -** -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of this -** file. -** -** If you have questions regarding the use of this file, please contact -** Nokia at qt-info@nokia.com. -** $QT_END_LICENSE$ -** -****************************************************************************/ - - - -/*! -\page qml-intro.html -\title Intro to Qt Quick - -\section1 Overview - -QML is a high level, scripted language. Its commands, more correctly \e elements, -leverage the power and efficiency of the Qt libraries to make easy to use -commands that perform intuitive functions. Draw a rectangle, display an image at -a position and so on. Behind these elements are complex C++ libraries that -efficiently perform the action. As with any graphical application, always -consider that this ability to easily build graphically rich applications means -that some care may be needed to prevent performance problems. - -The language also allows more flexibility of these commands by using -Javascript rather than C++ to add new layers of logic to your application. -Javascript is easier to learn than C++ and can be embedded into the QML -files or imported from a separate file. - -\bold{In QML the types of various 'objects' are referred to as \l {QML -Elements}{elements}}. - -An element usually has various \e properties that help define the element. For -example, if we created an element called Circle then the radius of the circle -would be a property. - - -\section1 A First Look - -The basic syntax of an \l{QML Elements}{element} is - -\qml -SomeElement { - id: myObject - // ... some other things here ... -} -\endqml - -Here we are defining a new object. We specify its 'type' first as SomeElement. -Then within matching braces { ... } we specify the various parts of our -element. - -The \c id is a unique identifier for the element, it must start with a lower -case letter and only contain letters, numbers and underscores. It is this -particular object's name. If this SomeElement \l {QML Elements}{element} was -a Rectangle instead and it was one of many then the \e optional unique id -would allow us to manipulate each element individually. - -Each visual element is ultimately based on, or inherits from, an element -called \l Item. \l Item has certain properties and actions that may be -useful. The properties have default values so you need only specify the -ones you will need. - -Take a simple element such as a \l Rectangle. It has an \c id, we will call -it \e myRectangle, it has a \c width and a \c height. Imagine that we -want a rectangle that is 500 pixels by 400 pixels in the x and y directions -(horizontal by vertical). - -We can implement this \l Rectangle with these properties this way - -\snippet doc/src/snippets/declarative/qml-intro/rectangle.qml document - -This is a valid QML script. To run it, copy it and save it to a file, say -myexample.qml, and on the command line run the following command: - -\code -qmlviewer myexample.qml -\endcode - -On Mac OS X, open the "QMLViewer" application instead and open the -\c myexample.qml file, or run it from the command line: - -\code -QMLViewer.app/Contents/MacOS/QMLViewer myexample.qml -\endcode - -It will create a very boring rectangle in its own window. - - -\section1 Hello World! - -We can now add some color and text to make a Hello World QML program. - -\l Rectangle has the property \l{Rectangle::color}{color} to produce a -background color. - -Text is handled by a different element called \l Text. We need to create a -\l Text object inside the \l Rectangle and set its \l{Text::}{text} -property to "Hello World!". So to set the text to "Hello world" and the -background colour to light gray, - -\snippet doc/src/snippets/declarative/qml-intro/hello-world1.qml document - - -\section1 Hello World Again - -From now on we will not always show the import statement for Qt but it -should still be there when you create your QML scripts. - -To make our Hello World example a little nicer set the position of the text -to be at pixel position x = 100, y = 100 within the displayed window. This -position belongs to the \l Text element so we set the position inside its -definition. Note that we separate different QML statements on the same line -with a semi-colon, or we could have simply put each statement on a new line - -\snippet doc/src/snippets/declarative/qml-intro/hello-world2.qml updated text - -Not only did we reposition the text, but the text was altered by adding -HTML tags to change the font size. The text color was also changed from the -default black to dark green by using a standard string for the color's SVG -name. - -We could also have used a hexadecimal string for the RGB (red-green-blue, as -#rrggbb) values of the color similar to the method used in HTML. For -example, mostly blue with a green tint, - -\snippet doc/src/snippets/declarative/qml-intro/hello-world3.qml updated text - -All of these changes occurred within the \l Text object which is the scope -of these property changes. - -Other objects may use the information but it belongs to the element where -the property has been defined. - - -\section1 Images - -To add an image to our little application we use the \l Image element. An -\l Image uses a path to an image file, and has properties to control -the aspect ratio, the image size, to tile the area amongst others. The -source of the image, the path to the file, is a URL. Therefore the file can -be local: \e {mydir/myimage1.png}. Or it can be remote: -\e {"http://www.example.com/images/myimage1.png"}. - -\snippet doc/src/snippets/declarative/qml-intro/hello-world4.qml added an image - -This displays the image, as we would expect, at the top left of the window. -The position of the default x = 0, y = 0 coordinate. The example here uses -a PNG file, but it could have been one of various supported formats, -including JPG and GIF. - -Let us reposition the image and enlarge it. Place it at the same 'x' offset -as the "Hello world again" text, but put it another 50 pixels below the -text, also make it 150 by 150 pixels in size, - -\snippet doc/src/snippets/declarative/qml-intro/hello-world5.qml positioning the image - -Adding the Hello World example, with the text and the image example we can -write a simple piece of QML that starts to look a bit better. - -\snippet doc/src/snippets/declarative/qml-intro/hello-world5.qml document - -The result is still quite simple - -\image qml-intro-helloa.png - - -\section1 Anchors: Aligning Elements - -Using absolute positioning, such as saying x = 100 and y = 150, works well -until the user or developer stretches or increases the size of the window. -Then the positions need to be recalculated. What would be nice would be a -relative means of positioning of objects in a window or rectangle. For -example, we want to place an image at the bottom of a rectangle, we would -like to specify the image's location as the 'bottom of the window', not a -specific coordinate. We can do this with the anchors property, which -objects inherit from Item. - -The anchors property is really a property group. It is a collection of -related properties. It has properties within it which can be used by means -of the dot notation. - -The dot notation uses object \c{id}s and property names to use a particular -object or property. Say I have a rectangle r1, which contains a rectangle -r2, which contains an Item item1, which has an 'x' property I want to -change. I just use the dot notation to identify it: r1.r2.item1.x - -If we want to position an image at the bottom of the rectangle it is -inside. I have to specify that the bottom of the image is also at the -bottom of the rectangle - -\snippet doc/src/snippets/declarative/qml-intro/anchors1.qml document - -This places the logo at the bottom left of the window. - -\image qml-intro-anchors1.png "A simple anchor" - -We would like it centered and not touching the bottom of the window, for -aesthetic reasons. For the centering we use the horizontalCenter property, -and to prevent the touching of the image to the bottom of the rectangle, -the bottomMargin property is used. So the new actions for the script are - - \list - \o set the bottom of the image (anchors.bottom) to be the bottom of the window - \o move the image to be in the horizontal center of the window - \o set a margin of 10 pixels so that the image does not touch the bottom window border - \endlist - -Encoded into QML the script becomes - -\snippet doc/src/snippets/declarative/qml-intro/anchors2.qml document - -Run this and resize the window. You will see that now the position of the -image adjusts during the resize. - -\image qml-intro-anchors2.png "Image Centered at the Bottom" - -You can also add another object say a block of descriptive text and place -it above or below the image or to the side. This code places some text just -above the image - -\snippet doc/src/snippets/declarative/qml-intro/anchors3.qml adding some text - -\image qml-intro-anchors3.png - -\note \e anchors is a property group, to be used within the object. When -referencing these properties from another object we use the property -directly, instead of saying: - -\qml -Item { - anchors.bottom: myRectangle.anchors.top // Wrong -} -\endqml - -we use - -\qml -Item { - anchors.bottom: myRectangle.top // Correct -} -\endqml - - -\section1 Transformations - -We can transform a graphical object to get additional effects. Rotate a -piece of text by 180 degrees to display upside-down text. Rotate an image -by 90 degrees to lay it on its side. These transformations require -additional information. - -For rotation, the additional information includes: the origin relative to -the object being rotated, the axis of rotation, and the angle in degrees to -rotate the image through in a clockwise direction. The axis does not have -to be the z-axis, the line between your eyes and the image, it could be -along the vertical y-axis or the horizontal x-axis. We have three -dimensions to play with. For simplicity in this example we will rotate -about the z-axis by 90 degrees in a negative direction, anti-clockwise. - -Rotation of text was also suggested. It could also be useful to scale the -text. We can do both. The \l {Item::transform}{transform} property is a -\e list of \l Transform elements, so using the list syntax -\c{myList: [ listElement1, listElement2, ... } ]} -we can produce a list of transformations. - -The text will be rotated by 45 degrees anti-clockwise and scaled -vertically by a factor of 1.5 and by 1.2 horizontally. - -Using the example above as the basis for this we have, - -\snippet doc/src/snippets/declarative/qml-intro/transformations1.qml document - -The code block in \c image1 starting with \c transform specifies that the -\l {Item::transform}{transform} property will be a Rotation through -90 -degrees, which is anti-clockwise, about the z-axis running through the -center of the image at (75,75), since the image is 150 x 150 pixels. - -The other transformation available is \l Translate. This produces a change -in position of the item. - -\note In a list of transformations the order of the transformations is -important. In the above example try swapping around the Scale transform with -the Rotation transform, remember to remove or add the comma. The results are -acceptable for our little test but not the same. - - -\section1 Animations - -Animation in QML is done by animating properties of objects. Properties -that are numbers, colors, Rectangles, points and directions. In QML these -are \l {QML Basic Types} named as real, int, color, rect, point, size, and -vector3d. There are a number of different ways to do animation. Here we -will look at a few of them. - -\section2 Number Animation - -Previously we have used a rotation transformation to change the orientation -of an image. We could easily animate this rotation so that instead of a -straight rotation counter-clockwise of 90 degrees we could rotate the image -through a full 360 degrees in an animation. The axis of rotation wont -change, the position of the center of the image will not change, only the -angle will change. Therefore, a NumberAnimation of a rotation's angle should -be enough for the task. If we wish for a simple rotation about the center -of the image then we can use the \c rotation property that is inherited -from \l Item. The rotation property is a real number that specifies the -angle in a clockwise direction for the rotation of the object. Here is the -code for our animated rotating image. - -\snippet doc/src/snippets/declarative/qml-intro/number-animation1.qml document - -The \c {transformOrigin: Item.Center} is redundant since this is the default -axis of rotation anyway. But if you change \c Center to \c BottomRight you -will see an interesting variation. - -Also if instead the \l Rotation transformation had been used then we would have -more control over the various parameters. We could vary the axis, to be not -just a different offset from the z-axis but along the y-axis, x-axis or -combination. For example, if the task had been to animate the rotation -about the y-axis passing through the center of the image then the following -code would do it. - -\snippet doc/src/snippets/declarative/qml-intro/number-animation2.qml document - -Here there is a rectangle 600 by 400 pixels. Placed within that rectangle -is an image 100 by 100 pixels. It is rotated about the center of the image -about the y-axis so that it looks as if it is rotating about an invisible -vertical string holding it up. The time it takes to complete the rotation is 3 -seconds (3,000 milliseconds). The NumberAnimation is applied to the angle -taking it from 0 (no change) to 360 degrees, back where it started. -Strictly speaking it isn't necessary to go from 0 to 360 since the same -location is duplicated, but it makes it easier to read in this example and -it has no visible effect on the animation. The number of loops that the -animation will execute is set to \c {Animation.Infinite} which means that the -animation is in an endless loop. - -To see an interesting variation. Change the axis to \c {axis { x:1; y:1; z:1 -}}. This is a line coming from the center of the image downwards to the -right and out of the screen. Although the change is simple the rotation -seems complex. - -\section2 Sequential Animation - -For a more complex animation we will need two images. The first image will -be placed at the center of a window (Rectangle) and the second image will -be at the upper left of the window. The animation will move the second -image from the top left of the window to the bottom right. In doing so we -will be animating the position and the size of the image. - -First create two images - -\snippet doc/src/snippets/declarative/qml-intro/sequential-animation1.qml document - -We will add to 'image1' a SequentialAnimation from x = 20 to the target of -x = 450. The 'from' values will be used because we will be repeating the -animation, so the object needs to know where the original position is, both -x and y. The SequentialAnimation of x will set it to repeat by indicating -that the number of animation loops is infinite, meaning that the 'loop' -counter will be set to a value Animation.Infinite that indicates an endless -cycle. Also there will be a NumberAnimation to vary the numeric property -between the x values and over a given duration. After the NumberAnimation -there will be a PauseAnimation that will pause the animation for 500 -milliseconds (half a second) simply for the visual effect. - -\snippet doc/src/snippets/declarative/qml-intro/sequential-animation2.qml adding a sequential animation - -A similar block of code is written for the animation of the 'y' value of -the position. - -We will also animate the scale of the object, so as it goes from top left -to bottom right of the window it will become smaller until about midway, -and then become larger. To complete the animation we will set the 'z' -values of the images. 'z' is the stacking order, the z-axis effectively -points out from the screen to your eyes with the default value of 'z' being -0. So if we set the Rectangle to have z with value zero, just to be sure, -and image1 to 1 and image2 to 2 then image2 will be in the foreground and -image1 in the background. When image1 passes image2 it will pass behind it. -The completed code looks like - -\snippet doc/src/snippets/declarative/qml-intro/sequential-animation3.qml document - -The \c {easing.type} has many options, expressed as a string. It specifies the -kind of equation that describes the acceleration of the property value, not -necessarily position, over time. - -For example, \e InOutQuad means that at the start and the end of the animation the -'velocity' is low but the acceleration or deceleration is high. Much like a car -accelerating from stop, and decelerating to stop at the end of a journey, -with the maximum speed being in the middle. Examine the \l {PropertyAnimation::easing.type} -{easing} documentation and the various graphs that show the effect. The horizontal -axis, 'progress', can be thought of as time. The vertical axis is the value -of the particular property. - -In discussing animation we need to describe three objects: State, MouseArea -and Signals. Although independent of the animation elements, animation -delivers some of the best examples that illustrate these new elements. - - - -\section2 Animation Summary - -\table - \header - \o Name - \o Description - \row - \o PropertyAnimation - \o a property value on a target object is varied to a specified value over a given time. - - \row - \o NumberAnimation - \o animate a numeric property from one value to another over a given time. - - \row - \o PauseAnimation - \o results in the task waiting for the specified duration, in milliseconds. - - \row - \o SequentialAnimation - \o allows us to list in order the animation events we want to occur, first A then B then C and so on. - - \row - \o ParallelAnimation - \o enables us to run different animations at the same time instead of sequentially. - -\endtable - - -\section1 Using States - -A state is a defined set of values in the configuration of an object and -often depends on the previous state. For example, a glass could be in a -state we call 'HalfFull' if it is being filled with a liquid and has -reached half of its total capacity. We could also have a state called -HalfEmpty which is the state that occurs when the amount of liquid drops to -half of the glass's capacity. Both states represent the same amount of -liquid, but we consider them different. Likewise, states in a program -represent not just values but may include how the current values were -reached. - -When a state changes a \e transition occurs. This is an opportunity to make -changes or take actions that depend on the movement to the new state. For -example, if we had a scene in the country where the state variable has two -states "daylight" and "night". Then when the state changes to "night" at -this transition the sky would be made dark, stars would be shown, the -countryside would be darkened. And when the state changes to "daylight" the -opposite changes would be made: the sky is now blue, the scenery is green, -there is a sun in the sky. - -Here is a simple QML program that shows the change of state in the above -example. We have two rectangles, the top one is the 'sky' and the bottom -one is the 'ground'. We will animate the change from daylight to night. -There will be two states, but we only need to define one since 'daylight' -will be the default state. We will just go to 'night' by clicking and -holding the left mouse button down, releasing the mouse button will reverse -the process - -\snippet doc/src/snippets/declarative/qml-intro/states1.qml document - -Several new things appear in this sample. Firstly, we use a \l MouseArea -element to detect mouse clicks in the \e mainRectangle. Secondly, we use -the list notation [ thing1 , thing2, ... ] to build a list of states and a -list of transitions. - -\l MouseArea defines a region that will respond to mouse clicks. In this case -we are only concerned with when the mouse is pressed or not pressed, not -the particular button or other details. The area of the MouseArea is the -entire main window, mainRectangle, so that clicking anywhere in this region -will start the animation. Since we are using the 'pressed' mouse state, -then the animation will move from 'daylight' to 'night' only while the mouse -button remains pressed. - -When the button is released the 'daylight' state is entered and the -transition from 'night' to 'daylight' is triggered causing the animation to -run. The transition specifies the duration in milliseconds of the -ColorAnimation, while the state specifies the color of the new state. - -The PropertyChanges command is the way that we nominate which properties -will change in a change of state, and what new value the property will -take. Since, for example, we want the 'sky' region to turn to dark blue and -the 'ground' region to turn to black for the 'night' state, then the -rectangles for those regions are the 'target' and the property in the target -is 'color'. - - -\section1 Signals - -Signals are simply events that can be hooked up to actions we want performed. -In QML they are usually preceded by the word 'on', for example in the animation -using a MouseArea the signal was \l {MouseArea::onPressed}{onPressed}. If -you look at the C++ documentation you will see a lot of talk about -\l {Signals & Slots}{Signals and Slots}. Signals are connected to Slots. The -signal represents an event and the Slot is the function that does something -based on that event. You can also have Signals connected to other Signals, so -that one Signal (event) triggers another Signal (event), and so forth. It is -nice to know this is what happens beneath the QML layer but not essential for -using QML. - -Most elements do not have Signals associated with them. However, a few like -the \l Audio element have many signals. Some of the \l Audio signals are -used to represent events such as when the audio is stopped, play is pressed, -paused, and reaching the end of the media. They allow the developer to connect, - for example, the press of a user interface button (perhaps a MouseArea) to - some QML that will handle this event. - - -\section1 Analyzing An Example: Dial Control - -In the Qt \e {examples/declarative/ui-components} folder you will find a folder -\e {dialcontrol} which contains the \e dialcontrol example. - -\image qml-dial.png "QML Dial example with Slider" - -In essence this small application has a sliding bar that you can slide using -a mouse, and a graphical dial that responds to the position of the slider. - -The code for the example is in two parts: Dial.qml and dialcontrol.qml. - -\e {Dial.qml} can be found in the \e content sub-directory. It defines a \c Dial -component similar to an odometer. Eventually, the example will hook up a slider -component so that moving the slider will change the position of a needle on the -dial. - -The code for the \c Dial, identified by the name of the file, contains four images -in overlapping order: the background (numbers and divisions), the shadow of the -needle, the needle itself, and finally the 'glass' overlay (containing -transparent layers). - -The \c needle_shadow.png image has a \l Rotation assigned to the \e transform -attribute of the \l Image. The rotation is set to match the angle of the needle -image angle value \e {needleRotation.angle}. Both the needle and the -needle_shadow have the same default \e x and \e y values but the rotation origin -for the needle is slightly different so that a shadow will be evident as the -needle moves. - -\snippet examples/declarative/ui-components/dialcontrol/content/Dial.qml needle_shadow - -And the needle - -\snippet examples/declarative/ui-components/dialcontrol/content/Dial.qml needle - -The final image is the overlay which simply has a position defined. - -\snippet examples/declarative/ui-components/dialcontrol/content/Dial.qml overlay - -\e {dialcontrol.qml} in the \e {examples/declarative/ui-components/dialcontrol} directory is the -main file of the example. It defines the visual environment that the Dial -will fit into. Because the \e Dial component and the images live in the \e -content sub-directory we will have to import this into \e dialcontrol.qml. So the -start of the file looks like - -\snippet examples/declarative/ui-components/dialcontrol/dialcontrol.qml imports - -The visual space is bound by a 300 by 300 pixel \l Rectangle which is given -a gray color. Inside this rectangle is our component \e Dial and a \l Rectangle. -Inside the rectangle called 'container' is another rectangle with the -interesting name 'slider'. - -\snippet examples/declarative/ui-components/dialcontrol/dialcontrol.qml 0 - -The Dial component, named 'dial, is \e anchored to the center of the main -rectangle. The \c value attribute of 'dial' is set to a value based on the -'slider' horizontal position and the 'container' width. So changes to the -'slider' position will change the Dial \c value which is used in Dial to compute -the rotation of the needle image. Notice this piece of code in Dial where -the change in \c value modifies the position of the needle. - -\snippet examples/declarative/ui-components/dialcontrol/content/Dial.qml needle angle - -This is part of the \c needleRotation that rotates the needle and causes the -rotation of its shadow. \l SpringAnimation is an element that modifies the value -of that rotation \e angle and mimics the oscillatory behavior of a spring, -with the appropriate \e spring constant to control the acceleration and the \e -damping to control how quickly the effect dies away. - -The 'container' is light gray with a color gradient defined using -\l GradientStop. The gradient is applied vertically. If you need a horizontal -gradient then you could apply the vertical gradient and then rotate the item -by 90 degrees. - -The 'slider' is dark gray and also has a vertical color gradient. The most -important thing about the 'slider' is that it has a MouseArea defined, which -specifies a \c {drag.target} on itself along the X-axis. With minimum -and maximum values on the X-axis defined. So we can click on the 'slider' and -drag it left and right within the confines of the 'container'. The motion of -the 'slider' will then change the \c value attribute in \e Dial as discussed -already. - -Also notice the use of a \c radius value for a rectangle. This produces rounded -corners. That is how the 'container' and 'slider' are displayed with a -pleasant rounded look. - - - -*/ - - - diff --git a/doc/src/declarative/qmlevents.qdoc b/doc/src/declarative/qmlevents.qdoc new file mode 100644 index 0000000..566f71c --- /dev/null +++ b/doc/src/declarative/qmlevents.qdoc @@ -0,0 +1,127 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qmlevents.html +\ingroup qml-features +\contentspage QML Features +\previouspage {Keyboard Focus in QML}{Keyboard Focus} +\nextpage Importing Reusable Components + +\title QML Signal and Handler Event System + +QML utilizes Qt's \l{The Meta-Object System}{meta-object} and +\l{Signals & Slots}{signals} systems. Signals and slots created using Qt in C++ +are inheritely valid in QML. + +\keyword qml-signals-and-handlers +\section1 Signals and Handlers + +Signals provide a way to notify other objects when an event has occurred. For +example, the MouseArea \c clicked signal notifies other objects that the mouse +has been clicked within the area. + +The syntax for defining a new signal is: + +\tt{signal <name>[([<type> <parameter name>[, ...]])]} + +Attempting to declare two signals or methods with the same name in the same type +block generates an error. However, a new signal may reuse the name of an existing signal on the type. (This should be done with caution, as the existing signal may be hidden and become inaccessible.) + +Here are various examples of signal declarations: +\snippet doc/src/snippets/declarative/events.qml parent begin +\snippet doc/src/snippets/declarative/events.qml signal declaration +\snippet doc/src/snippets/declarative/events.qml parent end + +If the signal has no parameters, the "\c{()}" brackets are optional. If +parameters are used, the parameter types must be declared, as for the \c string +and \c variant arguments of the \c perform signal. + +Adding a signal to an item automatically adds a \e{signal handler} as well. The +signal hander is named \c on<SignalName>, with the first letter of the signal in +uppercase. The previous signals have the following signal handlers: +\snippet doc/src/snippets/declarative/events.qml signal handler declaration + +Further, each QML properties have a \c{<property_name>Changed} signal and its +corresponding \c{on<property_name>Changed} signal handler. As a result, property +changes may notify other components for any changes. +\snippet doc/src/snippets/declarative/events.qml automatic signals + +To emit a signal, invoke it as a method. The signal handler binding is similar +to a property binding and it is invoked when the signal is emitted. Use the +defined argument names to access the respective arguments. +\snippet doc/src/snippets/declarative/events.qml signal emit +Note that the \c Component.onCompleted is an +\l{attached-signalhandlers}{attached signal handler}; it is invoked when the +\l Component initialization is complete. + +\keyword qml-connect-signals-to-method +\section2 Connecting Signals to Methods and Signals + +Signal objects have a \c connect() method to a connect a signal either to a +method or another signal. When a signal is connected to a method, the method is +automatically invoked whenever the signal is emitted. (In Qt terminology, the +method is a \e slot that is connected to the \e signal; all methods defined in +QML are created as \l{Signals & Slots}{Qt slots}.) This enables a signal +to be received by a method instead of a \l {Signal Handlers}{signal handler}. + +\snippet doc/src/snippets/declarative/events.qml connect method +The \c {connect()} method is appropriate when connecting a JavaScript method to +a signal. + +There is a corresponding \c disconnect() method for removing connected +signals. + +\section3 Signal to Signal Connect + +By connecting signals to other signals, the \c connect() method can form different +signal chains. +\snippet doc/src/snippets/declarative/events.qml forward signal + + +Whenever the \l MouseArea \c clicked signal is emitted, the \c send +signal will automatically be emitted as well. + +\code +output: + MouseArea clicked + Send clicked +\endcode + +\section1 C++ Additions + +Because QML uses Qt, a signal defined in C++ also works as a QML signal. The +signal may be emitted in QML code or called as a method. In addition, the QML +runtime automatically creates signal handlers for the C++ signals. For more +signal control, the \c connect() method and the \l Connections element may connect +a C++ signal to another signal or method. + +For complete information on how to call C++ functions in QML, read the +\l{Extending QML - Signal Support Example}. + + +*/ diff --git a/doc/src/declarative/qmlreusablecomponents.qdoc b/doc/src/declarative/qmlreusablecomponents.qdoc new file mode 100644 index 0000000..ee360eb --- /dev/null +++ b/doc/src/declarative/qmlreusablecomponents.qdoc @@ -0,0 +1,143 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qmlreusablecomponents.html +\ingroup qml-features +\previouspage {QML Signal and Handler Event System}{Signal and Handler Event System} +\nextpage {QML States}{States} +\contentspage QML Features + +\title Importing Reusable Components + +A \e component is an instantiable QML definition, typically contained in a +\c .qml file. For instance, a Button \e component may be defined in +\c Button.qml. The QML runtime may instantiate this Button component to create +Button \e objects. Alternatively, a component may be defined inside a +\l Component element. + +Moreover, the Button definition may also contain other components. A Button +component could use a Text element for its label and other components to +implement its functions. Compounding components to form new components +(and effectively new interfaces) is the emphasis in QML. + +\keyword qml-define-components +\section1 Defining New Components + +Any snippet of QML code may become a component, by placing the code in a QML +file (extension is \c .qml). A complete Button component that responds to user +input may be in a Button.qml file. +\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml document + +Alternatively, a \l Component element may encapsulate a QML object to form a +component. +\snippet doc/src/snippets/declarative/reusablecomponents/component.qml parent begin +\snippet doc/src/snippets/declarative/reusablecomponents/component.qml define inline component +\snippet doc/src/snippets/declarative/reusablecomponents/component.qml parent end + +\keyword qml-loading-components +\section1 Loading a Component + +The initialization of inline components is different from loading a component +from a \c .qml file. + +\section2 Importing a Component + +A component defined in a \c .qml file is directly usable by declaring the name +of the component. For example, a button defined in \c Button.qml is created by +declaring a \c Button. The button is defined in the +\l {qml-define-components}{Defining New Components} section. +\snippet doc/src/snippets/declarative/reusablecomponents/application.qml document + +Note that the component name, \c Button, matches the QML filename, \c Button.qml. +Also, the first character is in upper case. Matching the names allow +components in the same directory to be in the direct import path of the +application. + +For flexibility, a \c qmldir file is for dictating which additional components, +plugins, or directories should be imported. By using a \c qmldir file, +component names do not need to match the filenames. The \c qmldir file should, +however, be in an imported path. +\snippet doc/src/snippets/declarative/reusablecomponents/qmldir document + +\section2 Loading an Inline Component + +A consequence of inline components is that initialization may be deferred or +delayed. A component may be created during a MouseArea event or by using a +\l Loader element. The component can create an object, which is addressable in a +similar way as an \l {qml-id-property}{id property}. Thus, the created object may +have its bindings set and read like a normal QML object. +\snippet doc/src/snippets/declarative/reusablecomponents/component.qml define inline component +\snippet doc/src/snippets/declarative/reusablecomponents/component.qml create inline component + +\keyword qml-component-properties +\section1 Component Properties + +Initializing a component, either from a .qml file or initializing an inline +component, have several properties to facilitate component execution. +Specifically, there are \l{attached-properties}{attached properties} and +\l{attached-signalhandlers}{attached signal handlers} for setting properties +during the lifetime of a component. + +The \c{Component.onCompleted} attached signal handler is called when the +component completes initialization. It is useful for executing any commands +after component initialization. Similarly, the \c{Component.onDestruction} +signal handler executes when the component finishes destruction. + +\keyword qml-top-level +\section1 Top-Level Component + +Choosing the \e{top-level} or the \e{root} object of components is an important +design aspect because the top-level object dictates which properties are +accessible outside the component. Some elements are not visual elements and +will not have visual properties exposed outside the component. Likewise, some +elements add functionality that are not available to visual elements. + +Consider the Button component from the +\l{qml-define-components}{Defining New Components} section; it's top-level +object is a \l Rectangle. When imported, the Button component will possess the +Rectangle's properties, methods, signals, and any custom properties. + +\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml parent begin +\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml ellipses +\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml properties +\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml ellipses +\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml parent end + +The Button's \c text alias is accessible from outside the component as well as +the Rectangle's visual properties and signals such as \c x, \c y, \c anchors, +and \c states. + +Alternatively, we may choose a \l {Keyboard Focus in QML}{FocusScope} as our +top-level object. The \l FocusScope element manage keyboard focus for its +children which is beneficial for certain types of interfaces. However, since +\c FocusScopes are not visual elements, the visual properties of its child need +to be exposed. + +\snippet doc/src/snippets/declarative/reusablecomponents/focusbutton.qml document +*/ + diff --git a/doc/src/declarative/qmlruntime.qdoc b/doc/src/declarative/qmlruntime.qdoc index f6604fb..a1f3f96 100644 --- a/doc/src/declarative/qmlruntime.qdoc +++ b/doc/src/declarative/qmlruntime.qdoc @@ -29,13 +29,13 @@ \page qmlruntime.html \title Qt Declarative UI Runtime -QML documents are loaded and executed by the QML runtime. This includes the +QML documents are loaded and executed by the QML runtime. This includes the Declarative UI engine along with the built-in QML elements and plugin modules, and it also provides access to third-party QML elements and modules. -Applications that use QML need to invoke the QML runtime in order to -execute QML documents. This can be done by creating a QDeclarativeView -or a QDeclarativeEngine, as described below. In addition, the Declarative UI +Applications that use QML need to invoke the QML runtime in order to +execute QML documents. This can be done by creating a QDeclarativeView +or a QDeclarativeEngine, as described below. In addition, the Declarative UI package includes the \QQV tool, which loads \c .qml files. This tool is useful for developing and testing QML code without the need to write a C++ application to load the QML runtime. @@ -44,7 +44,7 @@ a C++ application to load the QML runtime. \section1 Deploying QML-based applications -To deploy an application that uses QML, the QML runtime must be invoked by +To deploy an application that uses QML, the QML runtime must be invoked by the application. This is done by writing a Qt C++ application that loads the QDeclarativeEngine by either: @@ -61,12 +61,12 @@ For example, if there is a QML file, \c application.qml, like this: \qml import QtQuick 1.0 - + Rectangle { width: 100; height: 100; color: "red" } \endqml It can be loaded in a Qt application's \c main.cpp file like this: - + \code #include <QApplication> #include <QDeclarativeView> @@ -82,10 +82,10 @@ It can be loaded in a Qt application's \c main.cpp file like this: return app.exec(); } \endcode - -This creates a QWidget-based view that displays the contents of + +This creates a QWidget-based view that displays the contents of \c application.qml. - + The application's \c .pro \l{qmake Project Files}{project file} must specify the \c declarative module for the \c QT variable. For example: @@ -97,36 +97,36 @@ the \c declarative module for the \c QT variable. For example: \section2 Creating a QDeclarativeEngine directly - -If \c application.qml does not have any graphical components, or if it is + +If \c application.qml does not have any graphical components, or if it is preferred to avoid QDeclarativeView for other reasons, the QDeclarativeEngine can be constructed directly instead. In this case, \c application.qml is loaded as a QDeclarativeComponent instance rather than placed into a view: \code #include <QApplication> - #include <QDeclarativeEngine> + #include <QDeclarativeEngine> #include <QDeclarativeContext> #include <QDeclarativeComponent> int main(int argc, char *argv[]) { QApplication app(argc, argv); - + QDeclarativeEngine engine; QDeclarativeContext *objectContext = new QDeclarativeContext(engine.rootContext()); - + QDeclarativeComponent component(&engine, "application.qml"); QObject *object = component.create(objectContext); - + // ... delete object and objectContext when necessary - + return app.exec(); } \endcode -See \l {Using QML in C++ Applications} for more information about using -QDeclarativeEngine, QDeclarativeContext and QDeclarativeComponent, as well +See \l {Using QML Bindings in C++ Applications} for more information about using +QDeclarativeEngine, QDeclarativeContext and QDeclarativeComponent, as well as details on including QML files through \l{The Qt Resource System}{Qt's Resource system}. @@ -135,8 +135,8 @@ as details on including QML files through \l{The Qt Resource System}{Qt's Resour The Declarative UI package includes a QML runtime tool, the \QQV, which loads and displays QML documents. This is useful during the application development -phase for prototyping QML-based applications without writing your own C++ -applications to invoke the QML runtime. +phase for prototyping QML-based applications without writing your own C++ +applications to invoke the QML runtime. See the \l{QML Viewer} documentation for more details. diff --git a/doc/src/declarative/qmlsyntax.qdoc b/doc/src/declarative/qmlsyntax.qdoc new file mode 100644 index 0000000..fc25bce --- /dev/null +++ b/doc/src/declarative/qmlsyntax.qdoc @@ -0,0 +1,155 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qmlsyntax.html +\title QML Syntax +\ingroup QML Reference +\contentspage QML Reference + +\tableofcontents + +QML is a declarative language designed to describe the user interface of a +program: both what it looks like, and how it behaves. In QML, a user +interface is specified as a tree of objects with properties. + +JavaScript is used as a scripting language in QML, so you may want +to learn a bit more about it (\l{Javascript Guide}) before diving +deeper into QML. + +\section1 Basic QML Syntax + +QML looks like this: + +\code +import QtQuick 1.0 + +Rectangle { + width: 200 + height: 200 + color: "blue" + + Image { + source: "pics/logo.png" + anchors.centerIn: parent + } +} +\endcode + +Objects are specified by their type, followed by a pair of braces. Object +types always begin with a capital letter. In the above example, there are +two objects, a \l Rectangle, and an \l Image. Between the braces, we can specify +information about the object, such as its properties. + +Properties are specified as \c {propertyname: value}. In the above example, we +can see the Image has a property named \c source, which has been assigned the +value \c "pics/logo.png". The property and its value are separated by a colon. + +Properties can be specified one-per-line: + +\code +Rectangle { + width: 100 + height: 100 +} +\endcode + +or you can put multiple properties on a single line: + +\code +Rectangle { width: 100; height: 100 } +\endcode + +When multiple property/value pairs are specified on a single line, they +must be separated by a semicolon. + +The \c import statement imports the \c Qt \l{QML Modules}{module}, which contains all of the +standard \l {QML Elements}. Without this import statement, the \l Rectangle +and \l Image elements would not be available. + +\section1 Expressions + +In addition to assigning values to properties, you can also assign +expressions written in JavaScript. + +\code +Rotation { + angle: 360 * 3 +} +\endcode + +These expressions can include references to other objects and properties, in which case +a \e binding is established: when the value of the expression changes, the property the +expression has been assigned to is automatically updated to that value. + +\code +Item { + Text { + id: text1 + text: "Hello World" + } + Text { + id: text2 + text: text1.text + } +} +\endcode + +In the example above, the \c text2 object will display the same text as \c text1. If \c text1 is changed, +\c text2 is automatically changed to the same value. + +Note that to refer to other objects, we use their \e id values. (See below for more +information on the \e id property.) + +\section1 QML Comments + +Commenting in QML is similar to JavaScript. +\list +\o Single line comments start with // and finish at the end of the line. +\o Multiline comments start with /* and finish with *\/ +\endlist + +\snippet doc/src/snippets/declarative/comments.qml 0 + +Comments are ignored by the engine. They are useful for explaining what you +are doing; for referring back to at a later date, or for others reading +your QML files. + +Comments can also be used to prevent the execution of code, which is +sometimes useful for tracking down problems. + +\code +Text { + text: "Hello world!" + //opacity: 0.5 +} +\endcode + +In the above example, the Text object will have normal opacity, since the +line opacity: 0.5 has been turned into a comment. + +*/ diff --git a/doc/src/declarative/qmltexthandling.qdoc b/doc/src/declarative/qmltexthandling.qdoc new file mode 100644 index 0000000..7906193 --- /dev/null +++ b/doc/src/declarative/qmltexthandling.qdoc @@ -0,0 +1,76 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page texthandling.html +\title QML Text Handling and Validators +\ingroup QML Features +\previouspage {QML Mouse Events}{Mouse Events} +\nextpage {Keyboard Focus in QML}{Keyboard Focus} +\contentspage QML Features + +\tableofcontents + +\section1 Text Elements + +\list +\o \l{Text} +\o \l{TextInput} +\o \l{TextEdit} +\endlist + +\section1 Validators +\list +\o \l{IntValidator} +\o \l{DoubleValidator} +\o \l{RegExpValidator} +\endlist + +\section1 Displaying Text in QML +QML provides several elements to display text onto the screen. The \l Text +element will display formatted text onto the screen, the \l TextEdit element +will place a multiline line edit onto the screen, and the \l TextInput will +place a single editable line field onto the screen. + +To learn more about their specific features and properties, visit their +respective element documentation. + +\section1 Validating Input Text +The \l {Validators}{validator} elements enforce the type and format of +\l TextInput objects. + +\snippet doc/src/snippets/declarative/texthandling.qml int validator +The validator elements bind to \c {TextInput}'s \c validator property. + +\snippet doc/src/snippets/declarative/texthandling.qml regexp validator +The regular expression in the snippet will only allow the inputted text to be +\c {fruit basket}. + +Note that QML parses JavaScript regular expressions, while Qt's +\l {QRegExp} class' regular expressions are based on Perl regular expressions. + +*/ diff --git a/doc/src/declarative/qmlviewer.qdoc b/doc/src/declarative/qmlviewer.qdoc index 585b402..2e3cdc7 100644 --- a/doc/src/declarative/qmlviewer.qdoc +++ b/doc/src/declarative/qmlviewer.qdoc @@ -31,34 +31,34 @@ \title QML Viewer \ingroup qttools -The Declarative UI package includes \QQV, a tool for loading QML documents that -makes it easy to quickly develop and debug QML applications. It invokes the QML -runtime to load QML documents and also includes additional features useful for +The Declarative UI package includes \QQV, a tool for loading QML documents that +makes it easy to quickly develop and debug QML applications. It invokes the QML +runtime to load QML documents and also includes additional features useful for the development of QML-based applications. -The QML Viewer is a tool for testing and developing QML applications. It is -\e not intended for use in a production environment and should not be used for the +The QML Viewer is a tool for testing and developing QML applications. It is +\e not intended for use in a production environment and should not be used for the deployment of QML applications. In those cases, the QML runtime should be invoked from a Qt application instead; see \l {Qt Declarative UI Runtime} for more information. The viewer is located at \c QTDIR/bin/qmlviewer. To load a \c .qml file -with the viewer, run the viewer and select the file to be opened, or provide the +with the viewer, run the viewer and select the file to be opened, or provide the file path on the command line: \code qmlviewer myqmlfile.qml \endcode - + On Mac OS X, the QML Viewer application is named "QMLViewer" instead. You -can launch the viewer by opening the QMLViewer application from the Finder, or +can launch the viewer by opening the QMLViewer application from the Finder, or from the command line: \code QMLViewer.app/Contents/MacOS/QMLViewer myqmlfile.qml \endcode -The QML Viewer has a number of configuration options involving features such as +The QML Viewer has a number of configuration options involving features such as fullscreen display, module import path configurations, video recording of QML animations, and OpenGL support. @@ -68,7 +68,7 @@ To see the configuration options, run \c qmlviewer with the \c -help argument. \section1 Adding module import paths Additional module import paths can be provided using the \c -I flag. -For example, the \l{declarative/cppextensions/plugins}{QML plugins example} creates +For example, the \l{declarative/cppextensions/plugins}{QML plugins example} creates a C++ plugin identified as \c com.nokia.TimeExample. Since this has a namespaced identifier, the viewer has to be run with the \c -I flag from the example's base directory: @@ -87,16 +87,16 @@ the path is explicitly added. \section1 Loading translation files -When the QML Viewer loads a QML file, it installs a translation file from a -"i18n" subdirectory relative to that initial file. This directory should contain +When the QML Viewer loads a QML file, it installs a translation file from a +"i18n" subdirectory relative to that initial file. This directory should contain translation files named "qml_<language>.qm", where <language> is a two-letter ISO 639 language, such as "qml_fr.qm", optionally followed by an underscore and an uppercase two-letter ISO 3166 country code, such as "qml_fr_FR.qm" or -"qml_fr_CA.qm". +"qml_fr_CA.qm". Such files can be created using \l {Qt Linguist}. -The actual translation file that is loaded depends on the system locale. +The actual translation file that is loaded depends on the system locale. Additionally, the viewer will load any translation files specified on the command line via the \c -translation option. @@ -110,7 +110,7 @@ shows how JavaScript code in QML files can be made to use translatable strings. Often, QML applications are prototyped with fake data that is later replaced by real data sources from C++ plugins. QML Viewer assists in this aspect by loading fake data into the application context: it looks for a directory named -"dummydata" in the same directory as the target QML file, and any \c .qml +"dummydata" in the same directory as the target QML file, and any \c .qml files in that directory are loaded as QML objects and bound to the root context as properties named after the files. @@ -124,7 +124,7 @@ ListView { width: 200; height: 300 model: lottoNumbers delegate: Text { text: number } -} +} \endqml If within the document's directory, there is a "dummydata" directory which @@ -146,30 +146,30 @@ Child properties are included when loaded from dummy data. The following documen refers to a \c clock.time property: \qml -import QtQuick 1.0 +import QtQuick 1.0 Text { text: clock.time } \endqml - + The text value could be filled by a \c dummydata/clock.qml file with a \c time property in the root context: \qml -import QtQuick 1.0 +import QtQuick 1.0 QtObject { property int time: 54321 } \endqml To replace this with real data, you can simply bind the real data object to the root context in C++ using QDeclarativeContext::setContextProperty(). This -is detailed in \l {Using QML in C++ Applications}. +is detailed in \l {Using QML Bindings in C++ Applications}. \section1 Using the \c runtime object QML applications that are loaded with the QML Viewer have access to a special -\c runtime property on the root context. This property provides additional +\c runtime property on the root context. This property provides additional information about the application's runtime environment through the following properties: \table -\row +\row \o \c runtime.isActiveWindow @@ -177,9 +177,9 @@ information about the application's runtime environment through the following pr window on the system. It is useful for "pausing" an application, particularly animations, when the QML Viewer loses focus or moves to the background. -For example, the following animation is only played when the QML Viewer is +For example, the following animation is only played when the QML Viewer is the active window: - + \qml Rectangle { width: 200; height: 200 @@ -200,9 +200,9 @@ through the \c active property of the \l {QML:Qt::application}{Qt.application} o \o \c runtime.orientation \o This property indicates the current orientation of the QML Viewer. On the -N900 platform and most S60 5.0-based or newer Symbian devices, this property -automatically updates to reflect the device's actual orientation; on other platforms, -this indicates the orientation currently selected in the QML Viewer's +N900 platform and most S60 5.0-based or newer Symbian devices, this property +automatically updates to reflect the device's actual orientation; on other platforms, +this indicates the orientation currently selected in the QML Viewer's \e {Settings -> Properties} menu. The \c orientation value can be one of the following: \list @@ -213,7 +213,7 @@ this indicates the orientation currently selected in the QML Viewer's \endlist When the viewer's orientation changes, the appearance of the loaded QML document -does not change unless it has been set to respond to changes in +does not change unless it has been set to respond to changes in \c runtime.orientation. For example, the following Rectangle changes its aspect ratio depending on the orientation of the QML Viewer: @@ -221,12 +221,12 @@ aspect ratio depending on the orientation of the QML Viewer: Rectangle { id: window width: 640; height: 480 - + states: State { name: "landscape" PropertyChanges { target: window; width: 480; height: 640 } } - state: (runtime.orientation == Orientation.Landscape + state: (runtime.orientation == Orientation.Landscape || runtime.orientation == Orientation.LandscapeInverted) ? 'landscape' : '' } \endqml diff --git a/doc/src/declarative/qmlviews.qdoc b/doc/src/declarative/qmlviews.qdoc new file mode 100644 index 0000000..53ce4b9 --- /dev/null +++ b/doc/src/declarative/qmlviews.qdoc @@ -0,0 +1,114 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qml-views.html +\ingroup qml-features +\contentspage QML Features +\previouspage {QML Data Models}{Structuring Data with Models} +\nextpage {Extending QML Functionalities using C++} +\title Presenting Data with Views + +Views are containers for collections of items. They are feature-rich and can be +customizable to meet style or behavior requirements. + +\keyword qml-view-elements +A set of standard views are provided in the basic set of Qt Quick +graphical elements: + +\list +\o \l{ListView} arranges items in a horizontal or vertical list +\o \l{GridView} arranges items in a grid within the available space +\o \l{PathView} arranges items on a path +\o \l{WebView}{WebView} - available from the \l {QtWebKit QML Module}. +\endlist +Unlike other views, \l WebView is not a fully-featured view item, and needs +to be combined with a \l Flickable item to create a view that performs like +a Web browser. + +These elements have properties and behaviors exclusive to each element. Visit +their respective documentation for more information. + +\section1 Models + +Views display \l{qml-data-models}{models} onto the screen. A model could be a simple list of \l{QML Data Models#An Integer}{integer} or a \l{qml-c++-models}{C++ model}. + +To assign a model to a view, bind the view's \c model property to a model. +\snippet doc/src/snippets/declarative/listview.qml model +\snippet doc/src/snippets/declarative/listview.qml model + +For more information, consult the \l {QML Data Models} article. + +\keyword qml-view-delegate +\section1 View Delegates + +Views need a \e delegate to visually represent an item in a list. A view will +visualize each item list according to the template defined by the delegate. +Items in a model are accessible through the \c index property as well as the +item's properties. +\snippet doc/src/snippets/declarative/listview.qml delegate +\image listview-setup.png + +\section1 Decorating Views + +Views allow visual customization through \e decoration properties such as the \c header, \c footer, and \c section properties. By binding an object, usually +another visual object, to these properties, the views are decoratable. A footer +may include a \l Rectangle element showcasing borders or a header that displays +a logo on top of the list. + +Suppose that a specific club wants to decorate its members list with its brand +colors. A member list is in a \c model and the \c delegate will display the +model's content. +\snippet doc/src/snippets/declarative/listview-decorations.qml model +\snippet doc/src/snippets/declarative/listview-decorations.qml delegate + +The club may decorate the members list by binding visual objects to the +\c header and \c footer properties. The visual object may be defined inline, in another file, or in a +\l {Component} element. +\snippet doc/src/snippets/declarative/listview-decorations.qml decorations +\image listview-decorations.png + +\section1 ListView Sections + +\l {ListView} contents may be grouped into \e sections, where related list items +are labeled according to their sections. Further, the sections may be decorated +with \l{qml-view-delegate}{delegates}. + +A list may contain a list indicating people's names and the team on which team +the person belongs. +\snippet doc/src/snippets/declarative/listview-sections.qml model +\snippet doc/src/snippets/declarative/listview-sections.qml delegate + +The ListView element has the \c section +\l{Property Binding#Attached Properties}{attached property} that can combine +adjacent and related elements into a section. The section's \c property +property is for selecting which list element property to use as sections. +The \c criteria can dictate how the section names are displayed and the +\c delegate is similar to the views' \l {qml-view-delegate}{delegate} property. +\snippet doc/src/snippets/declarative/listview-sections.qml section +\image listview-section.png +*/ diff --git a/doc/src/declarative/qmlwebkit.qdoc b/doc/src/declarative/qmlwebkit.qdoc new file mode 100644 index 0000000..840f24d --- /dev/null +++ b/doc/src/declarative/qmlwebkit.qdoc @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qmlwebkit.html + +\title QtWebKit QML Module + +Qt WebKit QML + +\section1 WebKit QML Elements +\list +\o \l WebView +\endlist + +\section1 QtWebKit Module +The QtWebKit Module has a QML element, \l{WebView} for displaying web content +from a \c URL. + +Import the QtWebKit module before declaring a \c WebView element: +\snippet doc/src/snippets/declarative/webview/webview.qml import + +\section1 Simple Usage +\snippet doc/src/snippets/declarative/webview/webview.qml document +\image webview.png + +\sa {Models and Views: WebView Example}{WebView Example}, {QML Web Browser} +*/ diff --git a/doc/src/declarative/qtbinding.qdoc b/doc/src/declarative/qtbinding.qdoc index 03290aa..d11825e 100644 --- a/doc/src/declarative/qtbinding.qdoc +++ b/doc/src/declarative/qtbinding.qdoc @@ -27,10 +27,13 @@ /*! \page qtbinding.html -\target qtbinding -\title Using QML in C++ Applications +\ingroup qml-features +\previouspage {Extending QML Functionalities using C++} +\nextpage {Integrating QML Code with Existing Qt UI Code} +\contentspage QML Features +\title Using QML Bindings in C++ Applications -QML is designed to be easily extensible from C++. The classes in the +QML is designed to be easily extensible to and from C++. The classes in the Qt Declarative module allow QML components to be loaded and manipulated from C++, and through Qt's \l{The Meta-Object System}{meta-object system}, QML and C++ objects can easily communicate through Qt signals and slots. In addition, QML plugins can be written to create @@ -85,7 +88,7 @@ delete rectangleInstance; QML documents can also be loaded using QDeclarativeView. This class provides a convenient QWidget-based view for embedding QML components into QGraphicsView-based applications. (For other -methods of integrating QML into QWidget-based applications, see \l {Integrating QML with existing Qt +methods of integrating QML into QWidget-based applications, see \l {Integrating QML Code with existing Qt UI code}.) @@ -262,8 +265,8 @@ Note that custom C++ types do not have to inherit from QDeclarativeItem; this is a displayable item. If the item is not displayable, it can simply inherit from QObject. For more information on defining new QML elements, see the \l {Tutorial: Writing QML extensions with C++} -{Writing QML extensions with C++} tutorial and the \l {Extending QML in C++} reference -documentation. +{Writing QML extensions with C++} tutorial and the +\l {Extending QML Functionalities using C++} reference documentation. @@ -496,7 +499,8 @@ can be registered using qmlRegisterUncreatableType(). To be accessible from QML must begin with a capital letter. See the \l {Tutorial: Writing QML extensions with C++}{Writing QML extensions with C++} tutorial and -the \l {Extending QML in C++} reference documentation for more information. +the \l {Extending QML Functionalities using C++} reference documentation for +more information. \section2 Automatic type conversion from strings diff --git a/doc/src/declarative/qtprogrammers.qdoc b/doc/src/declarative/qtprogrammers.qdoc index b7d09a1..e48dc9a 100644 --- a/doc/src/declarative/qtprogrammers.qdoc +++ b/doc/src/declarative/qtprogrammers.qdoc @@ -30,8 +30,6 @@ \target qtprogrammers \title QML for Qt Programmers -\section1 Overview - While QML does not require Qt knowledge to use, if you \e are already familiar with Qt, much of your knowledge is directly relevant to learning and using QML. Of course, an application with a UI defined in QML also uses Qt for all the non-UI logic. @@ -48,7 +46,8 @@ QML provides direct access to the following concepts from Qt: \o Qt models - used directly in data binding (QAbstractItemModel) \endlist -Qt knowledge is \e required for \l {Extending QML in C++}, and also for \l{Integrating QML with existing Qt UI code}. +Qt knowledge is \e required for \l {Extending QML Functionalities using C++}, +and also for \l{Integrating QML Code with existing Qt UI code}. \section1 QML Items compared with QWidgets diff --git a/doc/src/declarative/qtquick-intro.qdoc b/doc/src/declarative/qtquick-intro.qdoc new file mode 100644 index 0000000..75236e6 --- /dev/null +++ b/doc/src/declarative/qtquick-intro.qdoc @@ -0,0 +1,124 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qml-intro.html +\title Intro to Qt Quick + +Qt Quick is a collection of technologies that are designed to help developers +create the kind of intuitive, modern, and fluid user interfaces that are +increasingly used on mobile phones, media players, set-top boxes, and other +portable devices. Qt Quick consists of a rich set of user interface +\l{QML Elements}{elements}, a \l{QML Syntax}{declarative} language for +describing user interfaces, and a language \l{QtDeclarative Module}{runtime}. A +collection of C++ APIs is used to integrate these high level features with +classic Qt applications. Version 2.1 of the Qt Creator integrated development +environment (IDE) introduces tools for developing Qt Quick applications. + +\image qml-clocks-example.png + +\section1 The QML Language + +QML is a high level, scripted language. Its commands, more correctly +\e elements, leverage the power and efficiency of the Qt libraries to make easy +to use commands that perform intuitive functions. Drawing a rectangle, +displaying an image, and application events -- all are possible with declarative +programming. + +The language also allows more flexibility of these commands by using +\l{About JavaScript}{JavaScript} to implement the high level user interface +logic. + +A QML element usually has various \e properties that help define the element. +For example, if we created an element called Circle then the radius of the +circle would be a property. Building user interfaces by importing these elements +is one of the great feature of QML and Qt Quick. +\image qml-texteditor5_newfile.png + +\section1 QtDeclarative Module + +To make Qt Quick possible, Qt introduces the \l {QtDeclarative} module. The +module creates a JavaScript runtime that QML runs under with a Qt based backend. +Because QtDeclarative and QML are built upon Qt, they inherit many of Qt's +technology, namely the \l{Signals and Slots}{signals and slots} mechanism and +the \l{The Meta-Object System}{meta-object} system. Data created using C++ are +directly accessible from QML and QML objects are also accessible from C++ code. + +In conjunction with the QML language, the QtDeclarative module separates the +interface logic in QML from the application logic in C++. + +\section1 Creator Tools + +Qt Creator is a complete integrated development environment (IDE) for creating +applications with Qt Quick and the Qt application framework. + +\image qmldesigner-visual-editor.png + +The main goal for Qt Creator is meeting the development needs of Qt Quick +developers who are looking for simplicity, usability, productivity, +extendibility and openness, while aiming to lower the barrier of entry for +newcomers to Qt Quick and Qt. The key features of Qt Creator allow UI designers +and developers to accomplish the following tasks: +\list +\o Get started with Qt Quick application development quickly and easily with +examples, tutorials, and project wizards. +\o Design application user interface with the integrated editor, Qt Quick +Designer, or use graphics software to design the user interface and use scripts +to export the design to Qt Quick Designer. +\o Develop applications with the advanced code editor that provides new powerful +features for completing code snippets, refactoring code, and viewing the element +hierarchy of QML files. +\o Build and deploy Qt Quick applications that target multiple desktop and +mobile platforms, such as Microsoft Windows, Mac OS X, Linux, Symbian, and +Maemo. +\o Debug JavaScript functions and execute JavaScript expressions in the current +context, and inspect QML at runtime to explore the object structure, debug +animations, and inspect colors. +\o Deploy applications to mobile devices and create application installation +packages for Symbian and Maemo devices that can be published in the Ovi Store +and other channels. +\o Easily access information with the integrated context-sensitive Qt Help +system. +\endlist + +\image qtcreator-target-selector.png + +\section1 Where to Go from Here + +The \l {Qt Quick} page has links to various Qt Quick topics such as QML +features, addons, and tools. + +The \l {QML Examples and Demos} page has a gallery of QML applications. + +\section1 License Information +\list +\o \l{Qt Quick Licensing Information} +\endlist +*/ + + + diff --git a/doc/src/declarative/scope.qdoc b/doc/src/declarative/scope.qdoc index 3317037..9a9934a 100644 --- a/doc/src/declarative/scope.qdoc +++ b/doc/src/declarative/scope.qdoc @@ -24,41 +24,17 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - -/* - - - -and requires extension to -fit naturally with QML. - - -JavaScript has only b -JavaScript has a very simple built in scope is very simple - -script, and the precede d - -and \l {Integrating JavaScript}{JavaScript} are executed in a scope chain -automatically established by QML when a component instance is constructed. QML is a \e {dynamically scoped} -language. Different object instances instantiated from the same component can exist in -different scope chains. - -\image qml-scope.png - - -*/ - /*! \page qdeclarativescope.html \title QML Scope \tableofcontents -QML property bindings, inline functions and imported JavaScript files all -run in a JavaScript scope. Scope controls which variables an expression can +QML property bindings, inline functions and imported JavaScript files all +run in a JavaScript scope. Scope controls which variables an expression can access, and which variable takes precedence when two or more names conflict. -As JavaScript's built-in scope mechanism is very simple, QML enhances it to fit +As JavaScript's built-in scope mechanism is very simple, QML enhances it to fit more naturally with the QML language extensions. \section1 JavaScript Scope @@ -67,8 +43,8 @@ QML's scope extensions do not interfere with JavaScript's natural scoping. JavaScript programmers can reuse their existing knowledge when programming functions, property bindings or imported JavaScript files in QML. -In the following example, the \c {addConstant()} method will add 13 to the -parameter passed just as the programmer would expect irrespective of the +In the following example, the \c {addConstant()} method will add 13 to the +parameter passed just as the programmer would expect irrespective of the value of the QML object's \c a and \c b properties. \code @@ -83,8 +59,8 @@ QtObject { } \endcode -That QML respects JavaScript's normal scoping rules even applies in bindings. -This totally evil, abomination of a binding will assign 12 to the QML object's +That QML respects JavaScript's normal scoping rules even applies in bindings. +This totally evil, abomination of a binding will assign 12 to the QML object's \c a property. \code @@ -101,13 +77,13 @@ with local variables declared in another. \section1 Element Names and Imported JavaScript Files -\l {QML Document}s include import statements that define the element names -and JavaScript files visible to the document. In addition to their use in the -QML declaration itself, element names are used by JavaScript code when accessing -\l {Attached Properties} and enumeration values. +\l {QML Document}s include import statements that define the element names +and JavaScript files visible to the document. In addition to their use in the +QML declaration itself, element names are used by JavaScript code when accessing +\l {Attached Properties} and enumeration values. -The effect of an import applies to every property binding, and JavaScript -function in the QML document, even those in nested inline components. The +The effect of an import applies to every property binding, and JavaScript +function in the QML document, even those in nested inline components. The following example shows a simple QML file that accesses some enumeration values and calls an imported JavaScript function. @@ -130,10 +106,10 @@ ListView { \section1 Binding Scope Object -Property bindings are the most common use of JavaScript in QML. Property +Property bindings are the most common use of JavaScript in QML. Property bindings associate the result of a JavaScript expression with a property of an -object. The object to which the bound property belongs is known as the binding's -scope object. In this QML simple declaration the \l Item object is the +object. The object to which the bound property belongs is known as the binding's +scope object. In this QML simple declaration the \l Item object is the binding's scope object. \code @@ -144,21 +120,21 @@ Item { Bindings have access to the scope object's properties without qualification. In the previous example, the binding accesses the \l Item's \c parent property -directly, without needing any form of object prefix. QML introduces a more -structured, object-oriented approach to JavaScript, and consequently does not +directly, without needing any form of object prefix. QML introduces a more +structured, object-oriented approach to JavaScript, and consequently does not require the use of the JavaScript \c this property. Care must be used when accessing \l {Attached Properties} from bindings due to their interaction with the scope object. Conceptually attached properties exist on \e all objects, even if they only have an effect on a subset of those. -Consequently unqualified attached property reads will always resolve to an -attached property on the scope object, which is not always what the programmer +Consequently unqualified attached property reads will always resolve to an +attached property on the scope object, which is not always what the programmer intended. -For example, the \l PathView element attaches interpolated value properties to +For example, the \l PathView element attaches interpolated value properties to its delegates depending on their position in the path. As PathView only -meaningfully attaches these properties to the root element in the delegate, any -sub-element that accesses them must explicitly qualify the root object, as shown +meaningfully attaches these properties to the root element in the delegate, any +sub-element that accesses them must explicitly qualify the root object, as shown below. \code @@ -181,7 +157,7 @@ the unset \c {PathView.scale} attached property on itself. Each QML component in a QML document defines a logical scope. Each document has at least one root component, but can also have other inline sub-components. -The component scope is the union of the object ids within the component and the +The component scope is the union of the object ids within the component and the component's root element's properties. \code @@ -195,7 +171,7 @@ Item { anchors.top: parent.top } - Text { + Text { text: titleElement.text font.pixelSize: 18 anchors.bottom: parent.bottom @@ -203,7 +179,7 @@ Item { } \endcode -The example above shows a simple QML component that displays a rich text title +The example above shows a simple QML component that displays a rich text title string at the top, and a smaller copy of the same text at the bottom. The first \c Text element directly accesses the component's \c title property when forming the text to display. That the root element's properties are directly @@ -211,18 +187,18 @@ accessible makes it trivial to distribute data throughout the component. The second \c Text element uses an id to access the first's text directly. IDs are specified explicitly by the QML programmer so they always take precedence -over other property names (except for those in the \l {JavaScript Scope}). For -example, in the unlikely event that the binding's \l {Binding Scope Object}{scope -object} had a \c titleElement property in the previous example, the \c titleElement +over other property names (except for those in the \l {JavaScript Scope}). For +example, in the unlikely event that the binding's \l {Binding Scope Object}{scope +object} had a \c titleElement property in the previous example, the \c titleElement id would still take precedence. \section1 Component Instance Hierarchy -In QML, component instances connect their component scopes together to form a -scope hierarchy. Component instances can directly access the component scopes of +In QML, component instances connect their component scopes together to form a +scope hierarchy. Component instances can directly access the component scopes of their ancestors. -The easiest way to demonstrate this is with inline sub-components whose component +The easiest way to demonstrate this is with inline sub-components whose component scopes are implicitly scoped as children of the outer component. \code @@ -239,16 +215,16 @@ Item { } \endcode -The component instance hierarchy allows instances of the delegate component +The component instance hierarchy allows instances of the delegate component to access the \c defaultColor property of the \c Item element. Of course, -had the delegate component had a property called \c defaultColor that would -have taken precedence. +had the delegate component had a property called \c defaultColor that would +have taken precedence. The component instance scope hierarchy extends to out-of-line components, too. -In the following example, the \c TitlePage.qml component creates two -\c TitleText instances. Even though the \c TitleText element is in a separate -file, it still has access to the \c title property when it is used from within -the \c TitlePage. QML is a dynamically scoped language - depending on where it +In the following example, the \c TitlePage.qml component creates two +\c TitleText instances. Even though the \c TitleText element is in a separate +file, it still has access to the \c title property when it is used from within +the \c TitlePage. QML is a dynamically scoped language - depending on where it is used, the \c title property may resolve differently. \code @@ -256,13 +232,13 @@ is used, the \c title property may resolve differently. import QtQuick 1.0 Item { property string title - - TitleText { + + TitleText { size: 22 anchors.top: parent.top } - TitleText { + TitleText { size: 18 anchors.bottom: parent.bottom } @@ -277,10 +253,10 @@ Text { } \endcode -Dynamic scoping is very powerful, but it must be used cautiously to prevent +Dynamic scoping is very powerful, but it must be used cautiously to prevent the behavior of QML code from becoming difficult to predict. In general it -should only be used in cases where the two components are already tightly -coupled in another way. When building reusable components, it is preferable +should only be used in cases where the two components are already tightly +coupled in another way. When building reusable components, it is preferable to use property interfaces, like this: \code @@ -289,14 +265,14 @@ import QtQuick 1.0 Item { id: root property string title - - TitleText { + + TitleText { title: root.title size: 22 anchors.top: parent.top } - TitleText { + TitleText { title: root.title size: 18 anchors.bottom: parent.bottom @@ -322,7 +298,7 @@ QML specific tasks a little easier. These extensions are described in the \l {QML Global Object} documentation. QML disallows element, id and property names that conflict with the properties -on the global object to prevent any confusion. Programmers can be confident +on the global object to prevent any confusion. Programmers can be confident that \c Math.min(10, 9) will always work as expected! */ diff --git a/doc/src/declarative/tutorial.qdoc b/doc/src/declarative/tutorial.qdoc index 1ee5e61..dc08ba0 100644 --- a/doc/src/declarative/tutorial.qdoc +++ b/doc/src/declarative/tutorial.qdoc @@ -144,7 +144,7 @@ An \l Item is the most basic visual element in QML and is often used as a contai We declare a \c cellColor property. This property is accessible from \e outside our component, this allows us to instantiate the cells with different colors. -This property is just an alias to an existing property - the color of the rectangle that compose the cell (see \l{Adding Properties}). +This property is just an alias to an existing property - the color of the rectangle that compose the cell (see \l{Property Binding}). \snippet examples/declarative/tutorials/helloworld/Cell.qml 5 diff --git a/doc/src/deployment/deployment-plugins.qdoc b/doc/src/deployment/deployment-plugins.qdoc index 12a3b0c..03685e5 100644 --- a/doc/src/deployment/deployment-plugins.qdoc +++ b/doc/src/deployment/deployment-plugins.qdoc @@ -104,7 +104,7 @@ plugins to be built in release mode, add the following line to the plugin's project file: - \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 3 + \snippet doc/src/snippets/code/doc_src_plugins-howto.pro 3 This will ensure that the plugin is compatible with the version of the library used in the application. diff --git a/doc/src/deployment/deployment.qdoc b/doc/src/deployment/deployment.qdoc index bc80ed3..50f873f 100644 --- a/doc/src/deployment/deployment.qdoc +++ b/doc/src/deployment/deployment.qdoc @@ -336,7 +336,7 @@ are many ways to solve this: \list - + \o You can install the Qt libraries in one of the system library paths (e.g. \c /usr/lib on most systems). @@ -345,7 +345,7 @@ linker to look in this directory when starting your application. \o You can write a startup script for your application, where you - modify the dynamic linker configuration (e.g. adding your + modify the dynamic linker configuration (e.g., adding your application's directory to the \c LD_LIBRARY_PATH environment variable. \note If your application will be running with "Set user ID on execution," and if it will be owned by root, then @@ -375,7 +375,7 @@ \c plugins directory, or you can set the \c DESTDIR in the plugins' project files: - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 8 + \snippet doc/src/snippets/code/doc_src_deployment.pro 8 An archive distributing all the Qt libraries, and all the plugins, required to run the \l {tools/plugandpaint}{Plug & Paint} @@ -422,7 +422,7 @@ application using QApplication::addLibraryPath() or QApplication::setLibraryPaths(). - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 9 + \snippet doc/src/snippets/code/doc_src_deployment.cpp 9 \section1 Application Dependencies @@ -718,7 +718,7 @@ using QApplication::addLibraryPath() or QApplication::setLibraryPaths(). - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 19 + \snippet doc/src/snippets/code/doc_src_deployment.cpp 19 One benefit of using plugins is that they can easily be made available to a whole family of applications. @@ -753,7 +753,7 @@ To use the options, add - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 21 + \snippet doc/src/snippets/code/doc_src_deployment.pro 21 to your .pro file. The \c embed_manifest_dll option is enabled by default. The \c embed_manifest_exe option is NOT enabled by default. @@ -965,7 +965,7 @@ command line application on Unix and Windows. You probably don't want to run it in a bundle: Add this to your application's .pro: - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 26 + \snippet doc/src/snippets/code/doc_src_deployment.pro 26 This will tell \c qmake not to put the executable inside a bundle. Please refer to the \l{Deploying an Application on @@ -1249,7 +1249,7 @@ to look for the new plugins. After constructing the QApplication, we add the following code: - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 49 + \snippet doc/src/snippets/code/doc_src_deployment.cpp 49 First, we tell the application to only look for plugins in this directory. In our case, this is what we want since we only want to @@ -1366,7 +1366,7 @@ variable to get \e{weak linking} to work for your application. You can add: - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 51 + \snippet doc/src/snippets/code/doc_src_deployment.pro 51 to your .pro file, and qmake will take care of this for you. @@ -1416,7 +1416,7 @@ add both to the \c CONFIG line. PowerPC users also need an SDK. For example: - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 53 + \snippet doc/src/snippets/code/doc_src_deployment.pro 53 Besides \c lipo, you can also check your binaries with the \c file(1) command line tool or the Finder. @@ -1513,12 +1513,12 @@ First, we will change the vendor statement to something more meaningful. The application vendor is visible to end-user during the installation. - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 56 + \snippet doc/src/snippets/code/doc_src_deployment.pro 56 Second we will tell the Symbian application installer that this application supports only S60 5.0 based devices: - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 57 + \snippet doc/src/snippets/code/doc_src_deployment.pro 57 You can find a list of platform and device indentification codes from \l {http://wiki.forum.nokia.com/index.php/S60_Platform_and_device_identification_codes}{Forum Nokia Wiki}. diff --git a/doc/src/development/activeqt-dumpcpp.qdoc b/doc/src/development/activeqt-dumpcpp.qdoc index 504b3b4..54581e1 100644 --- a/doc/src/development/activeqt-dumpcpp.qdoc +++ b/doc/src/development/activeqt-dumpcpp.qdoc @@ -83,24 +83,24 @@ as \c noncreatable) have a default constructor; this is typically a single class of type \c Application. - \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 0 + \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.cpp 0 All other classes can only be created by passing an IDispatch interface pointer to the constructor; those classes should however not be created explicitly. Instead, use the appropriate API of already created objects. - \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 1 + \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.cpp 1 All coclass wrappers also have one constructors taking an interface wrapper class for each interface implemented. - \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 2 + \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.cpp 2 You have to create coclasses to be able to connect to signals of the subobject. Note that the constructor deletes the interface object, so the following will cause a segmentation fault: - \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 3 + \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.cpp 3 If the return type is of a coclass or interface type declared in another type library you have to include the namespace header for that other type library @@ -115,7 +115,7 @@ In this case, create the correct wrapper class explicitly: - \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 4 + \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.cpp 4 You can of course use the IDispatch* returned directly, in which case you have to call \c Release() when finished with the interface. diff --git a/doc/src/development/debug.qdoc b/doc/src/development/debug.qdoc index 044ad0d..1669b00 100644 --- a/doc/src/development/debug.qdoc +++ b/doc/src/development/debug.qdoc @@ -142,7 +142,7 @@ If you include the <QtDebug> header file, the \c qDebug() function can also be used as an output stream. For example: - \snippet doc/src/snippets/code/doc_src_debug.qdoc 0 + \snippet doc/src/snippets/code/doc_src_debug.cpp 0 The Qt implementation of these functions prints the text to the \c stderr output under Unix/X11 and Mac OS X. With Windows, if it @@ -199,14 +199,14 @@ These macros are useful for detecting program errors, e.g. like this: - \snippet doc/src/snippets/code/doc_src_debug.qdoc 1 + \snippet doc/src/snippets/code/doc_src_debug.cpp 1 Q_ASSERT(), Q_ASSERT_X(), and Q_CHECK_PTR() expand to nothing if \c QT_NO_DEBUG is defined during compilation. For this reason, the arguments to these macro should not have any side-effects. Here is an incorrect usage of Q_CHECK_PTR(): - \snippet doc/src/snippets/code/doc_src_debug.qdoc 2 + \snippet doc/src/snippets/code/doc_src_debug.cpp 2 If this code is compiled with \c QT_NO_DEBUG defined, the code in the Q_CHECK_PTR() expression is not executed and \e alloc returns diff --git a/doc/src/development/designer-manual.qdoc b/doc/src/development/designer-manual.qdoc index 9a6220f..0f38c61 100644 --- a/doc/src/development/designer-manual.qdoc +++ b/doc/src/development/designer-manual.qdoc @@ -1385,17 +1385,13 @@ \target CreatingAMenu - \raw HTML - <div style="float: left; margin-right: 2em"> - \endraw + \div {class="float-left"} \inlineimage designer-creating-menu1.png \inlineimage designer-creating-menu2.png \br \inlineimage designer-creating-menu3.png \inlineimage designer-creating-menu4.png - \raw HTML - </div> - \endraw + \enddiv \section2 Creating a Menu @@ -1410,9 +1406,8 @@ \key Escape to reject it. You can undo the editing operation later if required. - \raw HTML - <div style="clear: both" /> - \endraw + \div {class="clear-both"} + \enddiv Menus can also be rearranged in the menu bar simply by dragging and dropping them in the preferred location. A vertical red line indicates the @@ -1423,17 +1418,13 @@ navigating the menu structure in the usual way. \target CreatingAMenuEntry - \raw HTML - <div style="float: right; margin-left: 2em"> - \endraw + \div {class="float-right"} \inlineimage designer-creating-menu-entry1.png \inlineimage designer-creating-menu-entry2.png \br \inlineimage designer-creating-menu-entry3.png \inlineimage designer-creating-menu-entry4.png - \raw HTML - </div> - \endraw + \enddiv \section2 Creating a Menu Entry @@ -1453,9 +1444,8 @@ be accessible via the \l{#TheActionEditor}{Action Editor}, and any associated keyboard shortcut can be set there. - \raw HTML - <div style="clear: both" /> - \endraw + \div {class="clear-both"} + \enddiv Just like with menus, entries can be moved around simply by dragging and dropping them in the preferred location. When an entry is dragged over a @@ -1465,13 +1455,9 @@ \section1 Toolbars - \raw HTML - <div style="float: left; margin-right: 2em"> - \endraw + \div {class="float-left"} \inlineimage designer-creating-toolbar.png - \raw HTML - </div> - \endraw + \enddiv \section2 Creating and Removing a Toolbar @@ -1483,9 +1469,8 @@ Toolbars are removed from the form via an entry in the toolbar's context menu. - \raw HTML - <div style="clear: both" /> - \endraw + \div {class="clear-both"} + \enddiv \section2 Adding and Removing Toolbar Buttons @@ -1494,14 +1479,10 @@ Since actions can be represented by menu entries and toolbar buttons, they can be moved between menus and toolbars. - \raw HTML - <div style="float: right; margin-left: 2em"> - \endraw + \div {class="float-right"} \inlineimage designer-adding-toolbar-action.png \inlineimage designer-removing-toolbar-action.png - \raw HTML - </div> - \endraw + \enddiv To share an action between a menu and a toolbar, drag its icon from the action editor to the toolbar rather than from the menu where its entry is @@ -1510,9 +1491,8 @@ Toolbar buttons are removed via the toolbar's context menu. - \raw HTML - <div style="clear: both" /> - \endraw + \div {class="clear-both"} + \enddiv \section1 Actions @@ -1521,13 +1501,9 @@ action editor window, simplifying the creation and management of actions. \target TheActionEditor - \raw HTML - <div style="float: left; margin-right: 2em"> - \endraw + \div {class="float-left"} \inlineimage designer-action-editor.png - \raw HTML - </div> - \endraw + \enddiv \section2 The Action Editor @@ -1543,9 +1519,8 @@ \gui{Detailed View}. You can also copy and paste actions between menus, toolbars and forms. - \raw HTML - <div style="clear: both" /> - \endraw + \div {class="clear-both"} + \enddiv \section2 Creating an Action @@ -1560,19 +1535,14 @@ Once the action is created, it can be used wherever actions are applicable. - \raw HTML - <div style="clear: left" /> - \endraw + \div {class="clear-left"} + \enddiv \target AddingAnAction - \raw HTML - <div style="float: right; margin-left: 2em"> - \endraw + \div {class="float-right"} \inlineimage designer-adding-menu-action.png \inlineimage designer-adding-toolbar-action.png - \raw HTML - </div> - \endraw + \enddiv \section2 Adding an Action @@ -1584,9 +1554,8 @@ will be added. Release the mouse button to add the action when you have found the right spot. - \raw HTML - <div style="clear: right" /> - \endraw + \div {class="clear-right"} + \enddiv \section1 Dock Widgets @@ -1598,13 +1567,9 @@ \target AddingADockWidget - \raw HTML - <div style="float: left; margin-right: 2em"> - \endraw + \div {class="float-left"} \inlineimage designer-adding-dockwidget.png - \raw HTML - </div> - \endraw + \enddiv \section2 Adding a Dock Widget @@ -1623,9 +1588,8 @@ \l{QDockWidget::}{windowTitle} property. This also helps to identify them on the form. - \raw HTML - <div style="clear: both" /> - \endraw + \div {class="clear-both"} + \enddiv */ @@ -2044,7 +2008,7 @@ pixmap property in the property editor. project file, ensuring that the application is compiled and linked appropriately. - \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 0 + \snippet doc/src/snippets/code/doc_src_designer-manual.pro 0 The QUiLoader class provides a form loader object to construct the user interface. This user interface can be retrieved from any QIODevice, e.g., @@ -2054,7 +2018,7 @@ pixmap property in the property editor. The QtUiTools module classes can be included using the following directive: - \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 1 + \snippet doc/src/snippets/code/doc_src_designer-manual.cpp 1 The QUiLoader::load() function is invoked as shown in this code from the \l{Text Finder Example}{Text Finder} example: @@ -2126,7 +2090,7 @@ pixmap property in the property editor. \c setupUi() function to do this, so we only need to declare and implement a slot with a name that follows a standard convention: - \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 2 + \snippet doc/src/snippets/code/doc_src_designer-manual.cpp 2 Using this convention, we can define and implement a slot that responds to mouse clicks on the \gui OK button: @@ -2588,7 +2552,7 @@ pixmap property in the property editor. plugins are also built in release mode. To do this, include the following declaration in the plugin's \c{.pro} file: - \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 3 + \snippet doc/src/snippets/code/doc_src_designer-manual.pro 3 If plugins are built in a mode that is incompatible with \QD, they will not be loaded and installed. For more information about plugins, see the @@ -2597,7 +2561,7 @@ pixmap property in the property editor. It is also necessary to ensure that the plugin is installed together with other \QD widget plugins: - \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 4 + \snippet doc/src/snippets/code/doc_src_designer-manual.pro 4 The \c $[QT_INSTALL_PLUGINS] variable is a placeholder to the location of the installed Qt plugins. You can configure \QD to look for plugins in @@ -2756,7 +2720,7 @@ pixmap property in the property editor. using the Q_INTERFACES() macro in the extension class's definition. For example: - \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 7 + \snippet doc/src/snippets/code/doc_src_designer-manual.cpp 7 This enables \QD to use the qobject_cast() function to query for supported interfaces using a QObject pointer only. @@ -2791,13 +2755,13 @@ pixmap property in the property editor. You can either create a new QExtensionFactory and reimplement the QExtensionFactory::createExtension() function: - \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 8 + \snippet doc/src/snippets/code/doc_src_designer-manual.cpp 8 or you can use an existing factory, expanding the QExtensionFactory::createExtension() function to enable the factory to create your custom extension as well: - \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 9 + \snippet doc/src/snippets/code/doc_src_designer-manual.cpp 9 \section2 Accessing Qt Designer's Extension Manager @@ -2809,7 +2773,7 @@ pixmap property in the property editor. an extension factory is typically made in the QDesignerCustomWidgetInterface::initialize() function: - \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 10 + \snippet doc/src/snippets/code/doc_src_designer-manual.cpp 10 The \c formEditor parameter in the QDesignerCustomWidgetInterface::initialize() function is a pointer to \QD's diff --git a/doc/src/development/moc.qdoc b/doc/src/development/moc.qdoc index fc0165b..5d524b2 100644 --- a/doc/src/development/moc.qdoc +++ b/doc/src/development/moc.qdoc @@ -136,7 +136,7 @@ This guarantees that make will run the moc before it compiles \c foo.cpp. You can then put - \snippet doc/src/snippets/code/doc_src_moc.qdoc 3 + \snippet doc/src/snippets/code/doc_src_moc.cpp 3 at the end of \c foo.cpp, where all the classes declared in that file are fully known. @@ -223,7 +223,7 @@ file. \c moc defines the preprocessor symbol \c Q_MOC_RUN. Any code surrounded by - \snippet doc/src/snippets/code/doc_src_moc.qdoc 4 + \snippet doc/src/snippets/code/doc_src_moc.cpp 4 is skipped by the \c moc. @@ -245,7 +245,7 @@ \c moc does not handle all of C++. The main problem is that class templates cannot have signals or slots. Here is an example: - \snippet doc/src/snippets/code/doc_src_moc.qdoc 5 + \snippet doc/src/snippets/code/doc_src_moc.cpp 5 Another limitation is that moc does not expand macros, so you for example cannot use a macro to declare a signal/slot @@ -261,7 +261,7 @@ first inherited class is a subclass of QObject. Also, be sure that only the first inherited class is a QObject. - \snippet doc/src/snippets/code/doc_src_moc.qdoc 6 + \snippet doc/src/snippets/code/doc_src_moc.cpp 6 Virtual inheritance with QObject is \e not supported. @@ -271,11 +271,11 @@ signal or slot parameters, we think inheritance is a better alternative. Here is an example of illegal syntax: - \snippet doc/src/snippets/code/doc_src_moc.qdoc 7 + \snippet doc/src/snippets/code/doc_src_moc.cpp 7 You can work around this restriction like this: - \snippet doc/src/snippets/code/doc_src_moc.qdoc 8 + \snippet doc/src/snippets/code/doc_src_moc.cpp 8 It may sometimes be even better to replace the function pointer with inheritance and virtual functions. @@ -289,7 +289,7 @@ fully qualify the data types when declaring signals and slots, and when establishing connections. For example: - \snippet doc/src/snippets/code/doc_src_moc.qdoc 9 + \snippet doc/src/snippets/code/doc_src_moc.cpp 9 \section2 Type Macros Cannot Be Used for Signal and Slot Parameters @@ -297,7 +297,7 @@ an argument will not work in signals and slots. Here is an illegal example: - \snippet doc/src/snippets/code/doc_src_moc.qdoc 10 + \snippet doc/src/snippets/code/doc_src_moc.cpp 10 A macro without parameters will work. @@ -305,7 +305,7 @@ Here's an example of the offending construct: - \snippet doc/src/snippets/code/doc_src_moc.qdoc 11 + \snippet doc/src/snippets/code/doc_src_moc.cpp 11 \section2 Signal/Slot return types cannot be references diff --git a/doc/src/development/qmake-manual.qdoc b/doc/src/development/qmake-manual.qdoc index 1c5d903..2bc8a34 100644 --- a/doc/src/development/qmake-manual.qdoc +++ b/doc/src/development/qmake-manual.qdoc @@ -34,26 +34,26 @@ \ingroup qttools \keyword qmake - \l {qmake}{ \c qmake} is a tool that helps simplify the build - process for development project across different platforms. \l {qmake}{ \c qmake} + \l{qmake}{\c qmake} is a tool that helps simplify the build process for + development project across different platforms. \l{qmake}{\c qmake} automates the generation of Makefiles so that only a few lines of - information are needed to create each Makefile. \l {qmake}{ \c qmake} can be used for - any software project, whether it is written in Qt or not. - - \l {qmake}{ \c qmake} generates a Makefile based on the information in a project - file. Project files are created by the developer, and are usually - simple, but more sophisticated project files can be created for - complex projects. - \l {qmake}{ \c qmake} contains additional features to support development with Qt, - automatically including build rules for \l{moc.html}{moc} + information are needed to create each Makefile. \l{qmake}{\c qmake} can be + used for any software project, whether it is written in Qt or not. + + \l{qmake}{\c qmake} generates a Makefile based on the information in a + project file. Project files are created by the developer, and are usually + simple, but more sophisticated project files can be created for complex + projects. + \l{qmake}{\c qmake} contains additional features to support development + with Qt, automatically including build rules for \l{moc.html}{moc} and \l{uic.html}{uic}. - \l {qmake}{ \c qmake} can also generate projects for Microsoft Visual studio + \l{qmake}{\c qmake} can also generate projects for Microsoft Visual studio without requiring the developer to change the project file. \section1 Getting Started The \l{qmake Tutorial} and guide to \l{qmake Common Projects} provide overviews - that aim to help new users get started with \l {qmake}{ \c qmake}. + that aim to help new users get started with \l{qmake}{\c qmake}. \list \o \l{qmake Tutorial} @@ -98,23 +98,24 @@ \previouspage qmake Manual \nextpage qmake Project Files - \l {qmake}{ \c qmake} provides a project-oriented system for managing the build - process for applications, libraries, and other components. This - approach gives developers control over the source files used, and + \l{qmake Manual#qmake}{\c qmake} provides a project-oriented system for + managing the buildprocess for applications, libraries, and other components. + This approach gives developers control over the source files used, and allows each of the steps in the process to be described concisely, - typically within a single file. \l {qmake}{ \c qmake} expands the information in - each project file to a Makefile that executes the necessary commands - for compiling and linking. + typically within a single file. \l{qmake Manual#qmake}{\c qmake} expands + the information in each project file to a Makefile that executes the necessary + commands for compiling and linking. In this document, we provide a basic introduction to project files, - describe some of the main features of \l {qmake}{ \c qmake}, and show how to use - \l {qmake}{ \c qmake} on the command line. + describe some of the main features of \l{qmake Manual#qmake}{\c qmake}, + and show how to use \l{qmake Manual#qmake}{\c qmake} on the command line. \section1 Describing a Project Projects are described by the contents of project (\c .pro) files. - The information within these is used by \l {qmake}{ \c qmake} to generate a Makefile - containing all the commands that are needed to build each project. + The information within these is used by \l{qmake Manual#qmake}{\c qmake} + to generate a Makefile containing all the commands that are needed to + build each project. Project files typically contain a list of source and header files, general configuration information, and any application-specific details, such as a list of extra libraries to link against, or a list of extra @@ -134,13 +135,14 @@ \section1 Building a Project - For simple projects, you only need to run \l {qmake}{ \c qmake} in the top - level directory of your project. By default, \l {qmake}{ \c qmake} generates a - Makefile that you then use to build the project, and you can then - run your platform's \c make tool to build the project. + For simple projects, you only need to run \l{qmake Manual#qmake}{\c qmake} + in the top level directory of your project. By default, + \l{qmake Manual#qmake}{\c qmake} generates a Makefile that you then use + to build the project, and you can then run your platform's \c make tool + to build the project. - \l {qmake}{ \c qmake} can also be used to generate project files. A full - description of \c{qmake}'s command line options can be found in the + \l{qmake Manual#qmake}{\c qmake} can also be used to generate project files. + A full description of \c{qmake}'s command line options can be found in the \l{Running qmake} chapter of this manual. \section1 Using Precompiled Headers @@ -157,38 +159,40 @@ \previouspage Using qmake \nextpage Running qmake - Project files contain all the information required by \l {qmake}{ \c qmake} to build - your application, library, or plugin. The resources used by your project - are generally specified using a series of declarations, but support for - simple programming constructs allow you to describe different build - processes for different platforms and environments. + Project files contain all the information required by + \l{qmake Manual#qmake}{\c qmake} to build your application, library, + or plugin. The resources used by your project are generally specified + using a series of declarations, but support for simple programming + constructs allow you to describe different build processes for different + platforms and environments. \tableofcontents \section1 Project File Elements - The project file format used by \l {qmake}{ \c qmake} can be used to support both - simple and fairly complex build systems. Simple project files will - use a straightforward declarative style, defining standard variables - to indicate the source and header files that are used in the project. - Complex projects may use the control flow structures to fine-tune the - build process. + The project file format used by \l{qmake Manual#qmake}{\c qmake} can be + used to support both simple and fairly complex build systems. + Simple project files will use a straightforward declarative style, + defining standard variables to indicate the source and header files + that are used in the project. Complex projects may use the control flow + structures to fine-tune the build process. The following sections describe the different types of elements used in project files. \section2 Variables - In a project file, variables are used to hold lists of strings. - In the simplest projects, these variables inform \l {qmake}{ \c qmake} about the - configuration options to use, or supply filenames and paths to use - in the build process. + In a project file, variables are used to hold lists of strings. In the + simplest projects, these variables inform \l{qmake Manual#qmake}{\c qmake} + about the configuration options to use, or supply filenames and paths to + use in the build process. - \l {qmake}{ \c qmake} looks for certain variables in each project file, and it - uses the contents of these to determine what it should write to a - Makefile. For example, the list of values in the \c HEADERS and - \c SOURCES variables are used to tell \l {qmake}{ \c qmake} about header and - source files in the same directory as the project file. + \l{qmake Manual#qmake}{\c qmake} looks for certain variables in each + project file, and it uses the contents of these to determine what it + should write to a Makefile. For example, the list of values in the + \c HEADERS and \c SOURCES variables are used to tell + \l{qmake Manual#qmake}{\c qmake} about header and source files in the + same directory as the project file. Variables can also be used internally to store temporary lists of values, and existing lists of values can be overwritten or extended with new @@ -206,14 +210,15 @@ \snippet doc/src/snippets/qmake/variables.pro 1 - The \c CONFIG variable is another special variable that \l {qmake}{ \c qmake} - uses when generating a Makefile. It is discussed in the section on + The \c CONFIG variable is another special variable that + \l{qmake Manual#qmake}{\c qmake} uses when generating a Makefile. + It is discussed in the section on \l{#GeneralConfiguration}{general configuration} later in this chapter. In the above line, \c qt is added to the list of existing values contained in \c CONFIG. - The following table lists the variables that \l {qmake}{ \c qmake} recognizes, and - describes what they should contain. + The following table lists the variables that \l{qmake Manual#qmake}{\c qmake} + recognizes, and describes what they should contain. \table \header \o Variable \o Contents @@ -273,8 +278,9 @@ \section2 Built-in Functions and Control Flow - \l {qmake}{ \c qmake} provides a number of built-in functions to allow the contents - of variables to be processed. The most commonly used function in simple + \l{qmake Manual#qmake}{\c qmake} provides a number of built-in functions + to allow the contents of variables to be processed. + The most commonly used function in simple project files is the \c include function which takes a filename as an argument. The contents of the given file are included in the project file at the place where the \c include function is used. @@ -292,7 +298,8 @@ The assignments inside the braces are only made if the condition is true. In this case, the special \c win32 variable must be set; this happens automatically on Windows, but this can also be specified on - other platforms by running \l {qmake}{ \c qmake} with the \c{-win32} command line + other platforms by running \l{qmake Manual#qmake}{\c qmake} + with the \c{-win32} command line option (see \l{Running qmake} for more information). The opening brace must stand on the same line as the condition. @@ -313,15 +320,17 @@ \section1 Project Templates The \c TEMPLATE variable is used to define the type of project that will - be built. If this is not declared in the project file, \l {qmake}{ \c qmake} assumes - that an application should be built, and will generate an appropriate - Makefile (or equivalent file) for the purpose. + be built. If this is not declared in the project file, + \l{qmake Manual#qmake}{\c qmake} assumes that an application should be + built, and will generate an appropriate Makefile (or equivalent file) + for the purpose. The types of project available are listed in the following table with - information about the files that \l {qmake}{ \c qmake} will generate for each of them: + information about the files that \l{qmake Manual#qmake}{\c qmake} + will generate for each of them: \table - \header \o Template \o Description of \l {qmake}{ \c qmake}output + \header \o Template \o Description of \l{qmake Manual#qmake}{\c qmake} output \row \o app (default) \o Creates a Makefile to build an application. \row \o lib \o Creates a Makefile to build a library. \row \o subdirs \o Creates a Makefile containing rules for the @@ -336,9 +345,10 @@ See the \l{qmake Tutorial} for advice on writing project files for projects that use the \c app and \c lib templates. - When the \c subdirs template is used, \l {qmake}{ \c qmake} generates a Makefile - to examine each specified subdirectory, process any project file it finds - there, and run the platform's \c make tool on the newly-created Makefile. + When the \c subdirs template is used, \l{qmake Manual#qmake}{\c qmake} + generates a Makefile to examine each specified subdirectory, + process any project file it finds there, and run the platform's + \c make tool on the newly-created Makefile. The \l{qmake Variable Reference#SUBDIRS}{SUBDIRS} variable is used to contain a list of all the subdirectories to be processed. @@ -348,7 +358,8 @@ The \l{qmake Variable Reference#CONFIG}{CONFIG variable} specifies the options and features that the compiler should use and the libraries that should be linked against. Anything can be added to the \c CONFIG variable, - but the options covered below are recognized by \l {qmake}{ \c qmake} internally. + but the options covered below are recognized by + \l{qmake Manual#qmake}{\c qmake} internally. The following options control the compiler flags that are used to build the project: @@ -360,11 +371,11 @@ \row \o debug \o The project is to be built in debug mode. \row \o debug_and_release \o The project is built in \e both debug and release modes. - \row \o debug_and_release_target \o The project is built in \e both debug + \row \o debug_and_release_target \o The project is built in \e both debug and release modes. TARGET is built into \e both the debug and release directories. \row \o build_all \o If \c debug_and_release is specified, the project is built in both debug and release modes by default. - \row \o autogen_precompile_source \o Automatically generates a \c .cpp file that includes + \row \o autogen_precompile_source \o Automatically generates a \c .cpp file that includes the precompiled header file specified in the .pro file. \row \o ordered \o When using the \c subdirs template, this option specifies that the directories listed should be processed in the @@ -372,15 +383,15 @@ \row \o warn_on \o The compiler should output as many warnings as possible. This is ignored if \c warn_off is specified. \row \o warn_off \o The compiler should output as few warnings as possible. - \row \o copy_dir_files \o Enables the install rule to also copy directories, not just files. + \row \o copy_dir_files \o Enables the install rule to also copy directories, not just files. \endtable The \c debug_and_release option is special in that it enables \e both debug and release versions of a project to be built. In such a case, the Makefile that - \l {qmake}{ \c qmake} generates includes a rule that builds both versions, and this can be - invoked in the following way: + \l{qmake Manual#qmake}{\c qmake} generates includes a rule that builds both versions, + and this can be invoked in the following way: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 0 Adding the \c build_all option to the \c CONFIG variable makes this rule the default when building the project, and installation targets will be @@ -423,10 +434,11 @@ build it as a multi-threaded application in \c debug mode, your project file will contain the following line: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 1 - Note, that you must use "+=", not "=", or \l {qmake}{ \c qmake} will not be able to - use Qt's configuration to determine the settings needed for your project. + Note, that you must use "+=", not "=", or \l{qmake Manual#qmake}{\c qmake} + will not be able to use Qt's configuration to determine the settings + needed for your project. \section1 Declaring Qt Libraries @@ -436,21 +448,21 @@ variable which can be used to declare the required extension modules. For example, we can enable the XML and network modules in the following way: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 2 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 2 Note that \c QT includes the \c core and \c gui modules by default, so the above declaration \e adds the network and XML modules to this default list. The following assignment \e omits the default modules, and will lead to errors when the application's source code is being compiled: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 3 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 3 If you want to build a project \e without the \c gui module, you need to exclude it with the "-=" operator. By default, \c QT contains both \c core and \c gui, so the following line will result in a minimal Qt project being built: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 4 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 4 The table below shows the options that can be used with the \c QT variable and the features that are associated with each of them: @@ -475,18 +487,18 @@ \section1 Configuration Features - \l {qmake}{ \c qmake} can be set up with extra configuration features that are specified - in feature (.prf) files. These extra features often provide support for - custom tools that are used during the build process. To add a feature to - the build process, append the feature name (the stem of the feature filename) - to the \c CONFIG variable. + \l{qmake Manual#qmake}{\c qmake} can be set up with extra configuration + features that are specified in feature (.prf) files. These extra features + often provide support for custom tools that are used during the build + process. To add a feature to the build process, append the feature name + (the stem of the feature filename) to the \c CONFIG variable. - For example, \l {qmake}{ \c qmake} can configure the build process to take advantage - of external libraries that are supported by + For example, \l{qmake Manual#qmake}{\c qmake} can configure the build + process to take advantage of external libraries that are supported by \l{http://www.freedesktop.org/wiki/Software_2fpkgconfig}{pkg-config}, such as the D-Bus and ogg libraries, with the following lines: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 5 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 5 More information about features can be found in the \l{qmake Advanced Usage#Adding New Configuration Features} @@ -498,15 +510,15 @@ If you are using other libraries in your project in addition to those supplied with Qt, you need to specify them in your project file. - The paths that \l {qmake}{ \c qmake} searches for libraries and the specific libraries - to link against can be added to the list of values in the + The paths that \l{qmake Manual#qmake}{\c qmake} searches for libraries + and the specific libraries to link against can be added to the list of values in the \l{qmake Variable Reference#LIBS}{LIBS} variable. The paths to the libraries themselves can be given, or the familiar Unix-style notation for specifying libraries and paths can be used if preferred. For example, the following lines show how a library can be specified: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 6 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 6 The paths containing header files can also be specified in a similar way using the \l{qmake Variable Reference#INCLUDEPATH}{INCLUDEPATH} variable. @@ -514,7 +526,7 @@ For example, it is possible to add several paths to be searched for header files: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 7 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 7 */ /*! @@ -524,8 +536,8 @@ \previouspage qmake Project Files \nextpage qmake Platform Notes - The behavior of \l {qmake}{ \c qmake} can be customized when it is run by - specifying various options on the command line. These allow the + The behavior of \l{qmake Manual#qmake}{\c qmake} can be customized when it + is run by specifying various options on the command line. These allow the build process to be fine-tuned, provide useful diagnostic information, and can be used to specify the target platform for your project. @@ -537,21 +549,23 @@ \section2 Syntax - The syntax used to run \l {qmake}{ \c qmake} takes the following simple form: + The syntax used to run \l{qmake Manual#qmake}{\c qmake} takes the + following simple form: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 8 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 8 - \l {qmake}{ \c qmake} supports two different modes of operation: In the default mode, - \l {qmake}{ \c qmake} will use the description in a project file to generate a Makefile, - but it is also possible to use \l {qmake}{ \c qmake} to generate project files. + \l{qmake Manual#qmake}{\c qmake} supports two different modes of operation: + In the default mode,\l{qmake Manual#qmake}{\c qmake} will use the + description in a project file to generate a Makefile, but it is also + possible to use \l{qmake Manual#qmake}{\c qmake} to generate project files. If you want to explicitly set the mode, you must specify it before all other options. The \c mode can be either of the following two values: \list \o \c -makefile \BR - \c qmake output will be a Makefile. + \l{qmake Manual#qmake}{\c qmake} output will be a Makefile. \o \c -project \BR - \c qmake output will be a project file. \BR + \l{qmake Manual#qmake}{\c qmake} output will be a project file. \BR \bold{Note:} It is likely that the created file will need to be edited; for example, adding the \c QT variable to suit what modules are required for the project. \endlist @@ -567,42 +581,48 @@ \section2 Options - A wide range of options can be specified on the command line to \l {qmake}{ \c qmake} in - order to customize the build process, and to override default settings for - your platform. The following basic options provide usage information, specify - where \l {qmake}{ \c qmake} writes the output file, and control the level of debugging - information that will be written to the console: + A wide range of options can be specified on the command line to + \l{qmake Manual#qmake}{\c qmake} in order to customize the build process, + and to override default settings for your platform. The following basic + options provide usage information, specify where + \l{qmake Manual#qmake}{\c qmake} writes the output file, and control the + level of debugging information that will be written to the console: \list \o \c -help \BR - \c qmake will go over these features and give some useful help. + \l{qmake Manual#qmake}{\c qmake} will go over these features and give some + useful help. \o \c -o file \BR - \c qmake output will be directed to \e file. If this option - is not specified, \c qmake will try to use a suitable file name for its - output, depending on the mode it is running in.\BR + \l{qmake Manual#qmake}{\c qmake} output will be directed to \e file. If + this option is not specified, \l{qmake Manual#qmake}{\c qmake} will try + to use a suitable file name for its output, depending on the mode it is + running in.\BR If '-' is specified, output is directed to stdout. \o \c -d \BR - \c qmake will output debugging information. + \l{qmake Manual#qmake}{\c qmake} will output debugging information. \endlist - For projects that need to be built differently on each target platform, with - many subdirectories, you can run \l {qmake}{ \c qmake} with each of the following - options to set the corresponding platform-specific variable in each - project file: + For projects that need to be built differently on each target platform, + with many subdirectories, you can run \l{qmake Manual#qmake}{\c qmake} with + each of the following options to set the corresponding platform-specific + variable in each project file: \list \o \c -unix \BR - \c qmake will run in unix mode. In this mode, Unix file - naming and path conventions will be used, additionally testing for \c unix - (as a scope) will succeed. This is the default mode on all Unices. + \l{qmake Manual#qmake}{\c qmake} will run in unix mode. In this mode, + Unix file naming and path conventions will be used, additionally + testing for \c unix (as a scope) will succeed. This is the default + mode on all Unices. \o \c -macx \BR - \c qmake will run in Mac OS X mode. In this mode, Unix file - naming and path conventions will be used, additionally testing for \c macx - (as a scope) will succeed. This is the default mode on Mac OS X. + \l{qmake Manual#qmake}{\c qmake} will run in Mac OS X mode. In this + mode, Unix file naming and path conventions will be used, additionally + testing for \c macx (as a scope) will succeed. This is the default mode + on Mac OS X. \o \c -win32 \BR - \c qmake will run in win32 mode. In this mode, Windows file naming and path - conventions will be used, additionally testing for \c win32 (as a scope) - will succeed. This is the default mode on Windows. + \l{qmake Manual#qmake}{\c qmake} will run in win32 mode. In this mode, + Windows file naming and path conventions will be used, additionally + testing for \c win32 (as a scope) will succeed. This is the default + mode on Windows. \endlist The template used for the project is usually specified by the \c TEMPLATE @@ -611,10 +631,11 @@ \list \o \c -t tmpl \BR - \c qmake will override any set \c TEMPLATE variables with tmpl, but only - \e after the .pro file has been processed. + \l{qmake Manual#qmake}{\c qmake} will override any set \c TEMPLATE + variables with tmpl, but only \e after the .pro file has been processed. \o \c -tp prefix \BR - \c qmake will add the prefix to the \c TEMPLATE variable. + \l{qmake Manual#qmake}{\c qmake} will add the prefix to the \c TEMPLATE + variable. \endlist The level of warning information can be fine-tuned to help you find problems in @@ -622,54 +643,59 @@ \list \o \c -Wall \BR - \c qmake will report all known warnings. + \l{qmake Manual#qmake}{\c qmake} will report all known warnings. \o \c -Wnone \BR - No warning information will be generated by \c qmake. + No warning information will be generated by \ + l{qmake Manual#qmake}{\c qmake}. \o \c -Wparser \BR - \c qmake will only generate parser warnings. This will alert - you to common pitfalls and potential problems in the parsing of your - project files. + \l{qmake Manual#qmake}{\c qmake} will only generate parser warnings. + This will alert you to common pitfalls and potential problems in the + parsing of your project files. \o \c -Wlogic \BR - \c qmake will warn of common pitfalls and potential problems in your - project file. For example, \c qmake will report whether a file is placed - into a list of files multiple times, or if a file cannot be found. + \l{qmake Manual#qmake}{\c qmake} will warn of common pitfalls and + potential problems in your project file. For example, + \l{qmake Manual#qmake}{\c qmake} will report whether a file is placed + into a list of files multiple times, or if a file cannot be found. \endlist \target MakefileMode \section2 Makefile Mode Options - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 9 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 9 - In Makefile mode, \l {qmake}{ \c qmake} will generate a Makefile that is used to build the - project. Additionally, the following options may be used in this mode to - influence the way the project file is generated: + In Makefile mode, \l{qmake Manual#qmake}{\c qmake} will generate a Makefile + that is used to build the project. Additionally, the following options may + be used in this mode to influence the way the project file is generated: \list \o \c -after \BR - \c qmake will process assignments given on the command line after - the specified files. + \l{qmake Manual#qmake}{\c qmake} will process assignments given on the + command line after the specified files. \o \c -nocache \BR - \c qmake will ignore the .qmake.cache file. + \l{qmake Manual#qmake}{\c qmake} will ignore the .qmake.cache file. \o \c -nodepend \BR - \c qmake will not generate any dependency information. + \l{qmake Manual#qmake}{\c qmake} will not generate any dependency + information. \o \c -cache file \BR - \c qmake will use \e file as the cache file, ignoring any other - .qmake.cache files found. + \l{qmake Manual#qmake}{\c qmake} will use \e file as the cache file, + ignoring any other .qmake.cache files found. \o \c -spec spec \BR - \c qmake will use \e spec as a path to platform and compiler information, - and the value of \c QMAKESPEC will be ignored. + \l{qmake Manual#qmake}{\c qmake} will use \e spec as a path to + platform and compiler information, and the value of \c QMAKESPEC will + be ignored. \endlist - You may also pass \l {qmake}{ \c qmake} assignments on the command line; - they will be processed before all of the files specified. For example: + You may also pass \l{qmake Manual#qmake}{\c qmake} assignments on the + command line; they will be processed before all of the files specified. + For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 10 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 10 This will generate a Makefile, from test.pro with Unix pathnames. However many of the specified options aren't necessary as they are the default. Therefore, the line can be simplified on Unix to: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 11 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 11 If you are certain you want your variables processed after the files specified, then you may pass the \c -after option. When this @@ -679,17 +705,18 @@ \target ProjectMode \section2 Project Mode Options - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 12 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 12 - In project mode, \l {qmake}{ \c qmake} will generate a project file. Additionally, you - may supply the following options in this mode: + In project mode, \l{qmake Manual#qmake}{\c qmake} will generate a project + file. Additionally, you may supply the following options in this mode: \list \o \c -r \BR - \c qmake will look through supplied directories recursively + \l{qmake Manual#qmake}{\c qmake} will look through supplied directories + recursively \o \c -nopwd \BR - \c qmake will not look in your current working directory for - source code and only use the specified \c files + \l{qmake Manual#qmake}{\c qmake} will not look in your current working + directory for source code and only use the specified \c files \endlist In this mode, the \c files argument can be a list of files or directories. @@ -712,9 +739,10 @@ Many cross-platform projects can be handled by the \c{qmake}'s basic configuration features. On some platforms, it is sometimes useful, or even - necessary, to take advantage of platform-specific features. \l {qmake}{ \c qmake} knows - about many of these features, and these can be accessed via specific - variables that only have an effect on the platforms where they are relevant. + necessary, to take advantage of platform-specific features. + \l{qmake Manual#qmake}{\c qmake} knows about many of these features, and + these can be accessed via specific variables that only have an effect on + the platforms where they are relevant. \tableofcontents @@ -725,38 +753,39 @@ \section2 Source and Binary Packages - The version of \l {qmake}{ \c qmake} supplied in source packages is configured slightly - differently to that supplied in binary packages in that it uses a different - feature specification. Where the source package typically uses the - \c macx-g++ specification, the binary package is typically configured to - use the \c macx-xcode specification. + The version of \l{qmake Manual#qmake}{\c qmake} supplied in source packages + is configured slightly differently to that supplied in binary packages in + that it uses a different feature specification. Where the source package + typically uses the \c macx-g++ specification, the binary package is + typically configured to use the \c macx-xcode specification. - Users of each package can override this configuration by invoking \l {qmake}{ \c qmake} - with the \c -spec option (see \l{Running qmake} for more information). This - makes it possible, for example, to use \l {qmake}{ \c qmake} from a binary package to + Users of each package can override this configuration by invoking + \l{qmake Manual#qmake}{\c qmake} with the \c -spec option (see + \l{Running qmake} for more information). This makes it possible, for + example, to use \l{qmake Manual#qmake}{\c qmake} from a binary package to create a Makefile in a project directory with the following command line invocation: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 13 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 13 \section2 Using Frameworks - \l {qmake}{ \c qmake} is able to automatically generate build rules for linking against - frameworks in the standard framework directory on Mac OS X, located at - \c{/Library/Frameworks/}. + \l{qmake Manual#qmake}{\c qmake} is able to automatically generate build + rules for linking against frameworks in the standard framework directory on + Mac OS X, located at \c{/Library/Frameworks/}. Directories other than the standard framework directory need to be specified to the build system, and this is achieved by appending linker options to the \l{qmake Variable Reference#QMAKE_LFLAGS}{QMAKE_LFLAGS} variable, as shown in the following example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 14 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 14 The framework itself is linked in by appending the \c{-framework} options and the name of the framework to the \l{qmake Variable Reference#LIBS}{LIBS} variable: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 15 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 15 \section2 Creating Frameworks @@ -768,7 +797,7 @@ \c lib_bundle option to the \l{qmake Variable Reference#CONFIG}{CONFIG} variable: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 16 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 16 The data associated with the library is specified using the \l{qmake Variable Reference#QMAKE_BUNDLE_DATA}{QMAKE_BUNDLE_DATA} @@ -776,7 +805,7 @@ bundle, and is often used to specify a collection of header files, as in the following example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 17 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 17 Here, the \c FRAMEWORK_HEADERS variable is a user-defined variable that is used to define the headers required to use a particular framework. @@ -801,10 +830,11 @@ The architectures to be supported in the binary are specified with the \l{qmake Variable Reference#CONFIG}{CONFIG} variable. For example, the - following assignment causes \l {qmake}{ \c qmake} to generate build rules to create - a universal binary for both PowerPC and x86 architectures: + following assignment causes \l{qmake Manual#qmake}{\c qmake} to generate + build rules to create a universal binary for both PowerPC and x86 + architectures: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 18 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 18 Additionally, developers using a PowerPC-based platform need to set the \l{qmake Variable Reference#QMAKE_MAC_SDK}{QMAKE_MAC_SDK} variable. @@ -816,13 +846,15 @@ Developers on Mac OS X can take advantage of \c{qmake}'s support for Xcode project files, as described in \l{Qt is Mac OS X Native#Development Tools}{Qt is Mac OS X Native}, - by running \l {qmake}{ \c qmake} to generate an Xcode project from an existing \l {qmake}{ \c qmake} - project files. For example: + by running \l{qmake Manual#qmake}{\c qmake} to generate an Xcode project + from an existing \l{qmake Manual#qmake}{\c qmake} project files. For + example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 19 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 19 - Note that, if a project is later moved on the disk, \l {qmake}{ \c qmake} must be run - again to process the project file and create a new Xcode project file. + Note that, if a project is later moved on the disk, + \l{qmake Manual#qmake}{\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 @@ -860,24 +892,27 @@ \l{Qt Commercial Edition} and do not need to worry about how project dependencies are managed. - However, some developers may need to import an existing \l {qmake}{ \c qmake} project - into Visual Studio. \l {qmake}{ \c qmake} is able to take a project file and create a - Visual Studio project that contains all the necessary information required - by the development environment. This is achieved by setting the \c qmake + However, some developers may need to import an existing + \l{qmake Manual#qmake}{\c qmake} project into Visual Studio. + \l{qmake Manual#qmake}{\c qmake} is able to take a project file and create + a Visual Studio project that contains all the necessary information + required by the development environment. This is achieved by setting the + \l{qmake Manual#qmake}{\c qmake} \l{qmake Variable Reference#TEMPLATE}{project template} to either \c vcapp (for application projects) or \c vclib (for library projects). This can also be set using a command line option, for example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 20 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 20 It is possible to recursively generate \c{.vcproj} files in subdirectories and a \c{.sln} file in the main directory, by typing: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 21 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 21 - Each time you update the project file, you need to run \l {qmake}{ \c qmake} to generate - an updated Visual Studio project. + Each time you update the project file, you need to run + \l{qmake Manual#qmake}{\c qmake} to generate an updated Visual Studio + project. \note If you are using the Visual Studio Add-in, you can import \c .pro files via the \gui{Qt->Import from .pro file} menu item. @@ -893,25 +928,25 @@ the following assignment to the \l{qmake Variable Reference#CONFIG} {CONFIG} variable: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 22 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 22 Also, the manifest embedding for DLLs can be removed with the following assignment to the \l{qmake Variable Reference#CONFIG}{CONFIG} variable: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 23 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 23 This is discussed in more detail in the \l{Deploying an Application on Windows#Visual Studio 2005 Onwards} {deployment guide for Windows}. - \section1 Symbian platform + \section1 Symbian Platform Features specific to this platform include handling of static data, capabilities, stack and heap size, compiler specific options, and unique identifiers for the application or library. - \section2 Handling of static data + \section2 Handling of Static Data If the application uses any static data, the build system needs to be informed about it. This is because Symbian tries to save memory if no @@ -919,11 +954,11 @@ To specify that static data support is desired, add this to the project file: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 129 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 129 The default value is zero. - \section2 Stack and heap size + \section2 Stack and Heap Size The Symbian platform uses predefined sizes for stacks and heaps. If an application exceeds either limit, it may crash or fail to complete its @@ -935,13 +970,13 @@ prevents the application from starting if that amount of memory is not available. The minimum and maximum values are separated by a space. For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 130 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 130 The default values depend on the version of the Symbian SDK you're using, - however, the Qt toolchain sets this to the maximum possible value and this - should not be changed. + however, the Qt toolchain sets this to the maximum possible value and this + should not be changed. - \section2 Compiler specific options + \section2 Compiler-Specific Options General compiler options can as usual be set using \c QMAKE_CFLAGS and \c QMAKE_CXXFLAGS. In order to set specific compiler options, \c QMAKE_CFLAGS.<compiler> and @@ -951,9 +986,9 @@ Here is an example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 131 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 131 - \section2 Unique identifiers + \section2 Unique Identifiers Symbian applications may have unique identifiers attached to them. Here is how to define them in a project file: @@ -961,37 +996,38 @@ There are four available types of IDs supported: \c UID2, \c UID3, \c SID, and \c VID. They are specified like this: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 132 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 132 If \c SID is not specified, it defaults to the same value as \c UID3. If \c UID3 is not specified, qmake will automatically generate a \c UID3 suitable for development and debugging. This value should be manually - specified for applications that are to be released. In order to obtain - an official UID, please contact \l{Symbian}{http:\\www.symbiansigned.com}. - Both \c SID and \c VID default to empty values. + specified for applications that are to be released. See the + \l{Symbian Signed} Web site for information about obtaining an official + UID. Both \c SID and \c VID default to empty values. There exists one UID1 too, but this should not be touched by any application. - - The UID2 has a specific value for different types of files - e.g. apps/exes - are always 0x100039CE. The toolchain will set this for value for the most common file types like, - EXE/APP and shared library DLL. - - For more information about unique identifiers and their meaning for Symbian applications, - please refer to the \l{Symbian SDK documentation}{http://developer.symbian.org/main/documentation/reference/s3/pdk/GUID-380A8C4F-3EB6-5E1C-BCFB-ED5B866136D9.html} - + + The UID2 has a specific value for different types of files; e.g. apps/exes + are always 0x100039CE. The toolchain will set this for value for the most common file types like, + EXE/APP and shared library DLL. + + For more information about unique identifiers and their meaning for + Symbian applications, please refer to the \l{UID Q&As (Symbian Signed)} + page in the \l{Forum Nokia Wiki} for more information. + \section2 Capabilities Capabilities define extra privileges for the application, such as the ability to list all files on the file system. Capabilities are defined in the project file like this: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 133 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 133 It is also possible to specify which capabilities \e not to have, by first specifying \c ALL and then list the unwanted capabilities with a minus in front of them, like this: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 134 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 134 For more information about capabilities, please refer to the Symbian SDK documentation. */ @@ -1003,14 +1039,14 @@ \previouspage Using Precompiled Headers \nextpage qmake Variable Reference - This reference is a detailed index of all the variables and function - that are available for use in \c qmake project files. + This reference is a detailed index of all the variables and function that + are available for use in \l{qmake Manual#qmake}{\c qmake} project files. \section1 Variable Reference The \l{qmake Variable Reference} describes the variables that are - recognized by \l {qmake}{ \c qmake}when configuring the build process for - projects. + recognized by \l{qmake Manual#qmake}{\c qmake}when configuring the build + process for projects. \section1 Function Reference @@ -1059,8 +1095,8 @@ \section1 Environment Variables and Configuration The \l{Configuring qmake's Environment} chapter of this manual - describes the environment variables that \l {qmake}{ \c qmake} uses when - configuring the build process. + describes the environment variables that \l{qmake Manual#qmake}{\c qmake} + uses when configuring the build process. */ /*! @@ -1089,23 +1125,23 @@ \e {This is only used on the Symbian platform.} - Generic \c bld.inf file content can be specified with \c BLD_INF_RULES variables. - The section of \c bld.inf file where each rule goes is appended to + Generic \c bld.inf file content can be specified with \c BLD_INF_RULES variables. + The section of \c bld.inf file where each rule goes is appended to \c BLD_INF_RULES with a dot. For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 152 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 152 - This will add the specified statements to the \c prj_exports section of the + This will add the specified statements to the \c prj_exports section of the generated \c bld.inf file. It is also possible to add multiple rows in a single block. Each double quoted string will be placed on a new row in the generated \c bld.inf file. - For example: + For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 143 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 143 Any rules you define will be added after automatically generated rules in each section. @@ -1115,7 +1151,7 @@ The \c CONFIG variable specifies project configuration and compiler options. The values will be recognized internally by - \l {qmake}{ \c qmake} and have special meaning. They are as follows. + \l{qmake Manual#qmake}{\c qmake} and have special meaning. They are as follows. These \c CONFIG values control compilation flags: @@ -1151,25 +1187,28 @@ defined in the \c CONFIG variable, it is necessary to use the \c debug_and_release option if you want to allow both debug and release versions of a project to be built. In such a case, the Makefile that - \l {qmake}{ \c qmake} generates includes a rule that builds both versions, and this can - be invoked in the following way: + \l{qmake Manual#qmake}{\c qmake} generates includes a rule that builds both + versions, and this can be invoked in the following way: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 24 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 24 - When linking a library, \l {qmake}{ \c qmake} relies on the underlying platform to know - what other libraries this library links against. However, if linking - statically, \l {qmake}{ \c qmake} will not get this information unless we use the following - \c CONFIG options: + When linking a library, \l{qmake Manual#qmake}{\c qmake} relies on the + underlying platform to know what other libraries this library links + against. However, if linking statically, \l{qmake Manual#qmake}{\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 \l {qmake}{ \c qmake} to track these - dependencies. When this option is enabled, \l {qmake}{ \c qmake} will create a file + \row \o create_prl \o This option enables + \l{qmake Manual#qmake}{\c qmake} to track these dependencies. When this + option is enabled, \l{qmake Manual#qmake}{\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, \l {qmake}{ \c qmake} will process all - libraries linked to by the application and find their meta-information - (see \l{LibDepend}{Library Dependencies} for more info). + \row \o link_prl \o When this is enabled, + \l{qmake Manual#qmake}{\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 @@ -1189,7 +1228,7 @@ will be set for each of these mode, and you can test for this to perform build-specific tasks. For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 25 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 25 As a result, it may be useful to define mode-specific variables, such as \l{#QMAKE_LFLAGS_RELEASE}{QMAKE_LFLAGS_RELEASE}, instead of general @@ -1287,7 +1326,7 @@ \row \o stdbinary \o Builds an Open C binary (i.e. STDDLL, STDEXE, or STDLIB, depending on the target binary type.) \row \o no_icon \o Doesn't generate resources needed for displaying an icon - for executable in application menu (app only). + for executable in application menu (app only). \row \o symbian_test \o Places mmp files and extension makefiles under test sections in generated bld.inf instead of their regular sections. Note that this only affects automatically generated bld.inf content; @@ -1316,17 +1355,17 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 26 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 26 \target DEFINES \section1 DEFINES - \l {qmake}{ \c qmake} adds the values of this variable as compiler C - preprocessor macros (-D option). + \l{qmake Manual#qmake}{\c qmake} adds the values of this variable as + compiler C preprocessor macros (-D option). For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 27 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 27 \target DEF_FILE \section1 DEF_FILE @@ -1360,7 +1399,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 28 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 28 This will upload all PNG images in \c path to the same directory your build target will be deployed to. @@ -1376,7 +1415,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 29 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 29 \note In Windows CE all linked Qt libraries will be deployed to the path specified by \c{myFiles.path}. On Symbian platform all libraries and executables @@ -1387,7 +1426,7 @@ dynamically loadable libraries need special handling. When deploying extra executables or dynamically loadable libraries, the target path must specify \\sys\\bin. For plugins, the target path must specify the - location where the plugin stub will be deployed to (see the + location where the plugin stub will be deployed to (see the \l{How to Create Qt Plugins} document for more information about plugins). If the binary cannot be found from the indicated source path, the directory Symbian build process moves the executables to is @@ -1395,10 +1434,10 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 128 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 128 On the Symbian platform, generic PKG file content can also be specified with this - variable. You can use either \c pkg_prerules or \c pkg_postrules to + variable. You can use either \c pkg_prerules or \c pkg_postrules to pass raw data to PKG file. The strings in \c pkg_prerules are added before package-body and \c pkg_postrules after. \c pkg_prerules is used for defining vendor information, dependencies, custom package headers, and the @@ -1411,7 +1450,7 @@ For example, to deploy DLL and add a new dependency: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 140 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 140 Please note that \c pkg_prerules can also replace default statements in pkg file. If no pkg_prerules is defined, qmake makes sure that PKG file @@ -1445,7 +1484,7 @@ targeted to only one of above files by appending listed rules suffix to the variable name: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 153 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 153 On the Symbian platform, the \c default_deployment item specifies default platform and package dependencies. Those dependencies can be @@ -1462,7 +1501,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 141 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 141 On the Symbian platform, a default deployment is generated for all application projects. You can modify the autogenerated default @@ -1476,7 +1515,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 154 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 154 This will entirely remove the default application deployment. @@ -1486,7 +1525,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 155 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 155 This will show a message box that gives user an option to cancel the installation and then automatically runs the application after @@ -1502,19 +1541,19 @@ Often the default is not optimal for displaying to end user. To set a better display name for these purposes, use \c{DEPLOYMENT.display_name} variable: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 156 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 156 On the Symbian platform, you can use \c{DEPLOYMENT.installer_header} variable to generate smart installer wrapper for your application. If you specify just UID of the installer package as the value, then installer package name and version will be autogenerated: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 146 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 146 If autogenerated values are not suitable, you can also specify the sis header yourself using this variable: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 147 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 147 \target DEPLOYMENT_PLUGIN \section1 DEPLOYMENT_PLUGIN @@ -1525,8 +1564,8 @@ available in Qt can be explicitly deployed to the device. See \l{Static Plugins}{Static Plugins} for a complete list. - \note In Windows CE, No plugins will be deployed automatically. - If the application depends on plugins, these plugins have to be specified + \note In Windows CE, No plugins will be deployed automatically. + If the application depends on plugins, these plugins have to be specified manually. \note On the Symbian platform, all plugins supported by this variable @@ -1535,7 +1574,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 142 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 142 This will upload the jpeg imageformat plugin to the plugins directory on the Windows CE device. @@ -1547,15 +1586,16 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 30 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 30 \target DESTDIR_TARGET \section1 DESTDIR_TARGET - This variable is set internally by \l {qmake}{ \c qmake}, which is basically the - \c DESTDIR variable with the \c TARGET variable appened at the end. - The value of this variable is typically handled by \l {qmake}{ \c qmake} or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable is set internally by \l{qmake Manual#qmake}{\c qmake}, which + is basically the \c DESTDIR variable with the \c TARGET variable appened at + the end. The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target DLLDESTDIR \section1 DLLDESTDIR @@ -1570,15 +1610,16 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 31 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 31 \target DSP_TEMPLATE \section1 DSP_TEMPLATE - This variable is set internally by \l {qmake}{ \c qmake}, which specifies where the - dsp template file for basing generated dsp files is stored. The value - of this variable is typically handled by \l {qmake}{ \c qmake} or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable is set internally by \l{qmake Manual#qmake}{\c qmake}, which + specifies where the dsp template file for basing generated dsp files is + stored. The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target FORMS \section1 FORMS @@ -1590,7 +1631,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 32 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 32 If FORMS3 is defined in your project, then this variable must contain forms for uic, and not uic3. If CONFIG contains uic3, and FORMS3 is not @@ -1606,7 +1647,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 33 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 33 \target GUID \section1 GUID @@ -1623,16 +1664,16 @@ Defines the header files for the project. - \l {qmake}{ \c qmake} will generate dependency information (unless \c -nodepend - is specified on the \l{Running qmake#Commands}{command line}) - for the specified headers. \l {qmake}{ \c qmake} will also automatically detect if - \c moc is required by the classes in these headers, and add the - appropriate dependencies and files to the project for generating and - linking the moc files. + \l{qmake Manual#qmake}{\c qmake} will generate dependency information (unless + \c -nodepend is specified on the \l{Running qmake#Commands}{command line}) + for the specified headers. \l{qmake Manual#qmake}{\c qmake} will also + automatically detect if \c moc is required by the classes in these headers, + and add the appropriate dependencies and files to the project for generating + and linking the moc files. For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 34 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 34 See also \l{#SOURCES}{SOURCES}. @@ -1651,7 +1692,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 35 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 35 To specify a path containing spaces, quote the path using the technique mentioned in the \l{qmake Project Files#Whitespace}{qmake Project Files} @@ -1671,24 +1712,25 @@ build target will be installed, and the \c INSTALLS assignment adds the build target to the list of existing resources to be installed: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 36 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 36 - Note that \l {qmake}{ \c qmake} will skip files that are executable. If you need to install - executable files, you can unset the files' executable flags. + Note that \l{qmake Manual#qmake}{\c qmake} will skip files that are + executable. If you need to install executable files, you can unset the + files' executable flags. \target LEXIMPLS \section1 LEXIMPLS This variable contains a list of lex implementation files. The value - of this variable is typically handled by \l {qmake}{ \c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely - needs to be modified. + of this variable is typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \target LEXOBJECTS \section1 LEXOBJECTS This variable contains the names of intermediate lex object files.The value of this variable is typically handled by - \l {qmake}{ \c qmake} and rarely needs to be modified. + \l{qmake Manual#qmake}{\c qmake} and rarely needs to be modified. \target LEXSOURCES \section1 LEXSOURCES @@ -1699,7 +1741,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 37 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 37 \target LIBS \section1 LIBS @@ -1713,7 +1755,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 38 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 38 To specify a path containing spaces, quote the path using the technique mentioned in the \l{qmake Project Files#Whitespace}{qmake Project Files} @@ -1741,7 +1783,7 @@ unique names before it is used. To change this behavior, add the \c no_lflags_merge option to the \c CONFIG variable: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 39 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 39 \target LITERAL_HASH \section1 LITERAL_HASH @@ -1761,9 +1803,10 @@ \section1 MAKEFILE This variable specifies the name of the Makefile which - \l {qmake}{ \c qmake} should use when outputting the dependency information - for building a project. The value of this variable is typically - handled by \l {qmake}{ \c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + \l{qmake Manual#qmake}{\c qmake} should use when outputting the dependency + information for building a project. The value of this variable is + typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \bold{Note:} On the Symbian platform, this variable is ignored. @@ -1772,44 +1815,45 @@ This variable contains the name of the Makefile generator to use when generating a Makefile. The value of this variable is typically - handled internally by \l {qmake}{ \c qmake} and rarely needs to be modified. + handled internally by \l{qmake Manual#qmake}{\c qmake} and rarely needs to + be modified. \target MMP_RULES \section1 MMP_RULES \e {This is only used on the Symbian platform.} - Generic MMP file content can be specified with this variable. + Generic MMP file content can be specified with this variable. For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 137 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 137 This will add the specified statement to the end of the generated MMP file. It is also possible to add multiple rows in a single block. Each double quoted string will be placed on a new row in the generated MMP file. - For example: + For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 138 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 138 If you need to include a hash (\c{#}) character inside the - \c MMP_RULES statement, it can be done with the variable + \c MMP_RULES statement, it can be done with the variable \c LITERAL_HASH as follows: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 139 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 139 There is also a convenience function for adding conditional rules called \c{addMMPRules}. Suppose you need certain functionality to require different library depending on architecture. This can be specified with \c{addMMPRules} as follows: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 148 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 148 \note You should not use this variable to add MMP statements that are explicitly supported by their own variables, such as - \c TARGET.EPOCSTACKSIZE. + \c TARGET.EPOCSTACKSIZE. Doing so could result in duplicate statements in the MMP file. \target MOC_DIR @@ -1820,7 +1864,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 40 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 40 \target OBJECTS \section1 OBJECTS @@ -1828,8 +1872,8 @@ This variable is generated from the \link #SOURCES SOURCES \endlink variable. The extension of each source file will have been replaced by .o (Unix) or .obj (Win32). The value of this variable is - typically handled by \l {qmake}{ \c qmake} or \l{#QMAKESPEC}{qmake.conf} and - rarely needs to be modified. + typically handled by \l {qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \target OBJECTS_DIR \section1 OBJECTS_DIR @@ -1839,16 +1883,16 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 41 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 41 \target OBJMOC \section1 OBJMOC - This variable is set by \l {qmake}{ \c qmake} if files can be found that - contain the Q_OBJECT macro. \c OBJMOC contains the - name of all intermediate moc object files. The value of this variable - is typically handled by \l {qmake}{ \c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be - modified. + This variable is set by \l{qmake Manual#qmake}{\c qmake} if files can be + found that contain the Q_OBJECT macro. \c OBJMOC contains the name of all + intermediate moc object files. The value of this variable is typically + handled by \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} + and rarely needs to be modified. \target POST_TARGETDEPS \section1 POST_TARGETDEPS @@ -1887,8 +1931,8 @@ This variable contains a list of header files that require some sort of pre-compilation step (such as with moc). The value of this - variable is typically handled by \l {qmake}{ \c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be - modified. + variable is typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \target PWD \section1 PWD @@ -1909,54 +1953,58 @@ \section1 OUT_PWD This variable contains the full path leading to the directory where - \l {qmake}{ \c qmake} places the generated Makefile. + \l{qmake Manual#qmake}{\c qmake} places the generated Makefile. \target QMAKE_systemvariable \section1 QMAKE - This variable contains the name of the \l {qmake}{ \c qmake} program - itself and is placed in generated Makefiles. The value of this - variable is typically handled by \l {qmake}{ \c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be - modified. + This variable contains the name of the \l{qmake Manual#qmake}{\c qmake} + program itself and is placed in generated Makefiles. The value of this + variable is typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \target QMAKESPEC_systemvariable \section1 QMAKESPEC - This variable contains the name of the \l {qmake}{ \c qmake} - configuration to use when generating Makefiles. The value of this - variable is typically handled by \l {qmake}{ \c qmake} and rarely needs to be modified. + This variable contains the name of the \l{qmake Manual#qmake}{\c qmake} + configuration to use when generating Makefiles. The value of this variable + is typically handled by \l{qmake Manual#qmake}{\c qmake} and rarely needs + to be modified. - Use the \c{QMAKESPEC} environment variable to override the \l {qmake}{ \c qmake} configuration. - Note that, due to the way \l {qmake}{ \c qmake} reads project files, setting the \c{QMAKESPEC} - environment variable from within a project file will have no effect. + Use the \c{QMAKESPEC} environment variable to override the + \l{qmake Manual#qmake}{\c qmake} configuration. Note that, due to the way + \l{qmake Manual#qmake}{\c qmake} reads project files, setting the + \c{QMAKESPEC} environment variable from within a project file will have no + effect. \target QMAKE_APP_FLAG \section1 QMAKE_APP_FLAG This variable is empty unless the \c app \l{#TEMPLATE}{TEMPLATE} is specified. The value of this - variable is typically handled by \l {qmake}{ \c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be - modified. Use the following instead: + variable is typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. Use the + following instead: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 42 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 42 \target QMAKE_APP_OR_DLL \section1 QMAKE_APP_OR_DLL - This variable is empty unless the \c app or \c dll - \l{#TEMPLATE}{TEMPLATE} is specified. The value of this - variable is typically handled by \l {qmake}{ \c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be - modified. + This variable is empty unless the \c app or \c dll \l{#TEMPLATE}{TEMPLATE} + is specified. The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target QMAKE_AR_CMD \section1 QMAKE_AR_CMD \e {This is used on Unix platforms only.} - This variable contains the command for invoking the program which - creates, modifies and extracts archives. The value of this variable is - typically handled by \l {qmake}{ \c qmake} or \l{#QMAKESPEC}{qmake.conf} - and rarely needs to be modified. + This variable contains the command for invoking the program which creates, + modifies and extracts archives. The value of this variable is typically + handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \target QMAKE_BUNDLE_DATA \section1 QMAKE_BUNDLE_DATA @@ -1968,7 +2016,7 @@ and \c path/to/header_two.h to a group containing information about the headers supplied with the framework: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 43 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 43 The last line adds the information about the headers to the collection of resources that will be installed with the library bundle. @@ -1990,7 +2038,7 @@ For example, the following definition will result in a framework with the \c{.myframework} extension: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 44 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 44 \e{This is used on Mac OS X only.} @@ -2004,9 +2052,10 @@ \target QMAKE_CFLAGS_DEBUG \section1 QMAKE_CFLAGS_DEBUG - This variable contains the flags for the C compiler in debug mode.The value of this variable is - typically handled by \l {qmake}{ \c qmake} or \l{#QMAKESPEC}{qmake.conf} - and rarely needs to be modified. + This variable contains the flags for the C compiler in debug mode. The + value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target QMAKE_CFLAGS_MT \section1 QMAKE_CFLAGS_MT @@ -2014,7 +2063,7 @@ This variable contains the compiler flags for creating a multi-threaded application or when the version of Qt that you link against is a multi-threaded statically linked library. The value of - this variable is typically handled by \l {qmake}{ \c qmake} or + this variable is typically handled by \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \target QMAKE_CFLAGS_MT_DBG @@ -2023,8 +2072,9 @@ This variable contains the compiler flags for creating a debuggable multi-threaded application or when the version of Qt that you link against is a debuggable multi-threaded statically linked library. The - value of this variable is typically handled by \l {qmake}{ \c qmake} or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target QMAKE_CFLAGS_MT_DLL \section1 QMAKE_CFLAGS_MT_DLL @@ -2034,8 +2084,8 @@ This variable contains the compiler flags for creating a multi-threaded dll or when the version of Qt that you link against is a multi-threaded dll. The value of this variable is typically - handled by \l {qmake}{ \c qmake} or \l{#QMAKESPEC}{qmake.conf} and - rarely needs to be modified. + handled by \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} + and rarely needs to be modified. \target QMAKE_CFLAGS_MT_DLLDBG \section1 QMAKE_CFLAGS_MT_DLLDBG @@ -2045,16 +2095,17 @@ This variable contains the compiler flags for creating a debuggable multi-threaded dll or when the version of Qt that you link against is a debuggable multi-threaded statically linked library. - The value of this variable is typically handled by \l {qmake}{ \c qmake} or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target QMAKE_CFLAGS_RELEASE \section1 QMAKE_CFLAGS_RELEASE This variable contains the compiler flags for creating a non-debuggable application. The value of this variable is typically - handled by \l {qmake}{ \c qmake} or \l{#QMAKESPEC}{qmake.conf} and - rarely needs to be modified. + handled by \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} + and rarely needs to be modified. \target QMAKE_CFLAGS_SHLIB \section1 QMAKE_CFLAGS_SHLIB @@ -2063,33 +2114,32 @@ This variable contains the compiler flags for creating a shared library. The value of this variable is typically handled by - \l {qmake}{ \c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely needs - to be modified. + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target QMAKE_CFLAGS_THREAD \section1 QMAKE_CFLAGS_THREAD This variable contains the compiler flags for creating a multi-threaded application. The value of this variable is typically handled by - \l {qmake}{ \c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely needs - to be modified. + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target QMAKE_CFLAGS_WARN_OFF \section1 QMAKE_CFLAGS_WARN_OFF This variable is not empty if the warn_off \l{#CONFIG}{CONFIG} option is specified. The value of this - variable is typically handled by \l {qmake}{ \c qmake} or \l{#QMAKESPEC}{qmake.conf} - and rarely needs to be modified. + variable is typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \target QMAKE_CFLAGS_WARN_ON \section1 QMAKE_CFLAGS_WARN_ON - This variable is not empty if the warn_on - \l{#CONFIG}{CONFIG} option is specified. - The value of this variable is typically handled by - \l {qmake}{ \c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely needs - to be modified. + This variable is not empty if the warn_on \l{#CONFIG}{CONFIG} option is + specified. The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target QMAKE_CLEAN \section1 QMAKE_CLEAN @@ -2107,17 +2157,17 @@ \section1 QMAKE_CXXFLAGS This variable contains the C++ compiler flags that are used when building - a project. The value of this variable is typically handled by \l {qmake}{ \c qmake} or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. The flags - specific to debug and release modes can be adjusted by modifying - the \c QMAKE_CXXFLAGS_DEBUG and \c QMAKE_CXXFLAGS_RELEASE variables, - respectively. + a project. The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. The flags specific to debug and release modes can be + adjusted by modifying the \c QMAKE_CXXFLAGS_DEBUG and + \c QMAKE_CXXFLAGS_RELEASE variables, respectively. \bold{Note:} On the Symbian platform, this variable can be used to pass architecture specific options to each compiler in the Symbian build system. For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 131 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 131 For more information, see \l{qmake Platform Notes#Compiler specific options}{qmake Platform Notes}. @@ -2127,24 +2177,24 @@ This variable contains the C++ compiler flags for creating a debuggable application. The value of this variable is typically handled by - \l {qmake}{ \c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely needs - to be modified. + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target QMAKE_CXXFLAGS_MT \section1 QMAKE_CXXFLAGS_MT This variable contains the C++ compiler flags for creating a multi-threaded application. The value of this variable is typically handled by - \l {qmake}{ \c qmake}or \l{#QMAKESPEC}{qmake.conf} and rarely needs - to be modified. + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target QMAKE_CXXFLAGS_MT_DBG \section1 QMAKE_CXXFLAGS_MT_DBG - This variable contains the C++ compiler flags for creating a debuggable multi-threaded - application. The value of this variable is typically handled by - \l {qmake}{ \c qmake}or \l{#QMAKESPEC}{qmake.conf} and rarely needs - to be modified. + This variable contains the C++ compiler flags for creating a debuggable + multi-threaded application. The value of this variable is typically handled + by \l{qmake Manual#qmake}{\c qmake}or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target QMAKE_CXXFLAGS_MT_DLL \section1 QMAKE_CXXFLAGS_MT_DLL @@ -2153,56 +2203,58 @@ This variable contains the C++ compiler flags for creating a multi-threaded dll. The value of this variable is typically handled by - \l {qmake}{ \c qmake}or \l{#QMAKESPEC}{qmake.conf} and rarely needs - to be modified. + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target QMAKE_CXXFLAGS_MT_DLLDBG \section1 QMAKE_CXXFLAGS_MT_DLLDBG \c {This is used on Windows only.} - This variable contains the C++ compiler flags for creating a multi-threaded debuggable - dll. The value of this variable is typically handled by - \l {qmake}{ \c qmake}or \l{#QMAKESPEC}{qmake.conf} and rarely needs - to be modified. + This variable contains the C++ compiler flags for creating a multi-threaded + debuggable dll. The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target QMAKE_CXXFLAGS_RELEASE \section1 QMAKE_CXXFLAGS_RELEASE - This variable contains the C++ compiler flags for creating an - application. The value of this variable is typically handled by - \l {qmake}{ \c qmake}or \l{#QMAKESPEC}{qmake.conf} and rarely needs - to be modified. + This variable contains the C++ compiler flags for creating an application. + The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target QMAKE_CXXFLAGS_SHLIB \section1 QMAKE_CXXFLAGS_SHLIB - This variable contains the C++ compiler flags for creating a - shared library. The value of this variable is typically handled by - \l {qmake}{ \c qmake}or \l{#QMAKESPEC}{qmake.conf} and rarely needs - to be modified. + This variable contains the C++ compiler flags for creating a shared library. + The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target QMAKE_CXXFLAGS_THREAD \section1 QMAKE_CXXFLAGS_THREAD - This variable contains the C++ compiler flags for creating a - multi-threaded application. The value of this variable is typically handled by - \l {qmake}{ \c qmake}or \l{#QMAKESPEC}{qmake.conf} and rarely needs - to be modified. + This variable contains the C++ compiler flags for creating a multi-threaded + application. The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake}or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target QMAKE_CXXFLAGS_WARN_OFF \section1 QMAKE_CXXFLAGS_WARN_OFF - This variable contains the C++ compiler flags for suppressing compiler warnings. - The value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains the C++ compiler flags for suppressing compiler + warnings. The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target QMAKE_CXXFLAGS_WARN_ON \section1 QMAKE_CXXFLAGS_WARN_ON This variable contains C++ compiler flags for generating compiler warnings. - The value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target QMAKE_DISTCLEAN \section1 QMAKE_DISTCLEAN @@ -2212,9 +2264,9 @@ \target QMAKE_EXTENSION_SHLIB \section1 QMAKE_EXTENSION_SHLIB - This variable contains the extention for shared libraries. The value of this - variable is typically handled by \l {qmake}{ \c qmake}or \l{#QMAKESPEC}{qmake.conf} - and rarely needs to be modified. + This variable contains the extention for shared libraries. The value of + this variable is typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. Note that platform-specific variables that change the extension will override the contents of this variable. @@ -2286,16 +2338,18 @@ \target QMAKE_FAILED_REQUIREMENTS \section1 QMAKE_FAILED_REQUIREMENTS - This variable contains the list of requirements that were failed to be met when - \l {qmake}{ \c qmake}was used. For example, the sql module is needed and wasn't compiled into Qt. The - value of this variable is typically handled by \l {qmake}{ \c qmake}or \l{#QMAKESPEC}{qmake.conf} - and rarely needs to be modified. + This variable contains the list of requirements that were failed to be met + when \l{qmake Manual#qmake}{\c qmake} was used. For example, the sql module + is needed and wasn't compiled into Qt. The value of this variable is + typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \target QMAKE_FILETAGS \section1 QMAKE_FILETAGS - This variable contains the file tags needed to be entered into the Makefile, such as SOURCES - and HEADERS. The value of this variable is typically handled by \l {qmake}{ \c qmake}or + This variable contains the file tags needed to be entered into the + Makefile, such as SOURCES and HEADERS. The value of this variable is + typically handled by \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 QMAKE_FRAMEWORK_BUNDLE_NAME @@ -2329,26 +2383,28 @@ \target QMAKE_INCDIR \section1 QMAKE_INCDIR - This variable contains the location of all known header files to be added to - INCLUDEPATH when building an application. The value of this variable is - typically handled by \l {qmake}{ \c qmake}or \l{#QMAKESPEC}{qmake.conf} and rarely - needs to be modified. + This variable contains the location of all known header files to be added + to INCLUDEPATH when building an application. The value of this variable is + typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \target QMAKE_INCDIR_EGL \section1 QMAKE_INCDIR_EGL - This variable contains the location of EGL header files to be added - to INCLUDEPATH when building an application with OpenGL/ES or - OpenVG support. The value of this variable is typically handled by - \l {qmake}{ \c qmake}or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains the location of EGL header files to be added to + INCLUDEPATH when building an application with OpenGL/ES or OpenVG support. + The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target QMAKE_INCDIR_OPENGL \section1 QMAKE_INCDIR_OPENGL This variable contains the location of OpenGL header files to be added to INCLUDEPATH when building an application with OpenGL support. The - value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + value of this variable is typically handled by + \l{qmake Manual#qmake}{\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. @@ -2359,8 +2415,9 @@ to INCLUDEPATH when building an application with OpenGL ES 1 or OpenGL ES 2 support respectively. - The value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + The value of this variable is typically handled by \ + l{qmake Manual#qmake}{\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. @@ -2370,8 +2427,9 @@ This variable contains the location of OpenVG header files to be added to INCLUDEPATH when building an application with OpenVG support. The - value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. If the OpenVG implementation uses EGL then QMAKE_INCDIR_EGL may also need to be set. @@ -2379,28 +2437,28 @@ \target QMAKE_INCDIR_QT \section1 QMAKE_INCDIR_QT - This variable contains the location of all known header file - paths to be added to INCLUDEPATH when building a Qt application. The value - of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains the location of all known header file paths to be + added to INCLUDEPATH when building a Qt application. The value of this + variable is typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \target QMAKE_INCDIR_THREAD \section1 QMAKE_INCDIR_THREAD - This variable contains the location of all known header file - paths to be added to INCLUDEPATH when building a multi-threaded application. - The value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains the location of all known header file paths to be + added to INCLUDEPATH when building a multi-threaded application. The value + of this variable is typically handled by \l{qmake Manual#qmake}{\c qmake} + or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \target QMAKE_INCDIR_X11 \section1 QMAKE_INCDIR_X11 \e {This is used on Unix platforms only.} - This variable contains the location of X11 header file paths to be - added to INCLUDEPATH when building a X11 application. The - value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains the location of X11 header file paths to be added + to INCLUDEPATH when building a X11 application. The value of this variable + is typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \target QMAKE_INFO_PLIST \section1 QMAKE_INFO_PLIST @@ -2428,31 +2486,30 @@ \e {This is used on Windows only.} - This variable contains link flags when building console - programs. The value of this variable is typically handled by - \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains link flags when building console programs. The value + of this variable is typically handled by \l{qmake Manual#qmake}{\c qmake} + or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 QMAKE_LFLAGS_CONSOLE_DLL \e {This is used on Windows only.} - This variable contains link flags when building console - dlls. The value of this variable is typically handled by - \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains link flags when building console dlls. The value of + this variable is typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 QMAKE_LFLAGS_DEBUG - This variable contains link flags when building debuggable applications. The - value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains link flags when building debuggable applications. + The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \section1 QMAKE_LFLAGS_PLUGIN - This variable contains link flags when building plugins. The value - of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains link flags when building plugins. The value of this + variable is typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 QMAKE_LFLAGS_RPATH @@ -2463,122 +2520,125 @@ \section1 QMAKE_LFLAGS_QT_DLL - This variable contains link flags when building programs that - use the Qt library built as a dll. The value of this variable is - typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains link flags when building programs that use the Qt + library built as a dll. The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \section1 QMAKE_LFLAGS_RELEASE - This variable contains link flags when building applications for - release. The value of this variable is typically handled by - \l {qmake}{ \c qmake}or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains link flags when building applications for release. + The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \section1 QMAKE_LFLAGS_SHAPP - This variable contains link flags when building applications which are using - the \c app template. The value of this variable is typically handled by - \l {qmake}{ \c qmake}or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains link flags when building applications which are + using the \c app template. The value of this variable is typically + handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 QMAKE_LFLAGS_SHLIB This variable contains link flags when building shared libraries - The value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \section1 QMAKE_LFLAGS_SONAME This variable specifies the link flags to set the name of shared objects, - such as .so or .dll. The value of this variable is typically handled by \c - qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + such as .so or .dll. The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \section1 QMAKE_LFLAGS_THREAD This variable contains link flags when building multi-threaded projects. - The value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \section1 QMAKE_LFLAGS_WINDOWS \e {This is used on Windows only.} - This variable contains link flags when building Windows GUI projects - (i.e. non-console applications). - The value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains link flags when building Windows GUI projects (i.e. + non-console applications). The value of this variable is typically handled + by \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \section1 QMAKE_LFLAGS_WINDOWS_DLL \e {This is used on Windows only.} - This variable contains link flags when building Windows DLL projects. - The value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains link flags when building Windows DLL projects. The + value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \section1 QMAKE_LIBDIR - This variable contains the location of all known library - directories.The value of this variable is typically handled by - \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains the location of all known library directories. The + value of this variable is typically handled by \l{qmake Manual#qmake}{\c qmake} + or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 QMAKE_LIBDIR_FLAGS \e {This is used on Unix platforms only.} - This variable contains the location of all library - directory with -L prefixed. The value of this variable is typically handled by - \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains the location of all library directory with -L + prefixed. The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \section1 QMAKE_LIBDIR_EGL - This variable contains the location of the EGL library - directory, when EGL is used with OpenGL/ES or OpenVG. The value - of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains the location of the EGL library directory, when EGL + is used with OpenGL/ES or OpenVG. The value of this variable is typically + handled by \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} + and rarely needs to be modified. \section1 QMAKE_LIBDIR_OPENGL - This variable contains the location of the OpenGL library - directory.The value of this variable is typically handled by - \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains the location of the OpenGL library directory. The + value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. If the OpenGL implementation uses EGL (most OpenGL/ES systems), then QMAKE_LIBDIR_EGL may also need to be set. \section1 QMAKE_LIBDIR_OPENVG - This variable contains the location of the OpenVG library - directory. The value of this variable is typically handled by - \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains the location of the OpenVG library directory. The + value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. If the OpenVG implementation uses EGL, then QMAKE_LIBDIR_EGL may also need to be set. \section1 QMAKE_LIBDIR_QT - This variable contains the location of the Qt library - directory.The value of this variable is typically handled by - \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains the location of the Qt library directory. The value + of this variable is typically handled by \l{qmake Manual#qmake}{\c qmake} + or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 QMAKE_LIBDIR_X11 \e {This is used on Unix platforms only.} - This variable contains the location of the X11 library - directory.The value of this variable is typically handled by - \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains the location of the X11 library directory. The value + of this variable is typically handled by \l{qmake Manual#qmake}{\c qmake} + or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 QMAKE_LIBS - This variable contains all project libraries. The value of this - variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains all project libraries. The value of this variable + is typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 QMAKE_LIBS_CONSOLE @@ -2591,42 +2651,44 @@ \section1 QMAKE_LIBS_EGL - This variable contains all EGL libraries when building Qt with - OpenGL/ES or OpenVG. The value of this variable is typically - handled by \l {qmake}{ \c qmake}or \l{#QMAKESPEC}{qmake.conf} and rarely + This variable contains all EGL libraries when building Qt with OpenGL/ES + or OpenVG. The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. The usual value is \c{-lEGL}. \section1 QMAKE_LIBS_OPENGL - This variable contains all OpenGL libraries. The value of this - variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains all OpenGL libraries. The value of this variable + is typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. If the OpenGL implementation uses EGL (most OpenGL/ES systems), then QMAKE_LIBS_EGL may also need to be set. \section1 QMAKE_LIBS_OPENGL_QT - This variable contains all OpenGL Qt libraries.The value of this - variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains all OpenGL Qt libraries.The value of this variable + is typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 QMAKE_LIBS_OPENGL_ES1, QMAKE_LIBS_OPENGL_ES2 These variables contain all the OpenGL libraries for OpenGL ES 1 and OpenGL ES 2. - The value of these variables is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + The value of these variables is typically handled by + \l{qmake Manual#qmake}{\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 - variable is typically handled by \l {qmake}{ \c qmake}or \l{#QMAKESPEC}{qmake.conf} - and rarely needs to be modified. The usual value is \c{-lOpenVG}. + This variable contains all OpenVG libraries. The value of this variable + is typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. The usual + value is \c{-lOpenVG}. Some OpenVG engines are implemented on top of OpenGL. This will be detected at configure time and QMAKE_LIBS_OPENGL will be implicitly @@ -2637,95 +2699,96 @@ \section1 QMAKE_LIBS_QT - This variable contains all Qt libraries.The value of this - variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains all Qt libraries.The value of this variable is + typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 QMAKE_LIBS_QT_DLL \e {This is used on Windows only.} - This variable contains all Qt libraries when Qt is built as a dll. The - value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains all Qt libraries when Qt is built as a dll. The + value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \section1 QMAKE_LIBS_QT_OPENGL - This variable contains all the libraries needed to link against if - OpenGL support is turned on. The - value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains all the libraries needed to link against if OpenGL + support is turned on. The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \section1 QMAKE_LIBS_QT_THREAD - This variable contains all the libraries needed to link against if - thread support is turned on. The - value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains all the libraries needed to link against if thread + support is turned on. The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \section1 QMAKE_LIBS_RT \e {This is used with Borland compilers only.} This variable contains the runtime library needed to link against when - building an application. The - value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + building an application. The value of this variable is typically handled + by \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and + rarely needs to be modified. \section1 QMAKE_LIBS_RTMT \e {This is used with Borland compilers only.} This variable contains the runtime library needed to link against when - building a multi-threaded application. The - value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + building a multi-threaded application. The value of this variable is + typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 QMAKE_LIBS_THREAD \e {This is used on Unix and Symbian platforms only.} - This variable contains all libraries that need to be linked against - when building a multi-threaded application. The - value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains all libraries that need to be linked against when + building a multi-threaded application. The value of this variable is + typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 QMAKE_LIBS_WINDOWS \e {This is used on Windows only.} - This variable contains all windows libraries.The value of this - variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains all windows libraries. The value of this variable + is typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 QMAKE_LIBS_X11 \e {This is used on Unix platforms only.} - This variable contains all X11 libraries.The value of this - variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains all X11 libraries.The value of this variable is + typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 QMAKE_LIBS_X11SM \e {This is used on Unix platforms only.} - This variable contains all X11 session management libraries. The - value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains all X11 session management libraries. The value of + this variable is typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 QMAKE_LIB_FLAG - This variable is not empty if the \c lib template is specified. The - value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable is not empty if the \c lib template is specified. The value + of this variable is typically handled by \l{qmake Manual#qmake}{\c qmake} + or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 QMAKE_LINK_SHLIB_CMD - This variable contains the command to execute when creating a - shared library. The - value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains the command to execute when creating a shared + library. The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \section1 QMAKE_LN_SHLIB @@ -2754,8 +2817,8 @@ This variable determines the name of the project when generating project files for IDEs. The default value is the target name. The value of this - variable is typically handled by \l {qmake}{ \c qmake} and rarely needs - to be modified. + variable is typically handled by \l {qmake Manual#qmake}{ \c qmake} and + rarely needs to be modified. \section1 QMAKE_MAC_SDK @@ -2774,28 +2837,29 @@ \section1 QMAKE_MAKEFILE - This variable contains the name of the Makefile to create. The - value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains the name of the Makefile to create. The value of + this variable is typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 QMAKE_MOC_SRC - This variable contains the names of all moc source files to - generate and include in the project. The value of this variable is - typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains the names of all moc source files to generate and + include in the project. The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \section1 QMAKE_QMAKE - This variable contains the location of qmake if it is not in the path. - The value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains the location of qmake if it is not in the path. The + value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \section1 QMAKE_QT_DLL - This variable is not empty if Qt was built as a dll. The - value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable is not empty if Qt was built as a dll. The value of this + variable is typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 QMAKE_RESOURCE_FLAGS @@ -2805,7 +2869,7 @@ \c{-compress} options are used with particular values each time that \c rcc is invoked: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 45 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 45 \section1 QMAKE_RPATH @@ -2823,44 +2887,49 @@ \section1 QMAKE_RUN_CC - This variable specifies the individual rule needed to build an object. - The value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable specifies the individual rule needed to build an object. The + value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \section1 QMAKE_RUN_CC_IMP - This variable specifies the individual rule needed to build an object. - The value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable specifies the individual rule needed to build an object. The + value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \section1 QMAKE_RUN_CXX - This variable specifies the individual rule needed to build an object. - The value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable specifies the individual rule needed to build an object. The + value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \section1 QMAKE_RUN_CXX_IMP - This variable specifies the individual rule needed to build an object. - The value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable specifies the individual rule needed to build an object. The + value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \section1 QMAKE_TARGET - This variable contains the name of the project target. The value of - this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains the name of the project target. The value of this + variable is typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 QMAKE_UIC - This variable contains the location of uic if it is not in the path. - The value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains the location of uic if it is not in the path. The + value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. It can be used to specify arguments to uic as well, such as additional plugin paths. For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 46 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 46 \section1 QT @@ -2891,7 +2960,7 @@ exclude the \c gui value with the "-=" operator; the following line will result in a minimal Qt project being built: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 47 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 47 Note that adding the \c opengl option to the \c QT variable automatically causes the equivalent option to be added to the \c CONFIG variable. @@ -2927,8 +2996,9 @@ \section1 RC_FILE This variable contains the name of the resource file for the application. - The value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target RCC_DIR \section1 RCC_DIR @@ -2938,13 +3008,13 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 48 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 48 \target REQUIRES \section1 REQUIRES - This is a special variable processed by \c qmake. If the - contents of this variable do not appear in CONFIG by the time this + This is a special variable processed by \l{qmake Manual#qmake}{\c qmake}. + If the contents of this variable do not appear in CONFIG by the time this variable is assigned, then a minimal Makefile will be generated that states what dependencies (the values assigned to REQUIRES) are missing. @@ -2953,27 +3023,28 @@ \section1 RESOURCES - This variable contains the name of the resource collection file (qrc) + This variable contains the name of the resource collection file (qrc) for the application. Further information about the resource collection file can be found at \l{The Qt Resource System}. \section1 RES_FILE This variable contains the name of the resource file for the application. - The value of this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target RSS_RULES \section1 RSS_RULES - \e {This is only used on the Symbian platform.} + \e {This is only used on the Symbian platform.} - Generic RSS file content can be specified with this variable. The syntax is + Generic RSS file content can be specified with this variable. The syntax is similar to \c MMP_RULES and \c BLD_INF_RULES. For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 144 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 144 This will add the specified statement to the end of the \c APP_REGISTRATION_INFO resource struct in the generated registration resource file. @@ -2982,9 +3053,9 @@ It is also possible to add multiple rows in a single block. Each double quoted string will be placed on a new row in the registration resource file. - For example: + For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 145 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 145 This example will install the application to MyFolder in the Symbian platform application shell. In addition it will make the application to @@ -3016,7 +3087,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 151 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 151 This example will define service information for a fictional service that requires an icon to be supplied via the \c opaque_data of the service information. @@ -3045,17 +3116,17 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 49 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 49 See also \l{#HEADERS}{HEADERS} \section1 SRCMOC - This variable is set by \l {qmake}{ \c qmake}if files can be found that - contain the Q_OBJECT macro. \c SRCMOC contains the - name of all the generated moc files. The value of this variable - is typically handled by \l {qmake}{ \c qmake}or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be - modified. + This variable is set by \l{qmake Manual#qmake}{\c qmake} if files can be + found that contain the Q_OBJECT macro. \c SRCMOC contains the name of all + the generated moc files. The value of this variable is typically handled + by \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and + rarely needs to be modified. \target SUBDIRS \section1 SUBDIRS @@ -3067,18 +3138,18 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 50 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 50 It is essential that the project file in each subdirectory has the same - name as the subdirectory itself, so that \l {qmake}{ \c qmake}can find it. - For example, if the subdirectory is called \c myapp then the project file - in that directory should be called \c myapp.pro. + name as the subdirectory itself, so that \l{qmake Manual#qmake}{\c qmake} + can find it. For example, if the subdirectory is called \c myapp then the + project file in that directory should be called \c myapp.pro. If you need to ensure that the subdirectories are built in the order in which they are specified, update the \l{#CONFIG}{CONFIG} variable to include the \c ordered option: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 51 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 51 It is possible to modify this default behavior of \c SUBDIRS by giving additional modifiers to \c SUBDIRS elements. Supported modifiers are: @@ -3102,11 +3173,11 @@ For example, define two subdirectories, both of which reside in a different directory than the \c SUBDIRS value, and one of the subdirectories must be built before the other: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 149 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 149 For example, define a subdirectory that is only build for emulator builds in Qt for Symbian: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 150 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 150 \target SYMBIAN_VERSION \section1 SYMBIAN_VERSION @@ -3122,7 +3193,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 52 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 52 The project file above would produce an executable named \c myapp on unix and 'myapp.exe' on windows. @@ -3132,8 +3203,34 @@ \e {This is only used on the Symbian platform.} - Specifies which platform capabilities the application should have. For more - information, please refer to the Symbian SDK documentation. + Specifies which platform capabilities the application should have. These + include the following basic capabilities, but others are also available + for signed applications. + + \table + \header \o Capability \o Description + \row \o LocalServices \o The ability to use local services running on the + phone or device, including those which provide + local connectivity to other devices. + \row \o Location \o Access to the service that provides information + about the user's location, from GPS, phone + network, or other sources. + \row \o NetworkServices \o Use of services that access the phone network, + such as dialling a phone number, sending an SMS, + or other operations that result in network + traffic. + \row \o ReadUserData \o Access to the user's private data, such as + contact information. + \row \o UserEnvironment \o The ability to use services that provide from the + user's physical environment, such as the camera or + microphone. + \row \o WriteUserData \o The ability to write or modify the user's private + data. + \endtable + + For more information, and a comprehensive list of capabilities, please refer + to the Symbian SDK documentation or the \l{Symbian Capabilities} page of + the \l{Forum Nokia Wiki}. \target TARGET.EPOCALLOWDLLDATA \section1 TARGET.EPOCALLOWDLLDATA @@ -3152,7 +3249,7 @@ will refuse to run if the minimum size is not available when it starts. For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 135 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 135 \target TARGET.EPOCSTACKSIZE \section1 TARGET.EPOCSTACKSIZE @@ -3161,7 +3258,7 @@ Specifies the maximum stack size of the application. For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 136 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 136 \target TARGET.SID \section1 TARGET.SID @@ -3201,21 +3298,23 @@ \section1 TARGET_EXT - This variable specifies the target's extension. The value of this variable - is typically handled by \l {qmake}{ \c qmake}or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be - modified. + This variable specifies the target's extension. The value of this variable + is typically handled by \l {qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 TARGET_x - This variable specifies the target's extension with a major version number. The value of this variable - is typically handled by \l {qmake}{ \c qmake}or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be - modified. + This variable specifies the target's extension with a major version number. + The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \section1 TARGET_x.y.z - This variable specifies the target's extension with version number. The value of this variable - is typically handled by \l {qmake}{ \c qmake}or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be - modified. + This variable specifies the target's extension with version number. The + value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \target TEMPLATE \section1 TEMPLATE @@ -3242,7 +3341,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 53 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 53 The template can be overridden by specifying a new template type with the \c -t command line option. This overrides the template type \e after the .pro @@ -3261,16 +3360,16 @@ \section1 UICIMPLS This variable contains a list of the generated implementation files by UIC. - The value of this variable - is typically handled by \l {qmake}{ \c qmake}or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be - modified. + The value of this variable is typically handled by + \l{qmake Manual#qmake}{\c qmake} or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. \section1 UICOBJECTS - This variable is generated from the UICIMPLS variable. The extension of each - file will have been replaced by .o (Unix) or .obj (Win32). The value of this variable is - typically handled by \l {qmake}{ \c qmake}or \l{#QMAKESPEC}{qmake.conf} and - rarely needs to be modified. + This variable is generated from the UICIMPLS variable. The extension of + each file will have been replaced by .o (Unix) or .obj (Win32). The value + of this variable is typically handled by \l{qmake Manual#qmake}{\c qmake} + or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \target UI_DIR \section1 UI_DIR @@ -3281,7 +3380,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 54 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 54 \target UI_HEADERS_DIR \section1 UI_HEADERS_DIR @@ -3291,7 +3390,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 55 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 55 \target UI_SOURCES_DIR \section1 UI_SOURCES_DIR @@ -3301,7 +3400,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 56 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 56 \target VERSION \section1 VERSION @@ -3312,7 +3411,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 57 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 57 \section1 VER_MAJ @@ -3331,36 +3430,36 @@ \section1 VPATH - This variable tells \l {qmake}{ \c qmake}where to search for files it cannot - open. With this you may tell \l {qmake}{ \c qmake}where it may look for things - like SOURCES, and if it finds an entry in SOURCES that cannot be - opened it will look through the entire VPATH list to see if it can - find the file on its own. + This variable tells \l{qmake Manual#qmake}{\c qmake} where to search for + files it cannot open. With this you may tell + \l{qmake Manual#qmake}{\c qmake} where it may look for things like SOURCES, + and if it finds an entry in SOURCES that cannot be opened it will look + through the entire VPATH list to see if it can find the file on its own. See also \l{#DEPENDPATH}{DEPENDPATH}. \section1 YACCIMPLS - This variable contains a list of yacc source files. The value of - this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains a list of yacc source files. The value of this + variable is typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 YACCOBJECTS - This variable contains a list of yacc object files. The value of - this variable is typically handled by \l {qmake}{ \c qmake}or - \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + This variable contains a list of yacc object files. The value of this + variable is typically handled by \l{qmake Manual#qmake}{\c qmake} or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \target YACCSOURCES \section1 YACCSOURCES This variable contains a list of yacc source files to be included - in the project. All dependencies, headers and source files will + in the project. All dependencies, headers and source files will automatically be included in the project. For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 58 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 58 \section1 _PRO_FILE_ @@ -3389,8 +3488,8 @@ \previouspage qmake Variable Reference \nextpage Configuring qmake's Environment - \l {qmake}{ \c qmake}provides built-in functions to allow the contents of - variables to be processed, and to enable tests to be performed + \l{qmake Manual#qmake}{\c qmake} provides built-in functions to allow the + contents of variables to be processed, and to enable tests to be performed during the configuration process. Functions that process the contents of variables typically return values that can be assigned to other variables, and these values are obtained by prefixing @@ -3417,7 +3516,7 @@ Returns the basename of the file specified. For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 59 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 59 \section1 CONFIG(config) [Conditional] @@ -3430,7 +3529,7 @@ mutually exclusive values) a second parameter can be used to specify a set of values to consider. For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 60 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 60 Because release is considered the active setting (for feature parsing) it will be the CONFIG used to generate the build file. In the common @@ -3446,7 +3545,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 61 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 61 The contents of the scope are only processed if the \c drivers variable contains the value, \c network. If this is the case, the @@ -3473,19 +3572,19 @@ \section1 error(string) - This function never returns a value. \l {qmake}{ \c qmake}displays the given - \e string to the user, and exits. This function should only be used - for unrecoverable errors. + This function never returns a value. \l{qmake Manual#qmake}{\c qmake} + displays the given \e string to the user, and exits. This function + should only be used for unrecoverable errors. For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 62 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 62 \section1 eval(string) [Conditional] - Evaluates the contents of the string using \c qmake's syntax rules - and returns true. + Evaluates the contents of the string using + \l{qmake Manual#qmake}{\c qmake}'s syntax rules and returns true. Definitions and assignments can be used in the string to modify the values of existing variables or create new definitions. @@ -3504,7 +3603,7 @@ succeeds if any file matches the regular expression specified. For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 63 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 63 Note that "/" can be used as a directory separator, regardless of the platform in use. @@ -3514,7 +3613,7 @@ Places all the values in \e variablename that match \e substr. \e substr may be a regular expression, and will be matched accordingly. - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 64 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 64 MY_VAR2 will contain '-Lone -Ltwo -Lthree -Lfour -Lfive', and MY_VAR3 will contains 'three two three'. @@ -3531,7 +3630,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 65 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 65 \section1 include(filename) [Conditional] @@ -3544,15 +3643,16 @@ You can check whether the file was included by using this function as the condition for a scope; for example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 66 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 66 \section1 infile(filename, var, val) [Conditional] - Succeeds if the file \e filename (when parsed by \l {qmake}{ \c qmake}itself) - contains the variable \e var with a value of \e val; otherwise fails. - If you do not specify a third argument (\e val), the function will - only test whether \e var has been declared in the file. + Succeeds if the file \e filename (when parsed by + \l{qmake Manual#qmake}{\c qmake} itself) contains the variable \e var with + a value of \e val; otherwise fails. If you do not specify a third argument + (\e val), the function will only test whether \e var has been declared in + the file. \section1 isEmpty(variablename) [Conditional] @@ -3562,7 +3662,7 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 67 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 67 \section1 join(variablename, glue, before, after) @@ -3586,7 +3686,7 @@ This function simply writes a message to the console. Unlike the \c error() function, this function allows processing to continue. - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 68 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 68 The above line causes "This is a message" to be written to the console. The use of quotation marks is optional. @@ -3597,7 +3697,7 @@ \l{qmake Advanced Usage}{in conjunction with a scope} to filter out messages during builds; for example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 69 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 69 \section1 prompt(question) @@ -3618,7 +3718,7 @@ prints the message: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 70 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 70 \section1 sprintf(string, arguments...) @@ -3634,13 +3734,13 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 71 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 71 Alternatively, you can use this function to obtain stdout and stderr from the command, and assign it to a variable. For example, you can use this to interrogate information about the platform: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 72 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 72 \target unique \section1 unique(variablename) @@ -3648,7 +3748,7 @@ This will return a list of values in variable that are unique (that is with repetitive entries removed). For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 73 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 73 \section1 warning(string) @@ -3668,18 +3768,19 @@ \target Properties \section1 Properties - \l {qmake}{ \c qmake}has a system of persistent information, this allows you to - \c set a variable in qmake once, and each time qmake is invoked this - value can be queried. Use the following to set a property in qmake: + \l{qmake Manual#qmake}{\c qmake} has a system of persistent information, + this allows you to \c set a variable in qmake once, and each time qmake is + invoked this value can be queried. Use the following to set a property in + qmake: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 74 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 74 The appropriate variable and value should be substituted for \c VARIABLE and \c VALUE. To retrieve this information back from qmake you can do: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 75 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 75 \note \c{qmake -query} will only list variables that you have previously set with \c{qmake -set VARIABLE VALUE}. @@ -3687,24 +3788,26 @@ This information will be saved into a QSettings object (meaning it will be stored in different places for different platforms). As \c VARIABLE is versioned as well, you can set one value in an older - version of \c qmake, and newer versions will retrieve this value. However, - if you set \c VARIABLE for a newer version of \c qmake, the older version - will not use this value. You can however query a specific version of a - variable if you prefix that version of \l {qmake}{ \c qmake}to \c VARIABLE, as in - the following example: + version of \l{qmake Manual#qmake}{\c qmake}, and newer versions will + retrieve this value. However, if you set \c VARIABLE for a newer version + of \l{qmake Manual#qmake}{\c qmake}, the older version will not use this + value. You can however query a specific version of a variable if you + prefix that version of \l{qmake Manual#qmake}{\c qmake} to \c VARIABLE, + as in the following example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 76 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 76 - \l {qmake}{ \c qmake}also has the notion of \c builtin properties, for example you can - query the installation of Qt for this version of \l {qmake}{ \c qmake}with the + \l{qmake Manual#qmake}{\c qmake} also has the notion of \c builtin + properties, for example you can query the installation of Qt for this + version of \l{qmake Manual#qmake}{\c qmake} with the \c QT_INSTALL_PREFIX property: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 77 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 77 - These built-in properties cannot have a version prefixed to them as - they are not versioned, and each version of \l {qmake}{ \c qmake}will have its own - built-in set of these values. The list below outlines the built-in - properties: + These built-in properties cannot have a version prefixed to them as they + are not versioned, and each version of \l{qmake Manual#qmake}{\c qmake} + will have its own built-in set of these values. The list below outlines + the built-in properties: \list \o \c QT_INSTALL_PREFIX - Where the version of Qt this qmake is built for resides @@ -3715,27 +3818,27 @@ Finally, these values can be queried in a project file with a special notation such as: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 78 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 78 \target QMAKESPEC \section1 QMAKESPEC - \l {qmake}{ \c qmake}requires a platform and compiler description file which - contains many default values used to generate appropriate Makefiles. - The standard Qt distribution comes with many of these files, located - in the \c mkspecs subdirectory of the Qt installation. + \l{qmake Manual#qmake}{\c qmake}requires a platform and compiler + description file which contains many default values used to generate + appropriate Makefiles. The standard Qt distribution comes with many of + these files, located in the \c mkspecs subdirectory of the Qt installation. The \c QMAKESPEC environment variable can contain any of the following: \list \o A complete path to a directory containing a \c{qmake.conf} file. - In this case \l {qmake}{ \c qmake}will open the \c{qmake.conf} file from within that - directory. If the file does not exist, \l {qmake}{ \c qmake}will exit with an - error. - \o The name of a platform-compiler combination. In this case, \c qmake - will search in the directory specified by the \c mkspecs subdirectory - of the data path specified when Qt was compiled (see - QLibraryInfo::DataPath). + In this case \l{qmake Manual#qmake}{\c qmake} will open the + \c{qmake.conf} file from within that directory. If the file does not + exist, \l{qmake Manual#qmake}{\c qmake} will exit with an error. + \o The name of a platform-compiler combination. In this case, + \l{qmake Manual#qmake}{\c qmake} will search in the directory specified + by the \c mkspecs subdirectory of the data path specified when Qt was + compiled (see QLibraryInfo::DataPath). \endlist \bold{Note:} The \c QMAKESPEC path will automatically be added to the @@ -3746,31 +3849,32 @@ It is common on Unix to also use the build tool to install applications and libraries; for example, by invoking \c{make install}. For this reason, - \l {qmake}{ \c qmake}has the concept of an install set, an object which contains - instructions about the way part of a project is to be installed. - For example, a collection of documentation files can be described in the - following way: + \l{qmake Manual#qmake}{\c qmake}has the concept of an install set, an + object which contains instructions about the way part of a project is to + be installed. For example, a collection of documentation files can be + described in the following way: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 79 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 79 - The \c path member informs \l {qmake}{ \c qmake}that the files should be installed in - \c /usr/local/program/doc (the path member), and the \c files member - specifies the files that should be copied to the installation directory. - In this case, everything in the \c docs directory will be coped to - \c /usr/local/program/doc. + The \c path member informs \l{qmake Manual#qmake}{\c qmake} that the files + should be installed in \c /usr/local/program/doc (the path member), and the + \c files member specifies the files that should be copied to the + installation directory. In this case, everything in the \c docs directory + will be coped to \c /usr/local/program/doc. Once an install set has been fully described, you can append it to the install list with a line like this: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 80 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 80 - \l {qmake}{ \c qmake}will ensure that the specified files are copied to the installation - directory. If you require greater control over this process, you can also - provide a definition for the \c extra member of the object. For example, - the following line tells \l {qmake}{ \c qmake}to execute a series of commands for this + \l{qmake Manual#qmake}{\c qmake} will ensure that the specified files are + copied to the installation directory. If you require greater control over + this process, you can also provide a definition for the \c extra member of + the object. For example, the following line tells + \l{qmake Manual#qmake}{\c qmake} to execute a series of commands for this install set: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 81 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 81 The \c unix scope (see \l{qmake Advanced Usage#Scopes and Conditions}{Scopes and Conditions}) @@ -3782,23 +3886,24 @@ in the other members of the object are performed. If you append a built-in install set to the \c INSTALLS variable and do - not specify \c files or \c extra members, \l {qmake}{ \c qmake}will decide what needs to - be copied for you. Currently, the only supported built-in install set is - \c target: + not specify \c files or \c extra members, \l{qmake Manual#qmake}{\c qmake} + will decide what needs to be copied for you. Currently, the only supported + built-in install set is \c target: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 82 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 82 - In the above lines, \l {qmake}{ \c qmake}knows what needs to be copied, and will handle - the installation process automatically. + In the above lines, \l{qmake Manual#qmake}{\c qmake} knows what needs to + be copied, and will handle the installation process automatically. \target cache \section1 Cache File - The cache file is a special file \l {qmake}{ \c qmake}reads to find settings not specified - in the \c qmake.conf file, project files, or at the command line. If - \c -nocache is not specified when \l {qmake}{ \c qmake}is run, it will try to find a file - called \c{.qmake.cache} in parent directories of the current directory. If - it fails to find this file, it will silently ignore this step of processing. + The cache file is a special file \l{qmake Manual#qmake}{\c qmake} reads to + find settings not specified in the \c qmake.conf file, project files, or + at the command line. If \c -nocache is not specified when + \l{qmake Manual#qmake}{\c qmake} is run, it will try to find a file called + \c{.qmake.cache} in parent directories of the current directory. If it + fails to find this file, it will silently ignore this step of processing. If it finds a \c{.qmake.cache} file then it will process this file first before it processes the project file. @@ -3806,67 +3911,73 @@ \target LibDepend \section1 Library Dependencies - Often when linking against a library, \l {qmake}{ \c qmake}relies on the underlying - platform to know what other libraries this library links against, and - lets the platform pull them in. In many cases, however, this is not - sufficent. For example, when statically linking a library, no other - libraries are linked to, and therefore no dependencies to those - libraries are created. However, an application that later links + Often when linking against a library, \l{qmake Manual#qmake}{\c qmake} + relies on the underlying platform to know what other libraries this + library links against, and lets the platform pull them in. In many cases, + however, this is not sufficent. For example, when statically linking a + library, no other libraries are linked to, and therefore no dependencies + to those libraries are created. However, an application that later links against this library will need to know where to find the symbols that - the static library will require. To help with this situation, \c qmake - attempts to follow a library's dependencies where appropriate, but - this behavior must be explicitly enabled by following two steps. + the static library will require. To help with this situation, + \l{qmake Manual#qmake}{\c qmake} attempts to follow a library's + dependencies where appropriate, but this behavior must be explicitly + enabled by following two steps. The first step is to enable dependency tracking in the library itself. - To do this you must tell \l {qmake}{ \c qmake}to save information about the library: + To do this you must tell \l{qmake Manual#qmake}{\c qmake} to save + information about the library: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 83 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 83 - This is only relevant to the \c lib template, and will be ignored for - all others. When this option is enabled, \l {qmake}{ \c qmake}will create a file - ending in .prl which will save some meta-information about the - library. This metafile is just like an ordinary project file, but only + This is only relevant to the \c lib template, and will be ignored for all + others. When this option is enabled, \l{qmake Manual#qmake}{\c qmake} will + create a file ending in .prl which will save some meta-information about + the library. This metafile is just like an ordinary project file, but only contains internal variable declarations. You are free to view this file - and, if it is deleted, \l {qmake}{ \c qmake}will know to recreate it when necessary, - either when the project file is later read, or if a dependent library - (described below) has changed. When installing this library, by - specifying it as a target in an \c INSTALLS declaration, \l {qmake}{ \c qmake}will - automatically copy the .prl file to the installation path. + and, if it is deleted, \l{qmake Manual#qmake}{\c qmake} will know to + recreate it when necessary, either when the project file is later read, or + if a dependent library (described below) has changed. When installing this + library, by specifying it as a target in an \c INSTALLS declaration, + \l{qmake Manual#qmake}{\c qmake} will automatically copy the .prl file to + the installation path. The second step in this process is to enable reading of this meta information in the applications that use the static library: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 84 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 84 - When this is enabled, \l {qmake}{ \c qmake}will process all libraries linked to - by the application and find their meta-information. \l {qmake}{ \c qmake}will use - this to determine the relevant linking information, specifically adding - values to the application project file's list of \c DEFINES as well as - \c LIBS. Once \l {qmake}{ \c qmake}has processed this file, it will then look through - the newly introduced libraries in the \c LIBS variable, and find their - dependent .prl files, continuing until all libraries have been resolved. - At this point, the Makefile is created as usual, and the libraries are - linked explicitly against the application. + When this is enabled, \l{qmake Manual#qmake}{\c qmake} will process all + libraries linked to by the application and find their meta-information. + \l{qmake Manual#qmake}{\c qmake} will use this to determine the relevant + linking information, specifically adding values to the application project + file's list of \c DEFINES as well as \c LIBS. Once + \l{qmake Manual#qmake}{\c qmake} has processed this file, it will then + look through the newly introduced libraries in the \c LIBS variable, and + find their dependent .prl files, continuing until all libraries have been + resolved. At this point, the Makefile is created as usual, and the + libraries are linked explicitly against the application. The internals of the .prl file are left closed so they can easily change later. They are not designed to be changed by hand, should only - be created by \c qmake, and should not be transferred between operating - systems as they may contain platform-dependent information. + be created by \{qmake Manual#qmake}{\c qmake}, and should not be + transferred between operating systems as they may contain + platform-dependent information. \target Extensions \section1 File Extensions - Under normal circumstances \l {qmake}{ \c qmake}will try to use appropriate file extensions - for your platform. However, it is sometimes necessary to override the default - choices for each platform and explicitly define file extensions for \l {qmake}{ \c qmake}to use. - This is achieved by redefining certain built-in variables; for example the extension - used for \l moc files can be redefined with the following assignment in a project - file: + Under normal circumstances \l{qmake Manual#qmake}{\c qmake} will try to + use appropriate file extensions for your platform. However, it is + sometimes necessary to override the default choices for each platform and + explicitly define file extensions for \l{qmake Manual#qmake}{\c qmake} to + use. This is achieved by redefining certain built-in variables; for + example the extension used for \l moc files can be redefined with the + following assignment in a project file: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 85 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 85 The following variables can be used to redefine common file extensions recognized - by \c qmake: + by \l{qmake Manual#qmake}{\c qmake}: \list \o QMAKE_EXT_MOC - This modifies the extension placed on included moc files. @@ -3884,45 +3995,47 @@ accept a list of values: \list - \o QMAKE_EXT_CPP - Causes \l {qmake}{ \c qmake}to interpret all files with these suffixes as - C++ source files. - \o QMAKE_EXT_H - Causes \l {qmake}{ \c qmake}to interpret all files with these suffixes as - C and C++ header files. + \o QMAKE_EXT_CPP - Causes \l{qmake Manual#qmake}{\c qmake} to interpret + all files with these suffixes as C++ source files. + \o QMAKE_EXT_H - Causes \l qmake Manual#{qmake}{\c qmake} to interpret + all files with these suffixes as C and C++ header files. \endlist \target Customizing \section1 Customizing Makefile Output - \l {qmake}{ \c qmake}tries to do everything expected of a cross-platform build tool. - This is often less than ideal when you really need to run special - platform-dependent commands. This can be achieved with specific instructions - to the different \l {qmake}{ \c qmake}backends. + \l{qmake Manual#qmake}{\c qmake} tries to do everything expected of a + cross-platform build tool. This is often less than ideal when you really + need to run special platform-dependent commands. This can be achieved with + specific instructions to the different \l{qmake Manual#qmake}{\c qmake} + backends. Customization of the Makefile output is performed through an object-style - API as found in other places in \c qmake. Objects are defined automatically - by specifying their members; for example: + API as found in other places in \l{qmake Manual#qmake}{\c qmake}. Objects + are defined automatically by specifying their members; for example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 86 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 86 - The definitions above define a \l {qmake}{ \c qmake}target called \c mytarget, containing - a Makefile target called \c{.buildfile} which in turn is generated with - the \c touch command. Finally, the \c{.depends} member specifies that - \c mytarget depends on \c mytarget2, another target that is defined afterwards. - \c mytarget2 is a dummy target; it is only defined to echo some text to - the console. + The definitions above define a \l{qmake Manual#qmake}{\c qmake} target + called \c mytarget, containing a Makefile target called \c{.buildfile} + which in turn is generated with the \c touch command. Finally, the + \c{.depends} member specifies that \c mytarget depends on \c mytarget2, + another target that is defined afterwards. \c mytarget2 is a dummy target; + it is only defined to echo some text to the console. - The final step is to instruct \l {qmake}{ \c qmake}that this object is a target to be built: + The final step is to instruct \l{qmake Manual#qmake}{\c qmake} that this + object is a target to be built: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 87 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 87 - This is all you need to do to actually build custom targets. Of course, you may - want to tie one of these targets to the - \l{qmake Variable Reference#TARGET}{qmake build target}. To do this, you simply need to - include your Makefile target in the list of + This is all you need to do to actually build custom targets. Of course, + you may want to tie one of these targets to the + \l{qmake Variable Reference#TARGET}{qmake build target}. To do this, you + simply need to include your Makefile target in the list of \l{qmake Variable Reference#PRE_TARGETDEPS}{PRE_TARGETDEPS}. - The following tables are an overview of the options available to you with the QMAKE_EXTRA_TARGETS - variable. + The following tables are an overview of the options available to you with + the QMAKE_EXTRA_TARGETS variable. \table \header @@ -3967,15 +4080,16 @@ For convenience, there is also a method of customizing projects for new compilers or preprocessors: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 88 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 88 With the above definitions, you can use a drop-in replacement for moc if one is available. The commands is executed on all arguments given to the \c NEW_HEADERS variable (from the \c input member), and the result is written to the file defined by the \c output member; this file is added to the other source files in the project. - Additionally, \l {qmake}{ \c qmake}will execute \c depend_command to generate dependency - information, and place this information in the project as well. + Additionally, \l{qmake Manual#qmake}{\c qmake} will execute + \c depend_command to generate dependency information, and place this + information in the project as well. These commands can easily be placed into a cache file, allowing subsequent project files to add arguments to \c NEW_HEADERS. @@ -4024,71 +4138,71 @@ \table \header - \o Member - \o Description - \row - \o commands - \o The commands used for for generating the output from the input. - \row - \o CONFIG - \o Specific configuration options for the custom compiler. See the CONFIG table for details. - \row - \o depend_command - \o Specifies a command used to generate the list of dependencies for the output. - \row - \o dependency_type - \o Specifies the type of file the output is, if it is a known type (such as TYPE_C, - TYPE_UI, TYPE_QRC) then it is handled as one of those type of files. - \row - \o depends - \o Specifies the dependencies of the output file. - \row - \o input - \o The variable that contains the files that should be processed with the custom compiler. - \row - \o name - \o A description of what the custom compiler is doing. This is only used in some backends. - \row - \o output - \o The filename that is created from the custom compiler. - \row - \o output_function - \o Specifies a custom qmake function that is used to specify the filename to be created. - \row - \o variables - \o Indicates that the variables specified here are replaced with $(QMAKE_COMP_VARNAME) when refered to - in the pro file as $(VARNAME). - \row - \o variable_out - \o The variable that the files created from the output should be added to. - \endtable - - List of members specific to the CONFIG option: - - \table - \header - \o Member - \o Description - \row - \o combine - \o Indicates that all of the input files are combined into a single output file. - \row - \o target_predeps - \o Indicates that the output should be added to the list of PRE_TARGETDEPS. - \row - \o explicit_dependencies - \o The dependencies for the output only get generated from the depends member and from - nowhere else. - \row - \o no_link - \o Indicates that the output should not be added to the list of objects to be linked in. - \endtable + \o Member + \o Description + \row + \o commands + \o The commands used for for generating the output from the input. + \row + \o CONFIG + \o Specific configuration options for the custom compiler. See the CONFIG table for details. + \row + \o depend_command + \o Specifies a command used to generate the list of dependencies for the output. + \row + \o dependency_type + \o Specifies the type of file the output is, if it is a known type (such as TYPE_C, + TYPE_UI, TYPE_QRC) then it is handled as one of those type of files. + \row + \o depends + \o Specifies the dependencies of the output file. + \row + \o input + \o The variable that contains the files that should be processed with the custom compiler. + \row + \o name + \o A description of what the custom compiler is doing. This is only used in some backends. + \row + \o output + \o The filename that is created from the custom compiler. + \row + \o output_function + \o Specifies a custom qmake function that is used to specify the filename to be created. + \row + \o variables + \o Indicates that the variables specified here are replaced with $(QMAKE_COMP_VARNAME) when refered to + in the pro file as $(VARNAME). + \row + \o variable_out + \o The variable that the files created from the output should be added to. + \endtable + + List of members specific to the CONFIG option: + + \table + \header + \o Member + \o Description + \row + \o combine + \o Indicates that all of the input files are combined into a single output file. + \row + \o target_predeps + \o Indicates that the output should be added to the list of PRE_TARGETDEPS. + \row + \o explicit_dependencies + \o The dependencies for the output only get generated from the depends member and from + nowhere else. + \row + \o no_link + \o Indicates that the output should not be added to the list of objects to be linked in. + \endtable \note Symbian platform specific: Generating objects to be linked in is not supported on the Symbian platform, so either the \c CONFIG option \c no_link or variable \c variable_out should always be defined for extra compilers. - + */ /*! @@ -4098,12 +4212,13 @@ \previouspage qmake Platform Notes \nextpage Using Precompiled Headers - Many \l {qmake}{ \c qmake}project files simply describe the sources and header files used - by the project, using a list of \c{name = value} and \c{name += value} - definitions. \l {qmake}{ \c qmake}also provides other operators, functions, and scopes - that can be used to process the information supplied in variable declarations. - These advanced features allow Makefiles to be generated for multiple platforms - from a single project file. + Many \l{qmake Manual#qmake}{\c qmake} project files simply describe the + sources and header files used by the project, using a list of + \c{name = value} and \c{name += value} definitions. + \l{qmake Manual#qmake}{\c qmake} also provides other operators, functions, + and scopes that can be used to process the information supplied in + variable declarations. These advanced features allow Makefiles to be + generated for multiple platforms from a single project file. \tableofcontents @@ -4112,28 +4227,29 @@ In many project files, the assignment (\c{=}) and append (\c{+=}) operators can be used to include all the information about a project. The typical pattern of use is to assign a list of values to a variable, and append more values - depending on the result of various tests. Since \l {qmake}{ \c qmake}defines certain - variables using default values, it is sometimes necessary to use the removal - (\c{-=}) operator to filter out values that are not required. The following - operators can be used to manipulate the contents of variables. + depending on the result of various tests. Since + \l{qmake Manual#qmake}{\c qmake} defines certain variables using default + values, it is sometimes necessary to use the removal (\c{-=}) operator to + filter out values that are not required. The following operators can be + used to manipulate the contents of variables. The \c = operator assigns a value to a variable: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 89 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 89 The above line sets the \c TARGET variable to \c myapp. This will overwrite any values previously set for \c TARGET with \c myapp. The \c += operator appends a new value to the list of values in a variable: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 90 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 90 The above line appends \c QT_DLL to the list of pre-processor defines to be put in the generated Makefile. The \c -= operator removes a value from the list of values in a variable: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 91 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 91 The above line removes \c QT_DLL from the list of pre-processor defines to be put in the generated Makefile. @@ -4142,7 +4258,7 @@ if it is not already present. This prevents values from being included many times in a variable. For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 92 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 92 In the above line, \c QT_DLL will only be added to the list of pre-processor defines if it is not already defined. Note that the @@ -4153,7 +4269,7 @@ The \c ~= operator replaces any values that match a regular expression with the specified value: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 93 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 93 In the above line, any values in the list that start with \c QT_D or \c QT_T are replaced with \c QT. @@ -4161,7 +4277,7 @@ The \c $$ operator is used to extract the contents of a variable, and can be used to pass values between variables or supply them to functions: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 94 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 94 \target Scopes \section1 Scopes @@ -4188,9 +4304,9 @@ \snippet doc/src/snippets/qmake/scopes.pro 0 The above code will add the \c paintwidget_win.cpp file to the sources listed - in the generated Makefile if \l {qmake}{ \c qmake}is used on a Windows platform. - If \l {qmake}{ \c qmake}is used on a platform other than Windows, the define will be - ignored. + in the generated Makefile if \l{qmake Manual#qmake}{\c qmake} is used on a + Windows platform. If \l{qmake Manual#qmake}{\c qmake} is used on a + platform other than Windows, the define will be ignored. The conditions used in a given scope can also be negated to provide an alternative set of declarations that will be processed only if the @@ -4215,17 +4331,17 @@ You may also use the \c : operator to perform single line conditional assignments; for example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 95 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 95 The above line adds \c QT_DLL to the \c DEFINES variable only on the Windows platform. Generally, the \c : operator behaves like a logical AND operator, joining together a number of conditions, and requiring all of them to be true. - There is also the \c | operator to act like a logical OR operator, joining - together a number of conditions, and requiring only one of them to be true. + There is also the \c | operator to act like a logical OR operator, joining + together a number of conditions, and requiring only one of them to be true. - \snippet doc/src/snippets/qmake/scopes.pro 4 + \snippet doc/src/snippets/qmake/scopes.pro 4 You can also provide alternative declarations to those within a scope by using an \c else scope. Each \c else scope is processed if the conditions @@ -4233,15 +4349,15 @@ This allows you to write complex tests when combined with other scopes (separated by the \c : operator as above). For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 96 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 96 \section2 Configuration and Scopes The values stored in the - \l{qmake-project-files.html#GeneralConfiguration}{\c CONFIG variable} - are treated specially by \c qmake. Each of the possible values can be - used as the condition for a scope. For example, the list of values - held by \c CONFIG can be extended with the \c opengl value: + \l{qmake-project-files.html#GeneralConfiguration}{\c CONFIG variable} are + treated specially by \l{qmake Manual#qmake}{\c qmake}. Each of the possible + values can be used as the condition for a scope. For example, the list of + values held by \c CONFIG can be extended with the \c opengl value: \snippet doc/src/snippets/qmake/configscopes.pro 0 @@ -4284,12 +4400,13 @@ \section1 Variables Many of the variables used in project files are special variables that - \l {qmake}{ \c qmake}uses when generating Makefiles, such as \c DEFINES, \c SOURCES, - and \c HEADERS. It is possible for you to create variables for your own - use; \l {qmake}{ \c qmake}creates new variables with a given name when it encounters - an assignment to that name. For example: + \l{qmake Manual#qmake}{\c qmake} uses when generating Makefiles, such as + \c DEFINES, \c SOURCES, and \c HEADERS. It is possible for you to create + variables for your own use; \l{qmake Manual#qmake}{\c qmake} creates new + variables with a given name when it encounters an assignment to that name. + For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 97 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 97 There are no restricitions on what you do to your own variables, as \c qmake will ignore them unless it needs to evaluate them when processing @@ -4298,26 +4415,27 @@ You can also assign the value of a current variable to another variable by prefixing $$ to the variable name. For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 98 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 98 Now the MY_DEFINES variable contains what is in the DEFINES variable at this point in the project file. This is also equivalent to: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 99 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 99 The second notation allows you to append the contents of the variable to another value without separating the two with a space. For example, the following will ensure that the final executable will be given a name that includes the project template being used: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 100 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 100 Variables can be used to store the contents of environment variables. - These can be evaluated at the time that \l {qmake}{ \c qmake}is run, or included - in the generated Makefile for evaluation when the project is built. + These can be evaluated at the time that \l{qmake Manual#qmake}{\c qmake} + is run, or included in the generated Makefile for evaluation when the + project is built. - To obtain the contents of an environment value when \l {qmake}{ \c qmake}is run, - use the \c $$(...) operator: + To obtain the contents of an environment value when + \l{qmake Manual#qmake}{\c qmake}is run, use the \c $$(...) operator: \snippet doc/src/snippets/qmake/environment.pro 0 @@ -4345,17 +4463,17 @@ For example, a \QD plugin can be installed alongside \QD's built-in plugins if the following declaration is made in its project file: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 101 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 101 \target VariableProcessingFunctions \section1 Variable Processing Functions - \l {qmake}{ \c qmake}provides a selection of built-in functions to allow the - contents of variables to be processed. These functions process the - arguments supplied to them and return a value, or list of values, as - a result. In order to assign a result to a variable, it is necessary - to use the \c $$ operator with this type of function in the same way - used to assign contents of one variable to another: + \l{qmake Manual#qmake}{\c qmake} provides a selection of built-in + functions to allow the contents of variables to be processed. These + functions process the arguments supplied to them and return a value, or + list of values, as a result. In order to assign a result to a variable, + it is necessary to use the \c $$ operator with this type of function in + the same way used to assign contents of one variable to another: \snippet doc/src/snippets/qmake/functions.pro 1 @@ -4366,7 +4484,7 @@ contents of variables. These functions can be defined in the following way: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 102 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 102 The following example function takes a variable name as its only argument, extracts a list of values from the variable with the @@ -4378,9 +4496,9 @@ \target ConditionalFunctions \section1 Conditional Functions - \l {qmake}{ \c qmake}provides built-in functions that can be used as conditions - when writing scopes. These functions do not return a value, but - instead indicate "success" or "failure": + \l{qmake Manual#qmake}{\c qmake} provides built-in functions that can be + used as conditions when writing scopes. These functions do not return a + value, but instead indicate "success" or "failure": \snippet doc/src/snippets/qmake/functions.pro 3 @@ -4395,13 +4513,13 @@ \section1 Adding New Configuration Features - \l {qmake}{ \c qmake}lets you create your own \e features that can be included in - project files by adding their names to the list of values specified by - the \c CONFIG variable. Features are collections of custom functions and - definitions in \c{.prf} files that can reside in one of many standard - directories. The locations of these directories are defined in a number - of places, and \l {qmake}{ \c qmake}checks each of them in the following order when - it looks for \c{.prf} files: + \l{qmake Manual#qmake}{\c qmake} lets you create your own \e features that + can be included in project files by adding their names to the list of + values specified by the \c CONFIG variable. Features are collections of + custom functions and definitions in \c{.prf} files that can reside in one + of many standard directories. The locations of these directories are + defined in a number of places, and \l{qmake Manual#qmake}{\c qmake} checks + each of them in the following order when it looks for \c{.prf} files: \list 1 \o In a directory listed in the \c QMAKEFEATURES environment variable; @@ -4435,12 +4553,12 @@ For example, consider the following assignment in a project file: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 103 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 103 - With this addition to the \c CONFIG variable, \l {qmake}{ \c qmake}will search the - locations listed above for the \c myfeatures.prf file after it has - finished parsing your project file. On Unix systems, it will look for - the following file: + With this addition to the \c CONFIG variable, + \l{qmake Manual#qmake}{\c qmake} will search the locations listed above for + the \c myfeatures.prf file after it has finished parsing your project file. + On Unix systems, it will look for the following file: \list 1 \o \c $QMAKEFEATURES/myfeatures.prf (for each directory listed in the @@ -4480,8 +4598,8 @@ specified file. Each subsequent compilation is faster because the stable code does not need to be recompiled. - \l {qmake}{ \c qmake}supports the use of precompiled headers (PCH) on some - platforms and build environments, including: + \l{qmake Manual#qmake}{\c qmake} supports the use of precompiled headers + (PCH) on some platforms and build environments, including: \list \o Windows \list @@ -4512,7 +4630,7 @@ \section3 Example: \c stable.h - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 104 + \snippet doc/src/snippets/code/doc_src_qmake-manual.cpp 104 Note that a precompiled header file needs to separate C includes from C++ includes, since the precompiled header file for C files may not @@ -4524,11 +4642,12 @@ To make your project use PCH, you only need to define the \c PRECOMPILED_HEADER variable in your project file: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 105 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 105 - \l {qmake}{ \c qmake}will handle the rest, to ensure the creation and use of the - precompiled header file. You do not need to include the precompiled - header file in \c HEADERS, as \l {qmake}{ \c qmake}will do this if the configuration + \l{qmake Manual#qmake}{\c qmake} will handle the rest, to ensure the + creation and use of the precompiled header file. You do not need to + include the precompiled header file in \c HEADERS, as + \l{qmake Manual#qmake}{\c qmake} will do this if the configuration supports PCH. All platforms that support precompiled headers have the configuration @@ -4536,7 +4655,7 @@ conditional blocks in your project file to add settings when using PCH. For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 106 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 106 \section1 Notes on Possible Issues @@ -4545,7 +4664,7 @@ declarations may cause two different object files with the same name to be generated: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 107 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 107 To avoid potential conflicts like these, it is good practice to ensure that header files that will be precompiled are given distinctive names. @@ -4593,8 +4712,9 @@ \previouspage qmake Manual \nextpage qmake Common Projects - This tutorial teaches you how to use \c qmake. We recommend that - you read the \l {qmake}{ \c qmake}user guide after completing this tutorial. + This tutorial teaches you how to use \l{qmake Manual#qmake}{\c qmake}. We + recommend that you read the \l{qmake Manual#qmake}{\c qmake} user guide + after completing this tutorial. \section1 Starting off Simple @@ -4612,25 +4732,25 @@ the application is that it's written in Qt. First, using your favorite plain text editor, create a file called \c hello.pro in \c{examples/qmake/tutorial}. The first thing you need to do is add the - lines that tell \l {qmake}{ \c qmake}about the source and header files that are part - of your development project. + lines that tell \l{qmake Manual#qmake}{\c qmake} about the source and + header files that are part of your development project. We'll add the source files to the project file first. To do this you need to use the \l{qmake Variable Reference#SOURCES}{SOURCES} variable. Just start a new line with \c {SOURCES +=} and put hello.cpp after it. You should have something like this: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 108 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 108 We repeat this for each source file in the project, until we end up with the following: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 109 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 109 If you prefer to use a Make-like syntax, with all the files listed in one go you can use the newline escaping like this: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 110 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 110 Now that the source files are listed in the project file, the header files must be added. These are added in exactly the same way as source @@ -4640,7 +4760,7 @@ Once you have done this, your project file should look something like this: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 111 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 111 The target name is set automatically; it is the same as the project file, but with the suffix appropriate to the platform. For example, if @@ -4648,29 +4768,30 @@ on Windows and \c hello on Unix. If you want to use a different name you can set it in the project file: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 112 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 112 The final step is to set the \l{qmake Variable Reference#CONFIG}{CONFIG} variable. Since this is a Qt application, we need to put \c qt on the - \c CONFIG line so that \l {qmake}{ \c qmake}will add the relevant libraries to be - linked against and ensure that build lines for \c moc and \c uic are - included in the generated Makefile. + \c CONFIG line so that \l{qmake Manual#qmake}{\c qmake} will add the + relevant libraries to be linked against and ensure that build lines for + \c moc and \c uic are included in the generated Makefile. The finished project file should look like this: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 113 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 113 - You can now use \l {qmake}{ \c qmake}to generate a Makefile for your application. - On the command line, in your project's directory, type the following: + You can now use \l{qmake Manual#qmake}{\c qmake} to generate a Makefile + for your application. On the command line, in your project's directory, + type the following: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 114 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 114 Then type \c make or \c nmake depending on the compiler you use. - For Visual Studio users, \l {qmake}{ \c qmake}can also generate \c .dsp or - \c .vcproj files, for example: + For Visual Studio users, \l{qmake Manual#qmake}{\c qmake} can also + generate \c .dsp or \c .vcproj files, for example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 115 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 115 \section1 Making an Application Debuggable @@ -4682,11 +4803,11 @@ For example: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 116 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 116 - Use \l {qmake}{ \c qmake}as before to generate a Makefile and you will be able to - obtain useful information about your application when running it in - a debugging environment. + Use \l{qmake Manual#qmake}{\c qmake} as before to generate a Makefile and + you will be able to obtain useful information about your application when + running it in a debugging environment. \section1 Adding Platform-Specific Source Files @@ -4697,44 +4818,46 @@ hellounix.cpp. We can't just add these to the \c SOURCES variable since this will put both files in the Makefile. So, what we need to do here is to use a scope which will be processed depending on - which platform \l {qmake}{ \c qmake}is run on. + which platform \l{qmake Manual#qmake}{\c qmake} is run on. A simple scope that will add in the platform-dependent file for Windows looks like this: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 117 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 117 - So if \l {qmake}{ \c qmake}is run on Windows, it will add \c hellowin.cpp to the - list of source files. If \l {qmake}{ \c qmake}is run on any other platform, it + So if \l{qmake Manual#qmake}{\c qmake} is run on Windows, it will add + \c hellowin.cpp to the list of source files. If + \l{qmake Manual#qmake}{\c qmake} is run on any other platform, it will simply ignore it. Now all that is left to be done is to create a scope for the Unix-specific file. When you have done that, your project file should now look something like this: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 118 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 118 - Use \l {qmake}{ \c qmake}as before to generate a Makefile. + Use \l{qmake Manual#qmake}{\c qmake} as before to generate a Makefile. \section1 Stopping qmake If a File Doesn't Exist You may not want to create a Makefile if a certain file doesn't exist. We can check if a file exists by using the exists() function. We can - stop \l {qmake}{ \c qmake}from processing by using the error() function. This - works in the same way as scopes do. Simply replace the scope condition - with the function. A check for a \c main.cpp file looks like this: + stop \l{qmake Manual#qmake}{\c qmake} from processing by using the error() + function. This works in the same way as scopes do. Simply replace the + scope condition with the function. A check for a \c main.cpp file looks + like this: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 119 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 119 The \c{!} symbol is used to negate the test; i.e. \c{exists( main.cpp )} is true if the file exists, and \c{!exists( main.cpp )} is true if the file doesn't exist. - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 120 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 120 - Use \l {qmake}{ \c qmake}as before to generate a makefile. If you rename \c - main.cpp temporarily, you will see the message and \l {qmake}{ \c qmake}will stop - processing. + Use \l{qmake Manual#qmake}{\c qmake} as before to generate a makefile. + If you rename \c main.cpp temporarily, you will see the message and + \l{qmake Manual#qmake}{\c qmake} will stop processing. \section1 Checking for More than One Condition @@ -4749,15 +4872,16 @@ the other inside it. Put the settings to be processed inside the last scope, like this: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 121 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 121 Nested scopes can be joined together using colons, so the final project file looks like this: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 122 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 122 - That's it! You have now completed the tutorial for \c qmake, and are - ready to write project files for your development projects. + That's it! You have now completed the tutorial for + \l{qmake Manual#qmake}{\c qmake}, and are ready to write project files for + your development projects. */ /*! @@ -4767,10 +4891,10 @@ \previouspage qmake Tutorial \nextpage Using qmake - This chapter describes how to set up \l {qmake}{ \c qmake}project files for three - common project types that are based on Qt. Although all kinds of - projects use many of the same variables, each of them use project-specific - variables to customize output files. + This chapter describes how to set up \l{qmake Manual#qmake}{\c qmake} + project files for three common project types that are based on Qt. + Although all kinds of projects use many of the same variables, each of + them use project-specific variables to customize output files. Platform-specific variables are not described here; we refer the reader to the \l{Deploying Qt Applications} document for information on issues such as @@ -4786,9 +4910,10 @@ \section2 The app Template - The \c app template tells \l {qmake}{ \c qmake}to generate a Makefile that will build - an application. With this template, the type of application can be specified - by adding one of the following options to the \c CONFIG variable definition: + The \c app template tells \l{qmake Manual#qmake}{\c qmake} to generate a + Makefile that will build an application. With this template, the type of + application can be specified by adding one of the following options to the + \c CONFIG variable definition: \table \header \o Option \o Description @@ -4797,9 +4922,9 @@ application. \endtable - When using this template the following \l {qmake}{ \c qmake}system variables are recognized. - You should use these in your .pro file to specify information about your - application. + When using this template the following \l{qmake Manual#qmake}{\c qmake} + system variables are recognized. You should use these in your .pro file to + specify information about your application. \list \o HEADERS - A list of all the header files for the application. @@ -4821,12 +4946,12 @@ \o RES_FILE - Windows only: A resource file to be linked against for the application. \endlist - You only need to use the system variables that you have values for, - for instance, if you do not have any extra INCLUDEPATHs then you do not - need to specify any, \l {qmake}{ \c qmake}will add in the default ones needed. - For instance, an example project file might look like this: + You only need to use the system variables that you have values for, for + instance, if you do not have any extra INCLUDEPATHs then you do not need + to specify any, \l{qmake Manual#qmake}{\c qmake} will add in the default + ones needed. For instance, an example project file might look like this: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 123 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 123 For items that are single valued, e.g. the template or the destination directory, we use "="; but for multi-valued items we use "+=" to \e @@ -4839,11 +4964,11 @@ \section2 The lib Template - The \c lib template tells \l {qmake}{ \c qmake}to generate a Makefile that will - build a library. When using this template, in addition to the system variables - mentioned above for the \c app template the \c VERSION variable is - supported. You should use these in your .pro file to specify - information about the library. + The \c lib template tells \l{qmake Manual#qmake}{\c qmake} to generate a + Makefile that will build a library. When using this template, in addition + to the system variables mentioned above for the \c app template the + \c VERSION variable is supported. You should use these in your .pro file + to specify information about the library. When using the \c lib template, the following options can be added to the \c CONFIG variable to determine the type of library that is built: @@ -4870,10 +4995,10 @@ \section1 Building a Plugin Plugins are built using the \c lib template, as described in the previous - section. This tells \l {qmake}{ \c qmake}to generate a Makefile for the project that will - build a plugin in a suitable form for each platform, usually in the form of a - library. As with ordinary libraries, the \c VERSION variable is used to specify - information about the plugin. + section. This tells \l{qmake Manual#qmake}{\c qmake} to generate a + Makefile for the project that will build a plugin in a suitable form for + each platform, usually in the form of a library. As with ordinary + libraries, the \c VERSION variable is used to specify information about the plugin. \list \o VERSION - The version number of the target library, for example, 2.3.1. @@ -4908,11 +5033,11 @@ ensure that the resulting targets have different names. Providing different names for targets ensures that one will not overwrite the other. - When \l {qmake}{ \c qmake}processes the project file, it will generate a Makefile rule - to allow the project to be built in both modes. This can be invoked in the - following way: + When \l{qmake Manual#qmake}{\c qmake} processes the project file, it will + generate a Makefile rule to allow the project to be built in both modes. + This can be invoked in the following way: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 124 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 124 The \c build_all option can be added to the \c CONFIG variable in the project file to ensure that the project is built in both modes by default: @@ -4921,14 +5046,14 @@ This allows the Makefile to be processed using the default rule: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 125 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 125 \section2 Installing in Both Modes The \c build_all option also ensures that both versions of the target will be installed when the installation rule is invoked: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 126 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 126 It is possible to customize the names of the build targets depending on the target platform. For example, a library or plugin may be named using a @@ -4938,7 +5063,7 @@ Note: This was originally used in the customwidgetplugin.pro file, but is no longer needed there. \endomit - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 127 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 127 The default behavior in the above snippet is to modify the name used for the build target when building in debug mode. An \c else clause could be diff --git a/doc/src/development/qtestlib.qdoc b/doc/src/development/qtestlib.qdoc index 8924bdb..44b682a 100644 --- a/doc/src/development/qtestlib.qdoc +++ b/doc/src/development/qtestlib.qdoc @@ -119,7 +119,7 @@ testfunction. Example: - \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qtestlib.cpp 0 For more examples, refer to the \l{QTestLib Tutorial}. @@ -128,7 +128,7 @@ If you are using \c qmake as your build tool, just add the following to your project file: - \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qtestlib.pro 1 If you are using other build tools, make sure that you add the location of the QTestLib header files to your include path (usually \c{include/QtTest} @@ -217,7 +217,7 @@ To create a benchmark, follow the instructions for creating a test and then add a QBENCHMARK macro to the test function that you want to benchmark. - \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 12 + \snippet doc/src/snippets/code/doc_src_qtestlib.cpp 12 The code inside the QBENCHMARK macro will be measured, and possibly also repeated several times in order to get an accurate measurement. This depends on the selected @@ -410,7 +410,7 @@ Then you need to implement the test function itself. The implementation could look like this: - \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 8 + \snippet doc/src/snippets/code/doc_src_qtestlib.cpp 8 The \l QVERIFY() macro evaluates the expression passed as its argument. If the expression evaluates to true, the execution of @@ -475,7 +475,7 @@ test function. If we add more test data, the function might look like this: - \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 11 + \snippet doc/src/snippets/code/doc_src_qtestlib.cpp 11 To prevent that the function ends up being cluttered by repetitive code, QTestLib supports adding test data to a test function. All diff --git a/doc/src/examples/activeqt/hierarchy-demo-snippet.qdoc b/doc/src/examples/activeqt/hierarchy-demo-snippet.qdoc new file mode 100644 index 0000000..a36ebbb --- /dev/null +++ b/doc/src/examples/activeqt/hierarchy-demo-snippet.qdoc @@ -0,0 +1,68 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [script] +<script language="javascript"> +function createSubWidget( form ) +{ + ParentWidget.createSubWidget( form.nameEdit.value ); +} + +function renameSubWidget( form ) +{ + var SubWidget = ParentWidget.subWidget( form.nameEdit.value ); + if ( !SubWidget ) { + alert( "No such widget " + form.nameEdit.value + "!" ); + return; + } + SubWidget.label = form.labelEdit.value; + form.nameEdit.value = SubWidget.label; +} + +function setFont( form ) +{ + ParentWidget.font = form.fontEdit.value; +} +</script> + +<p> +This widget can have many children! +</p> +<object ID="ParentWidget" CLASSID="CLSID:d574a747-8016-46db-a07c-b2b4854ee75c" +CODEBASE="http://qt.nokia.com/demos/hierarchy.cab"> +[Object not available! Did you forget to build and register the server?] +</object><br /> +<form> +<input type="edit" ID="nameEdit" value="<enter object name>" /> +<input type="button" value="Create" onClick="createSubWidget(this.form)" /> +<input type="edit" ID="labelEdit" /> +<input type="button" value="Rename" onClick="renameSubWidget(this.form)" /> +<br /> +<input type="edit" ID="fontEdit" value="MS Sans Serif" /> +<input type="button" value = "Set Font" onClick="setFont(this.form)" /> +</form> +//! [script] diff --git a/doc/src/examples/activeqt/hierarchy-demo.qdocinc b/doc/src/examples/activeqt/hierarchy-demo.qdocinc index e7cb56e..86bfd87 100644 --- a/doc/src/examples/activeqt/hierarchy-demo.qdocinc +++ b/doc/src/examples/activeqt/hierarchy-demo.qdocinc @@ -1,5 +1,4 @@ \raw HTML -//! [0] <script language="javascript"> function createSubWidget( form ) { @@ -39,5 +38,4 @@ CODEBASE="http://qt.nokia.com/demos/hierarchy.cab"> <input type="edit" ID="fontEdit" value="MS Sans Serif" /> <input type="button" value = "Set Font" onClick="setFont(this.form)" /> </form> -//! [0] \endraw diff --git a/doc/src/examples/activeqt/hierarchy.qdoc b/doc/src/examples/activeqt/hierarchy.qdoc index eb6cc71..791af1f 100644 --- a/doc/src/examples/activeqt/hierarchy.qdoc +++ b/doc/src/examples/activeqt/hierarchy.qdoc @@ -25,7 +25,7 @@ ** ****************************************************************************/ -/*! +/*! \page qaxserver-demo-hierarchy.html \title Qt Widget Hierarchy @@ -84,5 +84,5 @@ your WebBrowser to support ActiveX controls, and scripting to be enabled. - \snippet examples/activeqt/hierarchy-demo.qdocinc 0 + \snippet examples/activeqt/hierarchy-demo-snippet.qdoc script */ diff --git a/doc/src/examples/arrowpad.qdoc b/doc/src/examples/arrowpad.qdoc index bb22f83..5e9cc9a 100644 --- a/doc/src/examples/arrowpad.qdoc +++ b/doc/src/examples/arrowpad.qdoc @@ -66,7 +66,7 @@ context: it is the context of the texts in the \c ArrowPad class. The \c Q_OBJECT macro defines \c tr(x) in \c ArrowPad like this: - \snippet doc/src/snippets/code/doc_src_examples_arrowpad.qdoc 0 + \snippet doc/src/snippets/code/doc_src_examples_arrowpad.cpp 0 Knowing which class each source text appears in enables \e {Qt Linguist} to group texts that are logically related together, e.g. diff --git a/doc/src/examples/containerextension.qdoc b/doc/src/examples/containerextension.qdoc index 818547c..57295de 100644 --- a/doc/src/examples/containerextension.qdoc +++ b/doc/src/examples/containerextension.qdoc @@ -138,7 +138,7 @@ target path for the project and adding it to the list of items to install: - \snippet doc/src/snippets/code/doc_src_examples_containerextension.qdoc 0 + \snippet doc/src/snippets/code/doc_src_examples_containerextension.pro 0 The container extension is created as a library, and will be installed alongside the other \QD plugins when the project is diff --git a/doc/src/examples/customwidgetplugin.qdoc b/doc/src/examples/customwidgetplugin.qdoc index f972500..5b6aab6 100644 --- a/doc/src/examples/customwidgetplugin.qdoc +++ b/doc/src/examples/customwidgetplugin.qdoc @@ -89,7 +89,7 @@ target path for the project and adding it to the list of items to install: - \snippet doc/src/snippets/code/doc_src_examples_customwidgetplugin.qdoc 0 + \snippet doc/src/snippets/code/doc_src_examples_customwidgetplugin.pro 0 The custom widget is created as a library, and will be installed alongside the other \QD plugins when the project is installed diff --git a/doc/src/examples/editabletreemodel.qdoc b/doc/src/examples/editabletreemodel.qdoc index 042b745..5edc91b 100644 --- a/doc/src/examples/editabletreemodel.qdoc +++ b/doc/src/examples/editabletreemodel.qdoc @@ -131,14 +131,14 @@ In the case shown in the diagram, the piece of information represented by \bold{a} can be obtained using the standard model/view API: - \snippet doc/src/snippets/code/doc_src_examples_editabletreemodel.qdoc 0 + \snippet doc/src/snippets/code/doc_src_examples_editabletreemodel.cpp 0 Since each items holds pieces of data for each column in a given row, there can be many model indexes that map to the same \c TreeItem object. For example, the information represented by \bold{b} can be obtained using the following code: - \snippet doc/src/snippets/code/doc_src_examples_editabletreemodel.qdoc 1 + \snippet doc/src/snippets/code/doc_src_examples_editabletreemodel.cpp 1 The same underlying \c TreeItem would be accessed to obtain information for the other model indexes in the same row as \bold{b}. diff --git a/doc/src/examples/fademessage.qdoc b/doc/src/examples/fademessage.qdoc index b8a09e8..09c1d94 100644 --- a/doc/src/examples/fademessage.qdoc +++ b/doc/src/examples/fademessage.qdoc @@ -29,13 +29,9 @@ \example effects/fademessage \title Fade Message Effect Example - \raw HTML - <div style="text-align: center"> - \endraw + \div { style="text-align: center"} \inlineimage fademessageeffect-example.png \inlineimage fademessageeffect-example-faded.png - \raw HTML - </div> - \endraw + \enddiv */ diff --git a/doc/src/examples/fancybrowser.qdoc b/doc/src/examples/fancybrowser.qdoc index b46903d..bc30988 100644 --- a/doc/src/examples/fancybrowser.qdoc +++ b/doc/src/examples/fancybrowser.qdoc @@ -26,8 +26,8 @@ ****************************************************************************/ /*! - \example webkit/fancybrowser - \title Fancy Browser Example + \example webkit/fancybrowser + \title Fancy Browser Example The Fancy Browser example shows how to use jQuery with QtWebKit to create a web browser with special effects and content diff --git a/doc/src/examples/globalVariables.qdoc b/doc/src/examples/globalVariables.qdoc index 4629801..224a3a7 100644 --- a/doc/src/examples/globalVariables.qdoc +++ b/doc/src/examples/globalVariables.qdoc @@ -101,48 +101,25 @@ The \c xmlpatterns command loads and parses \c globals.gccxml, runs the XQuery \c reportGlobals.xq, and generates this report: - \raw HTML -<html xmlns="http://www.w3.org/1999/xhtml/" xml:lang="en" lang="en"> - <head> - <title>Global variables report for globals.gccxml</title> - </head> - <style type="text/css"> - .details - { - text-align: left; - font-size: 80%; - color: blue - } - .variableName - { - font-family: courier; - color: blue - } - </style> - <body> - <p class="details">Start report: 2008-12-16T13:43:49.65Z</p> - <p>Global variables with complex types:</p> - <ol> - <li> - <span class="variableName">mutableComplex1</span> in globals.cpp at line 14</li> - <li> - <span class="variableName">mutableComplex2</span> in globals.cpp at line 15</li> - <li> - <span class="variableName">constComplex1</span> in globals.cpp at line 16</li> - <li> - <span class="variableName">constComplex2</span> in globals.cpp at line 17</li> - </ol> - <p>Mutable global variables with primitives types:</p> - <ol> - <li> - <span class="variableName">mutablePrimitive1</span> in globals.cpp at line 1</li> - <li> - <span class="variableName">mutablePrimitive2</span> in globals.cpp at line 2</li> - </ol> - <p class="details">End report: 2008-12-16T13:43:49.65Z</p> - </body> -</html> - \endraw + \div {class="details"} + Start report: 2008-12-16T13:43:49.65Z + \enddiv + + Global variables with complex types: + \list 1 + \o \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14 + \o \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15 + \o \span {class="variableName"} {constComplex1} in globals.cpp at line 16 + \o \span {class="variableName"} {constComplex2} in globals.cpp at line 17 + \endlist + + Mutable global variables with primitives types: + \list 1 + \o \span {class="variableName"} {mutablePrimitive1} in globals.cpp at line 1 + \o \span {class="variableName"} {mutablePrimitive2} in globals.cpp at line 2 + \endlist + + \div {class="details"} End report: 2008-12-16T13:43:49.65Z \enddiv \section1 XQuery Code Walk-Through diff --git a/doc/src/examples/icons.qdoc b/doc/src/examples/icons.qdoc index 4210859..3966bf4 100644 --- a/doc/src/examples/icons.qdoc +++ b/doc/src/examples/icons.qdoc @@ -147,8 +147,8 @@ render the other six mode/state combinations, QIcon uses the search algorithm described in the table below: - \table - \header \o{2,1} Requested Pixmap \o{8,1} Preferred Alternatives (mode/state) + \table 100% + \header \o{2,1} Requested Pixmap \o {8,1} Preferred Alternatives (mode/state) \header \o Mode \o State \o 1 \o 2 \o 3 \o 4 \o 5 \o 6 \o 7 \o 8 \row \o{1,2} Normal \o Off \o \bold N0 \o A0 \o N1 \o A1 \o D0 \o S0 \o D1 \o S1 \row \o On \o N1 \o \bold A1 \o N0 \o A0 \o D1 \o S1 \o D0 \o S0 @@ -278,7 +278,7 @@ If the application is built in debug mode, the \c Q_ASSERT() macro will expand to - \snippet doc/src/snippets/code/doc_src_examples_icons.qdoc 0 + \snippet doc/src/snippets/code/doc_src_examples_icons.cpp 0 In release mode, the macro simply disappear. The mode can be set in the application's \c .pro file. One way to do so is to add an diff --git a/doc/src/examples/imageviewer.qdoc b/doc/src/examples/imageviewer.qdoc index 70f71c8..f1d02c3 100644 --- a/doc/src/examples/imageviewer.qdoc +++ b/doc/src/examples/imageviewer.qdoc @@ -149,7 +149,7 @@ \{QWidget::adjustSize()}{adjustSize()} to achieve this, which is essentially the same as - \snippet doc/src/snippets/code/doc_src_examples_imageviewer.qdoc 0 + \snippet doc/src/snippets/code/doc_src_examples_imageviewer.cpp 0 In the \c print() slot, we first make sure that an image has been loaded into the application: @@ -160,7 +160,7 @@ If the application is built in debug mode, the \c Q_ASSERT() macro will expand to - \snippet doc/src/snippets/code/doc_src_examples_imageviewer.qdoc 1 + \snippet doc/src/snippets/code/doc_src_examples_imageviewer.cpp 1 In release mode, the macro simply disappear. The mode can be set in the application's \c .pro file. One way to do so is to add an @@ -318,7 +318,7 @@ Whenever we zoom in or out, we need to adjust the scroll bars in consequence. It would have been tempting to simply call - \snippet doc/src/snippets/code/doc_src_examples_imageviewer.qdoc 4 + \snippet doc/src/snippets/code/doc_src_examples_imageviewer.cpp 4 but this would make the top-left corner the focal point, not the center. Therefore we need to take into account the scroll bar diff --git a/doc/src/examples/qml-examples.qdoc b/doc/src/examples/qml-examples.qdoc index 3439b09..68deae7 100644 --- a/doc/src/examples/qml-examples.qdoc +++ b/doc/src/examples/qml-examples.qdoc @@ -29,7 +29,7 @@ \title Animation: Basics Example \example declarative/animation/basics - This example shows how to create and combine \l{QML Animation}{animations} in QML. + This example shows how to create and combine \l{QML Animation and Transitions}{animations} in QML. \table \row @@ -50,16 +50,16 @@ \title Animation: Behavior Examples \example declarative/animation/behaviors - This example shows how to use QML behaviors. + This example shows how to use QML behaviors. \image qml-behaviors-example.png */ /*! - \title Animation: Easing Example + \title Animation: Easing Example \example declarative/animation/easing - This example shows the different easing modes available for \l{QML Animation}{animations}. + This example shows the different easing modes available for \l{QML Animation and Transitions}{animations}. \image qml-easing-example.png */ @@ -122,9 +122,9 @@ \page declarative-cppextensions-reference.html \title C++ Extensions: Reference examples - These examples show how QML can be extended from C++ in various ways. - - The code for these examples is used throughout the \l {Extending QML in C++} reference + These examples show how QML can be extended from C++ in various ways. + + The code for these examples is used throughout the \l {Extending QML Functionalities using C++} reference documentation, which highlights the main principles demonstrated in each example. Furthermore, here are additional pages that discuss each example in detail: @@ -160,7 +160,7 @@ \title LayoutItem Example \example declarative/cppextensions/qgraphicslayouts/layoutitem - This example show how to use the LayoutItem element to integrate QML items into an existing + This example show how to use the LayoutItem element to integrate QML items into an existing \l{Graphics View Framework}{Graphics View}-based application. \image qml-layoutitem-example.png @@ -169,7 +169,7 @@ \title QGraphicsGridLayout Example \example declarative/cppextensions/qgraphicslayouts/qgraphicsgridlayout - This example shows how to use QGraphicsGridLayout to lay out QML items. This is + This example shows how to use QGraphicsGridLayout to lay out QML items. This is useful if you need to integrate Qt \l{Graphics View Framework}{Graphics View} layouts with QML. @@ -179,10 +179,10 @@ \title QGraphicsLinearLayout Example \example declarative/cppextensions/qgraphicslayouts/qgraphicslinearlayout - This example shows how to use QGraphicsLinearLayout to lay out QML items. This is + This example shows how to use QGraphicsLinearLayout to lay out QML items. This is useful if you need to integrate Qt \l{Graphics View Framework}{Graphics View} layouts with QML. - + \image qml-qgraphicslinearlayout-example.png */ /*! @@ -198,7 +198,7 @@ \o \l{declarative/cppextensions/qgraphicslayouts/qgraphicslinearlayout}{QGraphicsLinearLayout} \endlist - Also see \l {Integrating QML with existing Qt UI code} for information on using QML + Also see \l {Integrating QML Code with Existing Qt UI Code} for information on using QML in Qt applications that use the Graphics View framework or ordinary QWidget-based views. */ @@ -215,7 +215,7 @@ \title C++ Extensions: Image Provider Example \example declarative/cppextensions/imageprovider - This examples shows how to use QDeclarativeImageProvider to serve images + This examples shows how to use QDeclarativeImageProvider to serve images to QML image elements. \image qml-imageprovider-example.png @@ -232,6 +232,7 @@ /*! \title Internationalization Example \example declarative/i18n + \ingroup internationalization This example shows how to enable text translation in QML. @@ -567,7 +568,7 @@ \example declarative/toys/clocks This example displays a set of clocks with different times for different cities. - Each clock is created by combining \l Image elements with \l Rotation transforms + Each clock is created by combining \l Image elements with \l Rotation transforms and \l SpringAnimation behaviors. \image qml-clocks-example.png @@ -615,13 +616,6 @@ */ /*! - \title Touch Interaction: Gestures Example - \example declarative/touchinteraction/gestures - - This example shows how to use the GestureArea element. -*/ - -/*! \title Touch Interaction: MouseArea Example \example declarative/touchinteraction/mousearea diff --git a/doc/src/examples/qtscriptcustomclass.qdoc b/doc/src/examples/qtscriptcustomclass.qdoc index f2b4f36..3ee6c95 100644 --- a/doc/src/examples/qtscriptcustomclass.qdoc +++ b/doc/src/examples/qtscriptcustomclass.qdoc @@ -46,7 +46,7 @@ scripting environment, \c{ByteArray} objects can be constructed like so: - \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.qdoc 0 + \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.cpp 0 \c{ByteArray} objects behave similar to normal \c{Array} objects. Every \c{ByteArray} object has a \c{length} property, that holds the length of the array. If a new value is assigned to the \c{length} @@ -55,22 +55,22 @@ Use normal array operations to read or write bytes in the array. The following code sets all the bytes of an array to a certain value: - \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.qdoc 1 + \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.cpp 1 When assigning a value to an array element, the value is truncated to eight bits: - \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.qdoc 2 + \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.cpp 2 Like normal \c{Array} objects, if the array index is greater than the current length of the array, the array is resized accordingly: - \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.qdoc 3 + \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.cpp 3 Property names that aren't valid array indexes are treated like normal object properties (again, the same is the case for normal \c{Array} objects); in other words, it's perfectly fine to do something like this: - \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.qdoc 4 + \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.cpp 4 The above assignment won't affect the contents of the array, but will rather assign a value to the object property named "foo". @@ -78,7 +78,7 @@ \c{ByteArray} objects have a set of methods: chop(), equals(), left(), mid(), toBase64() and so on. These map directly onto the corresponding methods in QByteArray. - \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.qdoc 5 + \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.cpp 5 \section1 ByteArray Class Implementation diff --git a/doc/src/examples/rogue.qdoc b/doc/src/examples/rogue.qdoc index 94539ad..4df0910 100644 --- a/doc/src/examples/rogue.qdoc +++ b/doc/src/examples/rogue.qdoc @@ -190,8 +190,8 @@ \snippet examples/statemachine/rogue/movementtransition.h 2 When \c onTransition() is invoked, we know that we have a - \l{QEvent::}{KeyPress} event with 2, 4, 6, or 8, i.e., the event - is already unwrapped. + \l{QEvent::}{KeyPress} event with 2, 4, 6, or 8, and can ask \c + Window to move the player. \section1 The Roguelike Tradition diff --git a/doc/src/examples/simpledommodel.qdoc b/doc/src/examples/simpledommodel.qdoc index ea380bd..9b4d80e 100644 --- a/doc/src/examples/simpledommodel.qdoc +++ b/doc/src/examples/simpledommodel.qdoc @@ -53,7 +53,7 @@ snippet reads the contents of a file into a QDomDocument object and traverses the document, reading all the plain text that can be found: - \snippet doc/src/snippets/code/doc_src_examples_simpledommodel.qdoc 0 + \snippet doc/src/snippets/code/doc_src_examples_simpledommodel.cpp 0 In principle, the functions provided by QDomNode can be used to navigate from any given starting point in a document to the piece of data requested by another component. diff --git a/doc/src/examples/taskmenuextension.qdoc b/doc/src/examples/taskmenuextension.qdoc index 0200c2f..b557b8b 100644 --- a/doc/src/examples/taskmenuextension.qdoc +++ b/doc/src/examples/taskmenuextension.qdoc @@ -139,7 +139,7 @@ target path for the project and adding it to the list of items to install: - \snippet doc/src/snippets/code/doc_src_examples_taskmenuextension.qdoc 0 + \snippet doc/src/snippets/code/doc_src_examples_taskmenuextension.pro 0 The task menu extension is created as a library, and will be installed alongside the other \QD plugins when the project is diff --git a/doc/src/examples/textfinder.qdoc b/doc/src/examples/textfinder.qdoc index e92bb98..f5f41d7 100644 --- a/doc/src/examples/textfinder.qdoc +++ b/doc/src/examples/textfinder.qdoc @@ -70,7 +70,7 @@ QtUiTools module library. This is done in the \c{textfinder.pro} file that contains the following lines: - \snippet doc/src/snippets/code/doc_src_examples_textfinder.qdoc 0 + \snippet doc/src/snippets/code/doc_src_examples_textfinder.pro 0 \section1 TextFinder Class Definition diff --git a/doc/src/examples/trollprint.qdoc b/doc/src/examples/trollprint.qdoc index 3a77a71..a93811e 100644 --- a/doc/src/examples/trollprint.qdoc +++ b/doc/src/examples/trollprint.qdoc @@ -132,12 +132,12 @@ second argument "two-sided" in the appropriate \c tr() calls to the first pair of radio buttons: - \snippet doc/src/snippets/code/doc_src_examples_trollprint.qdoc 0 + \snippet doc/src/snippets/code/doc_src_examples_trollprint.cpp 0 and add the second argument "colors" in the appropriate \c tr() calls for the second pair of radio buttons: - \snippet doc/src/snippets/code/doc_src_examples_trollprint.qdoc 1 + \snippet doc/src/snippets/code/doc_src_examples_trollprint.cpp 1 Now run \c lupdate and open \c trollprint_pt.ts with \e {Qt Linguist}. You should now see two changes. @@ -177,7 +177,7 @@ the translations. This can be achieved by using a \c TRANSLATOR comment in the source code: - \snippet doc/src/snippets/code/doc_src_examples_trollprint.qdoc 2 + \snippet doc/src/snippets/code/doc_src_examples_trollprint.cpp 2 Try adding these comments to some source files, particularly to dialog classes, describing the navigation necessary to reach the @@ -192,7 +192,7 @@ correct. Comments that provide good navigation information can save them time: - \snippet doc/src/snippets/code/doc_src_examples_trollprint.qdoc 3 + \snippet doc/src/snippets/code/doc_src_examples_trollprint.cpp 3 \section1 Troll Print 1.1 diff --git a/doc/src/examples/undoframework.qdoc b/doc/src/examples/undoframework.qdoc index c5bc279..65104bd 100644 --- a/doc/src/examples/undoframework.qdoc +++ b/doc/src/examples/undoframework.qdoc @@ -199,8 +199,7 @@ \snippet examples/tools/undoframework/commands.cpp 8 - \c undo() removes the item from the scene. We need to update the - scene as ...(ask Andreas) + \c undo() removes the item from the scene. \snippet examples/tools/undoframework/commands.cpp 9 diff --git a/doc/src/examples/worldtimeclockplugin.qdoc b/doc/src/examples/worldtimeclockplugin.qdoc index 61a214c..8a17004 100644 --- a/doc/src/examples/worldtimeclockplugin.qdoc +++ b/doc/src/examples/worldtimeclockplugin.qdoc @@ -176,7 +176,7 @@ is searched by \QD. We do this by specifying a target path for the project and adding it to the list of items to install: - \snippet doc/src/snippets/code/doc_src_examples_worldtimeclockplugin.qdoc 0 + \snippet doc/src/snippets/code/doc_src_examples_worldtimeclockplugin.pro 0 The custom widget is created as a library, and will be installed alongside the other \QD plugins when the project is installed diff --git a/doc/src/external-resources.qdoc b/doc/src/external-resources.qdoc index 7639324..1abeae9 100644 --- a/doc/src/external-resources.qdoc +++ b/doc/src/external-resources.qdoc @@ -455,6 +455,31 @@ */ /*! + \externalpage https://developer.mozilla.org/en/JavaScript/Reference/Reserved_Words + \title JavaScript Reserved Words +*/ + +/*! \externalpage http://publicsuffix.org/ \title publicsuffix.org */ + +/*! + \externalpage http://wiki.forum.nokia.com/index.php/Capabilities + \title Symbian Capabilities +*/ + +/*! + \externalpage http://wiki.forum.nokia.com/ + \title Forum Nokia Wiki +*/ + +/*! + \externalpage http://wiki.forum.nokia.com/index.php/UID_Q&As_(Symbian_Signed) + \title UID Q&As (Symbian Signed) +*/ + +/*! + \externalpage http://www.symbiansigned.com + \title Symbian Signed +*/ diff --git a/doc/src/files-and-resources/resources.qdoc b/doc/src/files-and-resources/resources.qdoc index ecf343d..35e6a90 100644 --- a/doc/src/files-and-resources/resources.qdoc +++ b/doc/src/files-and-resources/resources.qdoc @@ -130,7 +130,7 @@ In the application, this resource would be registered with code like this: - \snippet doc/src/snippets/code/doc_src_resources.qdoc 4 + \snippet doc/src/snippets/code/doc_src_resources.cpp 4 \section2 Compiled-In Resources @@ -205,7 +205,7 @@ Q_INIT_RESOURCE() with the base name of the \c .qrc file. For example: - \snippet doc/src/snippets/code/doc_src_resources.qdoc 5 + \snippet doc/src/snippets/code/doc_src_resources.cpp 5 Similarly, if you must unload a set of resources explicitly (because a plugin is being unloaded or the resources are not valid diff --git a/doc/src/frameworks-technologies/accessible.qdoc b/doc/src/frameworks-technologies/accessible.qdoc index 1d15dbd..e7bf171 100644 --- a/doc/src/frameworks-technologies/accessible.qdoc +++ b/doc/src/frameworks-technologies/accessible.qdoc @@ -256,7 +256,7 @@ variable set to 1. For example, this is set in the following way with the bash shell: - \snippet doc/src/snippets/code/doc_src_qt4-accessibility.qdoc environment + \snippet doc/src/snippets/code/doc_src_qt4-accessibility.cpp environment Accessibility features are built into Qt by default when the libraries are configured and built. diff --git a/doc/src/frameworks-technologies/activeqt-container.qdoc b/doc/src/frameworks-technologies/activeqt-container.qdoc index 436f375..862408b 100644 --- a/doc/src/frameworks-technologies/activeqt-container.qdoc +++ b/doc/src/frameworks-technologies/activeqt-container.qdoc @@ -67,7 +67,7 @@ To build Qt applications that can host COM objects and ActiveX controls link the application against the QAxContainer module by adding - \snippet doc/src/snippets/code/doc_src_qaxcontainer.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qaxcontainer.pro 0 to your application's \c .pro file. @@ -128,7 +128,7 @@ want to use, or integrate it into the build system by adding the type libraries to the \c TYPELIBS variable in your application's \c .pro file: - \snippet doc/src/snippets/code/doc_src_qaxcontainer.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qaxcontainer.pro 1 Note that \l dumpcpp might not be able to expose all APIs in the type library. diff --git a/doc/src/frameworks-technologies/activeqt-server.qdoc b/doc/src/frameworks-technologies/activeqt-server.qdoc index 9af2b65..77cacf8 100644 --- a/doc/src/frameworks-technologies/activeqt-server.qdoc +++ b/doc/src/frameworks-technologies/activeqt-server.qdoc @@ -60,10 +60,10 @@ An out-of-process executable server is generated from a \c .pro file like this: - \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qaxserver.pro 0 To build an in-process server, use a \c .pro file like this: - \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qaxserver.pro 1 The files \c qaxserver.rc and \c qaxserver.def are part of the framework and can be used from their usual location (specify a @@ -91,7 +91,7 @@ Additionally you can specify a version number using the \c VERSION variable, e.g. - \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 2 + \snippet doc/src/snippets/code/doc_src_qaxserver.pro 2 The version number specified will be used as the version of the type library and of the server when registering. @@ -186,12 +186,12 @@ or any existing QObject subclass. If the class is a subclass of QWidget, the COM object will be an ActiveX control. - \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 3 + \snippet doc/src/snippets/code/doc_src_qaxserver.cpp 3 The Q_OBJECT macro is required to provide the meta object information about the widget to the ActiveQt framework. - \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 4 + \snippet doc/src/snippets/code/doc_src_qaxserver.cpp 4 Use the Q_CLASSINFO() macro to specify the COM identifiers for the COM object. \c ClassID and \c InterfaceID are required, while \c EventsID is @@ -201,7 +201,7 @@ You can specify additional attributes for each of your classes; see \l{Class Information and Tuning} for details. - \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 5 + \snippet doc/src/snippets/code/doc_src_qaxserver.cpp 5 Use the Q_PROPERTY() macro to declare properties for the ActiveX control. @@ -216,7 +216,7 @@ your implementation of QAxFactory::create. \endfootnote - \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 6 + \snippet doc/src/snippets/code/doc_src_qaxserver.cpp 6 The ActiveQt framework will expose properties and public slots as ActiveX properties and methods, and signals as ActiveX events, and convert between @@ -428,7 +428,7 @@ To make the properties bindable for the ActiveX client, use multiple inheritance from the QAxBindable class: - \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 7 + \snippet doc/src/snippets/code/doc_src_qaxserver.cpp 7 When implementing the property write functions, use the QAxBindable class's requestPropertyChange() and propertyChanged() @@ -453,7 +453,7 @@ an implementation of a QAxFactory. The easist way to do this is to use a set of macros: - \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 8 + \snippet doc/src/snippets/code/doc_src_qaxserver.cpp 8 This will export \c MyWidget and \c MyWidget2 as COM objects that can be created by COM clients, and will register \c MySubType as a type that can @@ -470,7 +470,7 @@ server. Use QAxFactory::isServer() to create and run a standard application interface, or to prevent a stand-alone execution: - \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 9 + \snippet doc/src/snippets/code/doc_src_qaxserver.cpp 9 This is however not necessary as ActiveQt provides a default implementation of a main function. The default implemenation calls QAxFactory::startServer(), @@ -512,7 +512,7 @@ macro, the QAxFactory subclass had no appropriate constructor. Provide a public class constructor like - \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 10 + \snippet doc/src/snippets/code/doc_src_qaxserver.cpp 10 for your factory class. @@ -560,7 +560,7 @@ your installer process, resolve the \c DllRegisterServer symbol and call the function: - \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 11 + \snippet doc/src/snippets/code/doc_src_qaxserver.cpp 11 \section3 Distributing Servers over the Internet @@ -766,7 +766,7 @@ own API, and is available in the "Insert Objects" dialog of Microsoft Office applications. - \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 15 + \snippet doc/src/snippets/code/doc_src_qaxserver.cpp 15 \section2 Developing Licensed Components @@ -782,7 +782,7 @@ To mark a Qt class as licensed specify a "LicenseKey" using the Q_CLASSINFO() macro. - \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 16 + \snippet doc/src/snippets/code/doc_src_qaxserver.cpp 16 The key is required to be able to create an instance of \c MyLicensedControl on a machine that is not licensed itself. The licensed developer can now @@ -805,12 +805,12 @@ Create a new subclass of QAxAggregated and use multiple inheritance to subclass additional COM interface classes. - \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 17 + \snippet doc/src/snippets/code/doc_src_qaxserver.cpp 17 Reimplement the QAxAggregated::queryInterface() function to support the additional COM interfaces. - \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 18 + \snippet doc/src/snippets/code/doc_src_qaxserver.cpp 18 Since \c ISomeCOMInterface is a subclass of \c IUnknown you will have to implement the \c QueryInterface(), \c AddRef(), and \c @@ -820,7 +820,7 @@ returned by the QAxAggregated::controllingUnknown() function, e.g. - \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 19 + \snippet doc/src/snippets/code/doc_src_qaxserver.cpp 19 Do not support the \c IUnknown interface itself in your \l{QAxAggregated::queryInterface()}{queryInterface()} @@ -833,5 +833,5 @@ QAxBindable::createAggregate() to return a new object of the QAxAggregated subclass. - \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 20 + \snippet doc/src/snippets/code/doc_src_qaxserver.cpp 20 */ diff --git a/doc/src/frameworks-technologies/containers.qdoc b/doc/src/frameworks-technologies/containers.qdoc index 991588e..f28e5dc 100644 --- a/doc/src/frameworks-technologies/containers.qdoc +++ b/doc/src/frameworks-technologies/containers.qdoc @@ -205,7 +205,7 @@ Here's an example custom data type that meets the requirement of an assignable data type: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 0 + \snippet doc/src/snippets/code/doc_src_containers.cpp 0 If we don't provide a copy constructor or an assignment operator, C++ provides a default implementation that performs a @@ -306,7 +306,7 @@ Here's a typical loop for iterating through all the elements of a QList<QString> in order and printing them to the console: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 1 + \snippet doc/src/snippets/code/doc_src_containers.cpp 1 It works as follows: The QList to iterate over is passed to the QListIterator constructor. At that point, the iterator is located @@ -319,7 +319,7 @@ Here's how to iterate backward in a QList: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 2 + \snippet doc/src/snippets/code/doc_src_containers.cpp 2 The code is symmetric with iterating forward, except that we start by calling \l{QListIterator::toBack()}{toBack()} @@ -358,7 +358,7 @@ QMutableListIterator. Here's an example where we remove all odd numbers from a QList<int> using QMutableListIterator: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 3 + \snippet doc/src/snippets/code/doc_src_containers.cpp 3 The next() call in the loop is made every time. It jumps over the next item in the list. The @@ -368,13 +368,13 @@ the iterator, so it is safe to continue using it. This works just as well when iterating backward: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 4 + \snippet doc/src/snippets/code/doc_src_containers.cpp 4 If we just want to modify the value of an existing item, we can use \l{QMutableListIterator::setValue()}{setValue()}. In the code below, we replace any value larger than 128 with 128: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 5 + \snippet doc/src/snippets/code/doc_src_containers.cpp 5 Just like \l{QMutableListIterator::remove()}{remove()}, \l{QMutableListIterator::setValue()}{setValue()} operates on the @@ -387,7 +387,7 @@ operations, we don't even need \l{QMutableListIterator::setValue()}{setValue()}: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 6 + \snippet doc/src/snippets/code/doc_src_containers.cpp 6 As mentioned above, QLinkedList's, QVector's, and QSet's iterator classes have exactly the same API as QList's. We will now turn to @@ -410,7 +410,7 @@ The following example removes all (capital, country) pairs where the capital's name ends with "City": - \snippet doc/src/snippets/code/doc_src_containers.qdoc 7 + \snippet doc/src/snippets/code/doc_src_containers.cpp 7 QMapIterator also provides a key() and a value() function that operate directly on the iterator and that return the key and @@ -418,7 +418,7 @@ example, the following code copies the contents of a QMap into a QHash: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 8 + \snippet doc/src/snippets/code/doc_src_containers.cpp 8 If we want to iterate through all the items with the same value, we can use \l{QMapIterator::findNext()}{findNext()} @@ -426,7 +426,7 @@ Here's an example where we remove all the items with a particular value: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 9 + \snippet doc/src/snippets/code/doc_src_containers.cpp 9 \section2 STL-Style Iterators @@ -473,7 +473,7 @@ Here's a typical loop for iterating through all the elements of a QList<QString> in order and converting them to lowercase: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 10 + \snippet doc/src/snippets/code/doc_src_containers.cpp 10 Unlike \l{Java-style iterators}, STL-style iterators point directly at items. The begin() function of a container returns an @@ -493,7 +493,7 @@ decrement the iterator \e before we access the item. This requires a \c while loop: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 11 + \snippet doc/src/snippets/code/doc_src_containers.cpp 11 In the code snippets so far, we used the unary \c * operator to retrieve the item (of type QString) stored at a certain iterator @@ -504,7 +504,7 @@ For read-only access, you can use const_iterator, constBegin(), and constEnd(). For example: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 12 + \snippet doc/src/snippets/code/doc_src_containers.cpp 12 The following table summarizes the STL-style iterators' API: @@ -536,7 +536,7 @@ value() function to retrieve the value. For example, here's how we would print all items in a QMap to the console: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 13 + \snippet doc/src/snippets/code/doc_src_containers.cpp 13 Thanks to \l{implicit sharing}, it is very inexpensive for a function to return a container per value. The Qt API contains @@ -545,7 +545,7 @@ using an STL iterator, you should always take a copy of the container and iterate over the copy. For example: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 14 + \snippet doc/src/snippets/code/doc_src_containers.cpp 14 This problem doesn't occur with functions that return a const or non-const reference to a container. @@ -567,35 +567,35 @@ statement. For example, here's how to use \c foreach to iterate over a QLinkedList<QString>: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 15 + \snippet doc/src/snippets/code/doc_src_containers.cpp 15 The \c foreach code is significantly shorter than the equivalent code that uses iterators: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 16 + \snippet doc/src/snippets/code/doc_src_containers.cpp 16 Unless the data type contains a comma (e.g., \c{QPair<int, int>}), the variable used for iteration can be defined within the \c foreach statement: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 17 + \snippet doc/src/snippets/code/doc_src_containers.cpp 17 And like any other C++ loop construct, you can use braces around the body of a \c foreach loop, and you can use \c break to leave the loop: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 18 + \snippet doc/src/snippets/code/doc_src_containers.cpp 18 With QMap and QHash, \c foreach accesses the value component of the (key, value) pairs. If you want to iterate over both the keys and the values, you can use iterators (which are fastest), or you can write code like this: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 19 + \snippet doc/src/snippets/code/doc_src_containers.cpp 19 For a multi-valued map: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 20 + \snippet doc/src/snippets/code/doc_src_containers.cpp 20 Qt automatically takes a copy of the container when it enters a \c foreach loop. If you modify the container as you are @@ -611,12 +611,12 @@ In addition to \c foreach, Qt also provides a \c forever pseudo-keyword for infinite loops: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 21 + \snippet doc/src/snippets/code/doc_src_containers.cpp 21 If you're worried about namespace pollution, you can disable these macros by adding the following line to your \c .pro file: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 22 + \snippet doc/src/snippets/code/doc_src_containers.cpp 22 \section1 Other Container-Like Classes @@ -736,7 +736,7 @@ Consider the following code, which builds a QString from another QString: - \snippet doc/src/snippets/code/doc_src_containers.qdoc 23 + \snippet doc/src/snippets/code/doc_src_containers.cpp 23 We build the string \c out dynamically by appending one character to it at a time. Let's assume that we append 15000 characters to diff --git a/doc/src/frameworks-technologies/dbus-adaptors.qdoc b/doc/src/frameworks-technologies/dbus-adaptors.qdoc index 7494f2d..82545db 100644 --- a/doc/src/frameworks-technologies/dbus-adaptors.qdoc +++ b/doc/src/frameworks-technologies/dbus-adaptors.qdoc @@ -85,14 +85,14 @@ using an adaptor. A sample usage of QDBusAbstractAdaptor is as follows: - \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.cpp 0 The code above would create an interface that could be represented more or less in the following canonical representation: - \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.cpp 1 This adaptor could be used in the application's main function as follows - \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 2 + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.cpp 2 Break-down analysis: \tableofcontents @@ -100,7 +100,7 @@ \section1 The header The header of the example is: - \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 3 + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.cpp 3 The code does the following: \list @@ -112,10 +112,10 @@ \section1 The properties The properties are declared as follows: - \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 4 + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.cpp 4 And are implemented as follows: - \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 5 + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.cpp 5 The code declares three properties: one of them is a read-write property called "caption" of string type. The other two are read-only, also of the string type. @@ -129,7 +129,7 @@ \section1 The constructor The constructor: - \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 6 + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.cpp 6 The constructor does the following: \list @@ -149,7 +149,7 @@ \section1 Slots/methods The public slots in the example (which will be exported as D-Bus methods) are the following: - \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 7 + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.cpp 7 This snippet of code defines 4 methods with different properties each: \list 1 @@ -176,7 +176,7 @@ \section1 Signals The signals in this example are defined as follows: - \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 8 + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.cpp 8 However, signal definition isn't enough: signals have to be emitted. One simple way of emitting signals is to connect another signal to them, so that Qt's signal handling system chains them @@ -187,7 +187,7 @@ When simple signal-to-signal connection isn't enough, one can use a private slot do do some work. This is what was done for the mainWindowHasFocus signal: - \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 9 + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.cpp 9 This private slot (which will not be exported as a method via D-Bus) was connected to the \c focusChanged signal in the adaptor's constructor. It is therefore able to shape the @@ -291,7 +291,7 @@ \l{QDBusMessage::setDelayedReply()}{QDBusMessage::setDelayedReply(true)} that the response will be sent later. - \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 10 + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.cpp 10 The use of \l{QDBusConnection::send()}{QDBusConnection::sessionBus().send(data->reply)} @@ -303,7 +303,7 @@ using the \c QDBusMessage object that was obtained. In our example, the reply code could be something as follows: - \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 11 + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.cpp 11 As can be seen in the example, when a delayed reply is in place, the return value(s) from the slot will be ignored by QtDBus. They @@ -473,7 +473,7 @@ You can use this macro in your own adaptors by placing it before your method's return value (which must be "void") in the class declaration, as shown in the example: - \snippet doc/src/snippets/code/doc_src_qdbusadaptors.qdoc 12 + \snippet doc/src/snippets/code/doc_src_qdbusadaptors.cpp 12 Its presence in the method implementation (outside the class declaration) is optional. diff --git a/doc/src/frameworks-technologies/graphicsview.qdoc b/doc/src/frameworks-technologies/graphicsview.qdoc index f689446..1903df5 100644 --- a/doc/src/frameworks-technologies/graphicsview.qdoc +++ b/doc/src/frameworks-technologies/graphicsview.qdoc @@ -95,7 +95,7 @@ descending stacking order (i.e., the first returned item is topmost, and the last item is bottom-most). - \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 0 + \snippet doc/src/snippets/code/doc_src_graphicsview.cpp 0 QGraphicsScene's event propagation architecture schedules scene events for delivery to items, and also manages propagation between items. If @@ -126,7 +126,7 @@ enable OpenGL support, you can set a QGLWidget as the viewport by calling QGraphicsView::setViewport(). - \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 1 + \snippet doc/src/snippets/code/doc_src_graphicsview.cpp 1 The view receives input events from the keyboard and mouse, and translates these to scene events (converting the coordinates used @@ -333,7 +333,7 @@ Here is an example of how to implement zoom and rotate slots in a subclass of QGraphicsView: - \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 2 + \snippet doc/src/snippets/code/doc_src_graphicsview.cpp 2 The slots could be connected to \l{QToolButton}{QToolButtons} with \l{QAbstractButton::autoRepeat}{autoRepeat} enabled. @@ -353,7 +353,7 @@ a QPainter to either of the rendering functions. This example shows how to print the whole scene into a full page, using QPrinter. - \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 3 + \snippet doc/src/snippets/code/doc_src_graphicsview.cpp 3 The difference between the scene and view rendering functions is that one operates in scene coordinates, and the other in view coordinates. @@ -364,7 +364,7 @@ is to render the exact contents of the viewport using the provided painter. - \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 4 + \snippet doc/src/snippets/code/doc_src_graphicsview.cpp 4 When the source and target areas' sizes do not match, the source contents are stretched to fit into the target area. By passing a @@ -390,7 +390,7 @@ so in mousePressEvent() or mouseMoveEvent(), you can get the originating widget pointer from the event. For example: - \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 5 + \snippet doc/src/snippets/code/doc_src_graphicsview.cpp 5 To intercept drag and drop events for the scene, you reimplement QGraphicsScene::dragEnterEvent() and whichever event handlers your @@ -449,7 +449,7 @@ Example: - \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 6 + \snippet doc/src/snippets/code/doc_src_graphicsview.cpp 6 \section2 Item Groups diff --git a/doc/src/frameworks-technologies/implicit-sharing.qdoc b/doc/src/frameworks-technologies/implicit-sharing.qdoc index 8938d9e..46567e9 100644 --- a/doc/src/frameworks-technologies/implicit-sharing.qdoc +++ b/doc/src/frameworks-technologies/implicit-sharing.qdoc @@ -109,7 +109,7 @@ data in all member functions that change the internal data. Code fragment: - \snippet doc/src/snippets/code/doc_src_groups.qdoc 0 + \snippet doc/src/snippets/code/doc_src_groups.cpp 0 \section1 List of Classes @@ -124,7 +124,7 @@ concern for the copying overhead. Example: - \snippet doc/src/snippets/code/doc_src_groups.qdoc 1 + \snippet doc/src/snippets/code/doc_src_groups.cpp 1 In this example, \c p1 and \c p2 share data until QPainter::begin() is called for \c p2, because painting a pixmap will modify it. diff --git a/doc/src/frameworks-technologies/model-view-programming.qdoc b/doc/src/frameworks-technologies/model-view-programming.qdoc index 92067b9..58b51e5 100644 --- a/doc/src/frameworks-technologies/model-view-programming.qdoc +++ b/doc/src/frameworks-technologies/model-view-programming.qdoc @@ -32,7 +32,7 @@ /*! \page model-view-programming.html - \ingroup qt-basic-concepts + \ingroup qt-basic-concepts \title Model/View Programming \brief A guide to Qt's extensible model/view architecture. @@ -328,7 +328,7 @@ contain a pointer to the model that created them, and this prevents confusion when working with more than one model. - \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 0 + \snippet doc/src/snippets/code/doc_src_model-view-programming.cpp 0 Model indexes provide \e temporary references to pieces of information, and can be used to retrieve or modify data via the model. Since models may @@ -355,7 +355,7 @@ item by specifying its row and column numbers to the model, and we receive an index that represents the item: - \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 1 + \snippet doc/src/snippets/code/doc_src_model-view-programming.cpp 1 Models that provide interfaces to simple, single level data structures like lists and tables do not need any other information to be provided but, as @@ -371,7 +371,7 @@ index that refers to an item of data by passing the relevant row and column numbers to the model. - \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 2 + \snippet doc/src/snippets/code/doc_src_model-view-programming.cpp 2 Top level items in a model are always referenced by specifying \c QModelIndex() as their parent item. This is discussed in the next @@ -392,7 +392,7 @@ about the item's parent. Outside the model, the only way to refer to an item is through a model index, so a parent model index must also be given: - \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 3 + \snippet doc/src/snippets/code/doc_src_model-view-programming.cpp 3 \table \row \i \inlineimage modelview-treemodel.png @@ -403,12 +403,12 @@ Items "A" and "C" are represented as top-level siblings in the model: - \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 4 + \snippet doc/src/snippets/code/doc_src_model-view-programming.cpp 4 Item "A" has a number of children. A model index for item "B" is obtained with the following code: - \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 5 + \snippet doc/src/snippets/code/doc_src_model-view-programming.cpp 5 \endtable \section3 Item roles @@ -423,7 +423,7 @@ corresponding to the item, and by specifying a role to obtain the type of data we want: - \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 6 + \snippet doc/src/snippets/code/doc_src_model-view-programming.cpp 6 \table \row \i \inlineimage modelview-roles.png diff --git a/doc/src/frameworks-technologies/phonon.qdoc b/doc/src/frameworks-technologies/phonon.qdoc index 1456eae6..9eb56ea 100644 --- a/doc/src/frameworks-technologies/phonon.qdoc +++ b/doc/src/frameworks-technologies/phonon.qdoc @@ -165,7 +165,7 @@ The \c .pro file for a project needs the following line to be added: - \snippet doc/src/snippets/code/doc_src_phonon.qdoc 0 + \snippet doc/src/snippets/code/doc_src_phonon.pro 0 Phonon comes with several widgets that provide functionality commonly associated with multimedia players - notably SeekSlider diff --git a/doc/src/frameworks-technologies/plugins-howto.qdoc b/doc/src/frameworks-technologies/plugins-howto.qdoc index b332d57..15b1547 100644 --- a/doc/src/frameworks-technologies/plugins-howto.qdoc +++ b/doc/src/frameworks-technologies/plugins-howto.qdoc @@ -109,12 +109,12 @@ straightforward, here is the class definition (\c mystyleplugin.h): - \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 0 + \snippet doc/src/snippets/code/doc_src_plugins-howto.cpp 0 Ensure that the class implementation is located in a \c .cpp file (including the class definition): - \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 1 + \snippet doc/src/snippets/code/doc_src_plugins-howto.cpp 1 (Note that QStylePlugin is case insensitive, and the lower-case version of the key is used in our @@ -127,7 +127,7 @@ you might want to set a style explicitly in code. To apply a style, use code like this: - \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 2 + \snippet doc/src/snippets/code/doc_src_plugins-howto.cpp 2 Some plugin classes require additional functions to be implemented. See the class documentation for details of the @@ -284,12 +284,12 @@ the required plugins to your build using \c QTPLUGIN. For example, in your \c main.cpp: - \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 4 + \snippet doc/src/snippets/code/doc_src_plugins-howto.cpp 4 In the \c .pro file for your application, you need the following entry: - \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 5 + \snippet doc/src/snippets/code/doc_src_plugins-howto.pro 5 It is also possible to create your own static plugins, by following these steps: diff --git a/doc/src/frameworks-technologies/qthelp.qdoc b/doc/src/frameworks-technologies/qthelp.qdoc index 42bc482..f4d75b6 100644 --- a/doc/src/frameworks-technologies/qthelp.qdoc +++ b/doc/src/frameworks-technologies/qthelp.qdoc @@ -218,7 +218,7 @@ we get the actual help contents by calling fileData() and display the document to the user. - \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 6 + \snippet doc/src/snippets/code/doc_src_qthelp.cpp 6 For further information on how to use the API, have a look at the QHelpEngine class reference. diff --git a/doc/src/frameworks-technologies/richtext.qdoc b/doc/src/frameworks-technologies/richtext.qdoc index 089f84d..313cf46 100644 --- a/doc/src/frameworks-technologies/richtext.qdoc +++ b/doc/src/frameworks-technologies/richtext.qdoc @@ -145,11 +145,11 @@ Although QTextEdit makes it easy to display and edit rich text, documents can also be used independently of any editor widget, for example: - \snippet doc/src/snippets/code/doc_src_richtext.qdoc 0 + \snippet doc/src/snippets/code/doc_src_richtext.cpp 0 Alternatively, they can be extracted from an existing editor: - \snippet doc/src/snippets/code/doc_src_richtext.qdoc 1 + \snippet doc/src/snippets/code/doc_src_richtext.cpp 1 This flexibility enables applications to handle multiple rich text documents without the overhead of multiple editor widgets, or requiring @@ -728,24 +728,24 @@ A text editor widget can be constructed and used to display HTML in the following way: - \snippet doc/src/snippets/code/doc_src_richtext.qdoc 2 + \snippet doc/src/snippets/code/doc_src_richtext.cpp 2 By default, the text editor contains a document with a root frame, inside which is an empty text block. This document can be obtained so that it can be modified directly by the application: - \snippet doc/src/snippets/code/doc_src_richtext.qdoc 3 + \snippet doc/src/snippets/code/doc_src_richtext.cpp 3 The text editor's cursor may also be used to edit a document: - \snippet doc/src/snippets/code/doc_src_richtext.qdoc 4 + \snippet doc/src/snippets/code/doc_src_richtext.cpp 4 Although a document can be edited using many cursors at once, a QTextEdit only displays a single cursor at a time. Therefore, if we want to update the editor to display a particular cursor or its selection, we need to set the editor's cursor after we have modified the document: - \snippet doc/src/snippets/code/doc_src_richtext.qdoc 5 + \snippet doc/src/snippets/code/doc_src_richtext.cpp 5 \section1 Selecting Text @@ -833,7 +833,7 @@ We give an example of the latter technique from the list. We assume that the text edit is visible. - \snippet doc/src/snippets/code/doc_src_richtext.qdoc 6 + \snippet doc/src/snippets/code/doc_src_richtext.cpp 6 \omit Ideas for other sections: diff --git a/doc/src/frameworks-technologies/unicode.qdoc b/doc/src/frameworks-technologies/unicode.qdoc index b4a9347..d2a6500 100644 --- a/doc/src/frameworks-technologies/unicode.qdoc +++ b/doc/src/frameworks-technologies/unicode.qdoc @@ -125,12 +125,12 @@ QString provides implicit casting from \c{const char *} so that things like - \snippet doc/src/snippets/code/doc_src_unicode.qdoc 0 + \snippet doc/src/snippets/code/doc_src_unicode.cpp 0 will work. There is also a function, QObject::tr(), that provides translation support, like this: - \snippet doc/src/snippets/code/doc_src_unicode.qdoc 1 + \snippet doc/src/snippets/code/doc_src_unicode.cpp 1 QObject::tr() maps from \c{const char *} to a Unicode string, and uses installable QTranslator objects to do the mapping. @@ -151,11 +151,11 @@ fast functions for mapping to and from them. For example, to open an application's icon one might do this: - \snippet doc/src/snippets/code/doc_src_unicode.qdoc 2 + \snippet doc/src/snippets/code/doc_src_unicode.cpp 2 or - \snippet doc/src/snippets/code/doc_src_unicode.qdoc 3 + \snippet doc/src/snippets/code/doc_src_unicode.cpp 3 Regarding output, Qt will do a best-effort conversion from Unicode to whatever encoding the system and fonts provide. diff --git a/doc/src/getting-started/examples.qdoc b/doc/src/getting-started/examples.qdoc index ad97836..ede8a5b 100644 --- a/doc/src/getting-started/examples.qdoc +++ b/doc/src/getting-started/examples.qdoc @@ -699,6 +699,7 @@ /*! \page examples-linguist.html \ingroup all-examples + \ingroup internationalization \title Qt Linguist Examples \brief Using Qt Linguist to internationalize your Qt application. diff --git a/doc/src/getting-started/gettingstartedqml.qdoc b/doc/src/getting-started/gettingstartedqml.qdoc index ccb9771..8054fc8 100644 --- a/doc/src/getting-started/gettingstartedqml.qdoc +++ b/doc/src/getting-started/gettingstartedqml.qdoc @@ -631,7 +631,7 @@ Now that we have our text editor layout, we may now implement the text editor functionalities in C++. Using QML with C++ enables us to create our application logic using Qt. We can create a QML context in a C++ application using the - \l {Using QML in C++ Applications}{Qt's Declarative} classes and display the QML + \l {Using QML Bindings in C++ Applications}{Qt's Declarative} classes and display the QML elements using a Graphics Scene. Alternatively, we can export our C++ code into a plugin that the \l {QML Viewer}{qmlviewer} tool can read. For our application, we shall implement the load and save functions in C++ and export it as a plugin. diff --git a/doc/src/getting-started/how-to-learn-qt.qdoc b/doc/src/getting-started/how-to-learn-qt.qdoc index 239c8a1..8d9508b 100644 --- a/doc/src/getting-started/how-to-learn-qt.qdoc +++ b/doc/src/getting-started/how-to-learn-qt.qdoc @@ -51,7 +51,7 @@ key overviews to deepen your understanding of Qt: The Qt \l{Object Model} and \l{Signals and Slots}. - \div{float-left} + \div {class="float-left"} \inlineimage qtdemo-small.png \enddiv diff --git a/doc/src/getting-started/installation.qdoc b/doc/src/getting-started/installation.qdoc index 6d0256e..26ccf88 100644 --- a/doc/src/getting-started/installation.qdoc +++ b/doc/src/getting-started/installation.qdoc @@ -1009,78 +1009,113 @@ We hope you will enjoy using Qt. \image x11_dependencies.png Qt for X11 Dependencies - \raw HTML - <style type="text/css" id="colorstyles"> - #QtGuiColor { background-color: #98fd00; color: black } - #QtCoreColor { background-color: #9c9cff; color: black } - #DefaultColor { background-color: #f6f6dc; color: black } - #FreetypeColor { background-color: #e6e6fa; color: black } - #GLColor { background-color: #ffc0cb; color: black } - #PthreadColor { background-color: #bdb76b; color: black } - #OptionalColor { background-color: #cae1ff; color: black } - #SMColor { background-color: #c2fafa; color: black } - #MiscColor { background-color: #f0f9ff; color: black } - #GlibColor { background-color: #b3b3b3; color: black } - </style> - \endraw - The QtGui module and the QtCore module, which provides the non-GUI features required by QtGui, depend on the libraries described in the following table. To build Qt from its source code, you will also need to install the development packages for these libraries for your system. - \raw HTML - <table class="generic"> - <thead><tr class="qt-style topAlign"><th>Name</th><th>Library</th><th>Notes</th><th>Configuration options</th><th>Minimum working version - <tr id="OptionalColor"> - <td> XRender </td><td> libXrender </td><td> X Rendering Extension; used for anti-aliasing</td> - <td><tt>-xrender</tt> or auto-detected</td><td>0.9.0</td> - </tr><tr id="OptionalColor"> - <td> Xrandr </td><td> libXrandr </td><td> X Resize and Rotate Extension</td> - <td><tt>-xrandr</tt> or auto-detected</td><td>1.0.2</td> - </tr><tr id="OptionalColor"> - <td> Xcursor </td><td> libXcursor </td><td> X Cursor Extension</td> - <td><tt>-xcursor</tt> or auto-detected</td><td>1.1.4</td> - </tr><tr id="OptionalColor"> - <td> Xfixes </td><td> libXfixes </td><td> X Fixes Extension</td> - <td><tt>-xfixes</tt> or auto-detected</td><td>3.0.0</td> - </tr><tr id="OptionalColor"> - <td> Xinerama </td><td> libXinerama </td><td> Multi-head support</td> - <td><tt>-xinerama</tt> or auto-detected</td><td>1.1.0</td> - - </tr><tr id="OptionalColor"> - <td> Fontconfig </td><td> libfontconfig </td><td> Font customization and configuration</td> - <td><tt>-fontconfig</tt> or auto-detected</td><td>2.1</td> - </tr><tr id="OptionalColor"> - <td> FreeType </td><td> libfreetype </td><td> Font engine</td> - <td></td><td>2.1.3</td> - - </tr><tr id="DefaultColor"> - <td> Xi </td><td> libXi </td><td> X11 Input Extensions</td> - <td><tt>-xinput</tt> or auto-detected</td><td>1.3.0</td> - </tr><tr id="DefaultColor"> - <td> Xt </td><td> libXt </td><td> Xt Intrinsics</td><td></td><td>0.99</td> - </tr><tr id="DefaultColor"> - <td> Xext </td><td> libXext </td><td> X Extensions</td><td></td><td>6.4.3</td> - </tr><tr id="DefaultColor"> - <td> X11 </td><td> libX11 </td><td> X11 Client-Side Library</td><td></td><td>6.2.1</td> - - </tr><tr id="SMColor"> - <td> SM </td><td> libSM </td><td> X Session Management</td> - <td><tt>-sm</tt> or auto-detected</td><td>6.0.4</td> - </tr><tr id="SMColor"> - <td> ICE </td><td> libICE </td><td> Inter-Client Exchange</td> - <td><tt>-sm</tt> or auto-detected</td><td>6.3.5</td> - - </tr><tr id="GlibColor"> - <td> glib </td><td> libglib-2.0 </td><td> Common event loop handling</td> - <td><tt>-glib</tt> or auto-detected</td><td>2.8.3</td> - </tr><tr id="PthreadColor"> - <td> pthread </td><td> libpthread </td><td> Multithreading</td> - <td></td><td>2.3.5</td> - </tr></th></tr></thead> - </table> - \endraw + \table 100% + \header + \o Name + \o Library + \o Notes + \o Configuration options + \o Minimum working version + \row {id="OptionalColor"} + \o XRender + \o libXrender + \o X Rendering Extension; used for anti-aliasing + \o \tt{-xrender} or auto-detected + \o 0.9.0 + \row {id="OptionalColor"} + \o Xrandr + \o libXrandr + \o X Resize and Rotate Extension + \o \tt{-xrandr} or auto-detected + \o 1.0.2 + \row {id="OptionalColor"} + \o Xcursor + \o libXcursor + \o X Cursor Extension + \o \tt{-xcursor} or auto-detected + \o 1.1.4 + \row {id="OptionalColor"} + \o Xfixes + \o libXfixes + \o X Fixes Extension + \o \tt{-xfixes} or auto-detected + \o 3.0.0 + \row {id="OptionalColor"} + \o Xinerama + \o libXinerama + \o Multi-head support + \o \tt{-xinerama} or auto-detected + \o 1.1.0 + + \row {id="OptionalColor"} + \o Fontconfig + \o libfontconfig + \o Font customization and configuration + \o \tt{-fontconfig} or auto-detected + \o 2.1 + \row {id="OptionalColor"} + \o FreeType + \o libfreetype + \o Font engine + \o + \o 2.1.3 + + \row {id="DefaultColor"} + \o Xi + \o libXi + \o X11 Input Extensions + \o \tt{-xinput} or auto-detected + \o 1.3.0 + \row {id="DefaultColor"} + \o Xt + \o libXt + \o Xt Intrinsics + \o + \o 0.99 + \row {id="DefaultColor"} + \o Xext + \o libXext + \o X Extensions + \o + \o 6.4.3 + \row {id="DefaultColor"} + \o X11 + \o libX11 + \o X11 Client-Side Library + \o + \o 6.2.1 + + \row {id="SMColor"} + \o SM + \o libSM + \o X Session Management + \o \tt{-sm} or auto-detected + \o 6.0.4 + \row {id="SMColor"} + \o ICE + \o libICE + \o Inter-Client Exchange + \o \tt{-sm} or auto-detected + \o 6.3.5 + + \row {id="GlibColor"} + \o glib + \o libglib-2.0 + \o Common event loop handling + \o \tt{-glib} or auto-detected + \o 2.8.3 + \row {id="PthreadColor"} + \o pthread + \o libpthread + \o Multithreading + \o + \o 2.3.5 + \endtable \note You must compile with XRender support to get alpha transparency support for pixmaps and images. @@ -1142,7 +1177,7 @@ We hope you will enjoy using Qt. \brief Setting up the Windows CE environment for Qt. \previouspage General Qt Requirements - Qt is known to work with Visual Studio 2005/2008 and the following SDKs for + Qt is known to work with Visual Studio 2005/2008/2010 and the following SDKs for Windows CE development on Windows XP and Windows Vista: \list @@ -1180,14 +1215,37 @@ We hope you will enjoy using Qt. \endlist \endtable - Device manufacturers may prefer to make their own customized version of Windows CE using Platform Builder. In order for Qt for Windows CE to support a custom SDK, a build specification needs to be created. More information on Windows CE Customization can be found \l{Windows CE - Working with Custom SDKs}{here}. - \sa {Known Issues} + \section3 Requirements + \list + \o Development environment: + \list + \o Microsoft Visual Studio 2005 (Standard Edition) or higher + \o ActivePerl + \endlist + \o Footprint + \list + \o Lean configuration - 4.8 MB + \o Full configuration - 8.4 MB + \endlist + \o Operating Systems + \list + \o Windows CE 5 or higher + \o Windows Mobile 5 or higher + \endlist + \o Hardware Platform + \list + \o Supported on ARM, x86 + \o (Compiles on SH4 and MIPS) + \endlist + \endlist + + \sa {Known Issues} */ /*! @@ -1332,7 +1390,7 @@ We hope you will enjoy using Qt. load those that have a matching <key>. \o \row \o \c {-release } \o Compile and link Qt with debugging turned off. \o \row \o \c {-debug } \o Compile and link Qt with debugging turned on. - \o Defualt value. + \o Default value. \row \o \c {-debug-and-release} \o Compile and link two Qt libraries, with and without debugging turned on. \o This option denotes a default value and needs to be evaluated. If the evaluation succeeds, the @@ -1343,28 +1401,28 @@ We hope you will enjoy using Qt. of Qt. \o \row \o \c {-developer-build} \o Compile and link Qt with Qt developer options including auto-tests exporting) \o - \row \o \c {-shared} \o Create and use shared Qt libraries. \o Defualt + \row \o \c {-shared} \o Create and use shared Qt libraries. \o Default value. \row \o \c {-static} \o Create and use static Qt libraries. \o \row \o \c {-ltcg} \o Use Link Time Code Generation. \o Apply to release builds only. - \row \o \c {-no-ltcg} \o Do not use Link Time Code Generation. \o Defualt + \row \o \c {-no-ltcg} \o Do not use Link Time Code Generation. \o Default value. \row \o \c {-no-fast} \o Configure Qt normally by generating Makefiles for - all project files. \o Defualt value. + all project files. \o Default value. \row \o \c {-fast} \o Configure Qt quickly by generating Makefiles only for library and subdirectory targets. \o All other Makefiles are created as wrappers which will in turn run qmake. \row \o \c {-no-exceptions} \o Disable exceptions on platforms that support it. \o \row \o \c {-exceptions} \o Enable exceptions on platforms that support it. - \o Defualt value. + \o Default value. \row \o \c {-no-accessibility} \o Do not compile Windows Active Accessibility support. \o \row \o \c {-accessibility} \o Compile Windows Active Accessibility - support. \o Defualt value. + support. \o Default value. \row \o \c {-no-stl} \o Do not compile STL support. \o - \row \o \c {-stl} \o Compile STL support. \o Defualt value. + \row \o \c {-stl} \o Compile STL support. \o Default value. \row \o \c {-no-sql-<driver>} \o Disable SQL <driver> entirely, by default none are turned on. \o \row \o \c {-qt-sql-<driver>} \o Enable a SQL <driver> in the Qt Library. @@ -1380,14 +1438,14 @@ We hope you will enjoy using Qt. version. \o Available values for <api>: desktop - Enable support for Desktop OpenGL (Default), es1 - Enable support for OpenGL ES Common Profile, es2 - Enable support for OpenGL ES 2.0. - \row \o \c {-no-openvg} \o Disables OpenVG functionality \o Defualt value. + \row \o \c {-no-openvg} \o Disables OpenVG functionality \o Default value. \row \o \c {-openvg} \o Enables OpenVG functionality \o Requires EGL support, typically supplied by an OpenGL or other graphics implementation. \row \o \c {-platform <spec> } \o The operating system and compiler you are building on. \o The default value is %QMAKESPEC%. \row \o \c {-xplatform <spec> } \o The operating system and compiler you - are cross compiling to. \o See the README file for a list of supported + are cross compiling for. \o See the README file for a list of supported operating systems and compilers. \row \o \c {-qtnamespace <namespace>} \o Wraps all Qt library code in 'namespace name {..} \o @@ -1399,7 +1457,7 @@ We hope you will enjoy using Qt. \row \o \c {-L <librarypath>} \o Add an explicit library path. \o \row \o \c {-l <libraryname>} \o Add an explicit library name, residing in a librarypath. \o - \row \o \c {-graphicssystem <sys>} \o Specify which graphicssystem should + \row \o \c {-graphicssystem <sys>} \o Specify which graphics system should be used. \o Available values for <sys>: * raster - Software rasterizer, opengl - Using OpenGL acceleration, experimental!, openvg - Using OpenVG acceleration, experimental! @@ -1428,7 +1486,7 @@ We hope you will enjoy using Qt. succeeds, the feature is included. \row \o \c {-qt-libmng} \o Use the libmng bundled with Qt. \o \row \o \c {-system-libmng} \o Use libmng from the operating system. - \o See See http://www.libmng.com + \o See http://www.libmng.com \row \o \c {-no-libtiff} \o Do not compile TIFF support. \o This option denotes a default value and needs to be evaluated. If the evaluation succeeds, the feature is included. @@ -1450,10 +1508,10 @@ We hope you will enjoy using Qt. \header \o Option \o Description \o Note \row \o \c {-no-dsp} \o Do not generate VC++ .dsp files. \o \row \o \c {-dsp} \o Generate VC++ .dsp files, only if spec "win32-msvc". - \o Defualt value. + \o Default value. \row \o \c {-no-vcproj} \o Do not generate VC++ .vcproj files. \o \row \o \c {-vcproj} \o Generate VC++ .vcproj files, only if platform - "win32-msvc.net". \o Defualt value. + "win32-msvc.net". \o Default value. \row \o \c {-no-incredibuild-xge} \o Do not add IncrediBuild XGE distribution commands to custom build steps. \o \row \o \c {-incredibuild-xge} \o Add IncrediBuild XGE distribution commands @@ -1464,14 +1522,14 @@ We hope you will enjoy using Qt. If the evaluation succeeds, the feature is included. \row \o \c {-no-plugin-manifests} \o Do not embed manifests in plugins. \o \row \o \c {-plugin-manifests} \o Embed manifests in plugins. - \o Defualt value. + \o Default value. \row \o \c {-no-qmake} \o Do not compile qmake. \o - \row \o \c {-qmake} \o Compile qmake. \o Defualt value + \row \o \c {-qmake} \o Compile qmake. \o Default value \row \o \c {-dont-process} \o Do not generate Makefiles/Project files. This will override -no-fast if specified. \o - \row \o \c {-process} \o Generate Makefiles/Project files. \o Defualt value. + \row \o \c {-process} \o Generate Makefiles/Project files. \o Default value. \row \o \c {-no-rtti} \o Do not compile runtime type information. \o - \row \o \c {-rtti} \o Compile runtime type information. \o Defualt value. + \row \o \c {-rtti} \o Compile runtime type information. \o Default value. \row \o \c {-no-mmx} \o Do not compile with use of MMX instructions \o \row \o \c {-mmx} \o Compile with use of MMX instructions \o This option denotes a default value and needs to be evaluated. If the evaluation @@ -1506,9 +1564,9 @@ We hope you will enjoy using Qt. \row \o \c {-no-phonon-backend} \o Do not compile the platform-specific Phonon backend-plugin \o \row \o \c {-phonon-backend} \o Compile in the platform-specific Phonon - backend-plugin \o Defualt value. + backend-plugin \o Default value. \row \o \c {-no-multimedia} \o Do not compile the multimedia module \o - \row \o \c {-multimedia} \o Compile in multimedia module \o Defualt value. + \row \o \c {-multimedia} \o Compile in multimedia module \o Default value. \row \o \c {-no-audio-backend} \o Do not compile in the platform audio backend into QtMultimedia \o \row \o \c {-audio-backend} \o Compile in the platform audio backend into @@ -1536,7 +1594,7 @@ We hope you will enjoy using Qt. \row \o \c {-no-declarative-debug} \o Do not build the declarative debugging support \o \row \o \c {-declarative-debug} \o Build the declarative debugging support - \o Defualt value. + \o Default value. \row \o \c {-arch <arch>} \o Specify an architecture. \o Available values for <arch>: * windows, windowsce, symbian, boundschecker, generic. \row \o \c {-no-style-<style>} \o Disable <style> entirely. \o @@ -1547,9 +1605,9 @@ We hope you will enjoy using Qt. \row \o \c {-no-native-gestures} \o Do not use native gestures on Windows 7. \o \row \o \c {-native-gestures} \o Use native gestures on Windows 7. - \o Defualt value. + \o Default value. \row \o \c {-no-mp} \o Do not use multiple processors for compiling with MSVC - \o Defualt value. + \o Default value. \row \o \c {-mp} \o Use multiple processors for compiling with MSVC (-MP) \o \row \o \c {-loadconfig <config>} \o Run configure with the parameters from file configure_<config>.cache. \o @@ -1566,7 +1624,7 @@ We hope you will enjoy using Qt. for Qt for Windows CE on Arm only. This option denotes a default value and needs to be evaluated. If the evaluation succeeds, the feature is included. \row \o \c {-no-crt} \o Do not add the C runtime to default deployment rules. - \o Defualt value. + \o Default value. \row \o \c {-qt-crt} \o Qt identifies C runtime during project generation \o \row \o \c {-crt <path>} \o Specify path to C runtime used for project generation. \o @@ -1576,20 +1634,20 @@ We hope you will enjoy using Qt. succeeds, the feature is included. \row \o \c {-signature <file>} \o Use file for signing the target project \o \row \o \c {-phonon-wince-ds9} \o Enable Phonon Direct Show 9 backend for - Windows CE \o Defualt value + Windows CE \o Default value \endtable \section2 Qt for Symbian OS only: \table \header \o Option \o Description \o Note \row \o \c {-no-freetype} \o Do not compile in Freetype2 support. - \o Defualt value. + \o Default value. \row \o \c {-qt-freetype} \o Use the libfreetype bundled with Qt. \o \row \o \c {-fpu <flags>} \o VFP type on ARM, supported options: softvfp(default) |vfpv2 | softvfp+vfpv2 \o \row \o \c {-no-s60} \o Do not compile in S60 support. \o \row \o \c {-s60} \o Compile with support for the S60 UI Framework - \o Defualt value. + \o Default value. \row \o \c {-no-usedeffiles} \o Disable the usage of DEF files. \o \row \o \c {-usedeffiles} \o Enable the usage of DEF files. \o \endtable diff --git a/doc/src/getting-started/tutorials.qdoc b/doc/src/getting-started/tutorials.qdoc index 5cde056..9fc6699 100644 --- a/doc/src/getting-started/tutorials.qdoc +++ b/doc/src/getting-started/tutorials.qdoc @@ -61,7 +61,7 @@ \o{2,1} \l{A Quick Start to Qt Designer}{\bold{Qt Designer}} \o{2,1} \l{Qt Linguist Manual: Programmers#Tutorials}{\bold {Qt Linguist}} \row - \o \image designer-examples.png QtDesigner + \o \image designer-examples.png \o A quick guide through \QD showing the basic steps to create a form with this interactive tool. @@ -72,17 +72,18 @@ tools provided for developers, translators and release managers. - \row +\row \o{2,1} \l{modelview.html}{\bold{ModelView}} - \o{2,1} - + \o{2,1} \l{thread-basics.html}{\bold {Threads}} \row \o \image treeview_sml.png ModelView - \o This tutorial gives an introduction to ModelView programming using the Qt cross-platform framework - \o + This tutorial gives an introduction to ModelView programming using the Qt cross-platform framework + + \o \image threads-examples.png Threads \o - + A short tutorial about thread concepts in general and basic Qt classes to handle threads. + \row \o{2,1} \l{QML Tutorial}{\bold QML Tutorial} \o{2,1} \l{QML Advanced Tutorial}{\bold SameGame} diff --git a/doc/src/howtos/appicon.qdoc b/doc/src/howtos/appicon.qdoc index 86934bc..6d86b22 100644 --- a/doc/src/howtos/appicon.qdoc +++ b/doc/src/howtos/appicon.qdoc @@ -62,7 +62,7 @@ Finally, assuming you are using \c qmake to generate your makefiles, add this line to your \c myapp.pro file: - \snippet doc/src/snippets/code/doc_src_appicon.qdoc 1 + \snippet doc/src/snippets/code/doc_src_appicon.pro 1 Regenerate your makefile and your application. The \c .exe file will now be represented with your icon in Explorer. @@ -96,7 +96,7 @@ if the name of your icon file is \c{myapp.icns}, and your project file is \c{myapp.pro}, add this line to \c{myapp.pro}: - \snippet doc/src/snippets/code/doc_src_appicon.qdoc 2 + \snippet doc/src/snippets/code/doc_src_appicon.pro 2 This will ensure that \c qmake puts your icons in the proper place and creates an \c{Info.plist} entry for the icon. @@ -213,6 +213,6 @@ icon file is \c{myapp.svg}, and your project file is \c{myapp.pro}, add this line to \c{myapp.pro}: - \snippet doc/src/snippets/code/doc_src_appicon.qdoc 5 + \snippet doc/src/snippets/code/doc_src_appicon.pro 5 */ diff --git a/doc/src/howtos/developmentsteps.qdoc b/doc/src/howtos/developmentsteps.qdoc new file mode 100644 index 0000000..e898bf5 --- /dev/null +++ b/doc/src/howtos/developmentsteps.qdoc @@ -0,0 +1,186 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! +\page qtdevelopment-steps.html +\title Qt Development: The Steps from Challenge to Achievement + +\section1 The Challenge + +One day, your boss runs into your cubicle and exclaims to you, "The board blew +millions on a new enterprise HelloWorld application. The new one does not work +and we need a solution quickly before this disaster brings down the company! I'm +putting you in charge of the whole project while I go on vacation -- see you in +2 weeks." + +\section1 Brainstorming Ideas - It is time to play! + +Never one to shy away from a challenge (especially when your job might be on the +line), you first set out try come up with an idea about what your options are. + +You ask around a bit and discover that the broken application was intended to +replace one that has been living on a dusty mainframe for the past 25 years. The +machine is nearing end of life and, rather than invest in replacement hardware +to run a legacy HelloWorld program, the board decided to invest in new software +that could be run on desktops, web, mobile devices and embedded into the +company's main product line -- a pocket size device with a small LCD screen, +which flashes the message "Hello World" every full moon. + +The vendor that was chosen to handle this task was a well known multinational +company that specialized in enterprise CRM/ERP systems. The project missed +several delivery deadlines over a 2 year period, and was 500% over budget. There +was not going to be much margin for error trying to fix the problem, and there +would likely be no budget either. + +You begin researching dozens of possible possible approaches to the problem. One +of the biggest challenges is that there are very few options that will allow you +to create native applications that use the same framework for targeting +\l{qt-creator-configure-target}{multiple platforms}. + +Some years ago you had coded a small desktop application using the Qt framework, +without realizing that it also can be used for targeting the web, mobile devices +and embedded devices. Since that time, Qt has added a new feature called \l{Qt +Quick}, which provides the ability to easily design applications with intuitive, +modern-looking, fluid user interfaces. + +\section1 Creating an Objective + +You quickly realize that you might need two, three, or more interfaces for your +application -- one for each of the target platforms you are aiming for. +Thankfully Qt has options well suited for each of them. + +For your mobile application the choice seems obvious enough. The new Qt Quick +technology looks very promising, but you do not know QML; the declarative +language that helps define the interface in a Qt Quick program. You still want +to give it a try, but worry that you might not have something complete before +your boss returns from vacation in two weeks. You also wonder if Qt Quick is +applicable to desktop and embedded targets -- and then of course there is the +need for something targeting the web. You decide to give Qt Quick a try first +and \l{QML Examples and Demos}{see where it takes you}. + +\section1 Developing Plans + +One thing you realize after reading up on \l{Qt Quick} is that things are very +different from the desktop when designing an interface. Qt Quick doesn't contain +ready made UI 'chrome'; the widgets and other design elements that define the +application interface. A new technology, called Qt Quick Components, looks like +a promising solution, but the components will only be available at a later date. +For now you'll have to come up with something on your own -- but you are keen to +give your design skills a work out, and learning to use Qt Quick seems to be a +great way to do it. + +Not knowing a better place to start, you begin by taking a cue from web design +and plan a wireframe, which helps +\l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-visual-editor.html}{define the application layout}, +content and user interaction. You decide on breaking the field of the screen +space into three roughly equal size parts. There will be one section across the +top, which will span the width of the screen, and two sections in the lower +have, which will be approximately as tall as the top section is wide (when in +portrait mode). + +The top section will be a simple text representation of the phrase "Hello World" +in English. In the lower left you would like to place some kind of audio +playback feature that repeats back the phrase in the top section of the screen. +Finally, in the lower right hand side of the screen will be four links to +similar views for additional languages -- Mandarin Chinese, Brazilian +Portuguese, Arabic, and Russian. When the user clicks one of the links the text +at the top is then translated, and the playback corresponds to the appropriate +language. + +While the wireframe is effective in dealing with one part of the design +challenge, it does not cover visual aspects other than layout and content. This +means that you still need to define colours, white space, and typography (among +other things). This is where a style guide would come in handy, if your company +already had one that is. In the absence of one you decide to again get some +inspiration from the web, and you mimic some of the company's website design +into your application -- a sans-serif font for white text on a blue field across +the top, black text on white for the bottom two sections, and a small company +logo to the left of the "Hello World" message. + + +\section1 Execution: The Coding Begins! + +At long last you sit down to \l{qt-technologies}{implement} your plans and +designs. The first few steps go according to plan, and creating the basic layout +and text goes fairly smoothly -- but you run into a few challenges quite +quickly: + +Devising a user friendly interface to audio playback is not as intuitive as you +first thought. Since there exist a ready made component for +\l{http://doc.qt.nokia.com/qtmobility-1.1.0/qml-multimedia.html}{multimedia}, +you remove the bottom left field and now have the screen split in two. You add +textual links for each of the five target languages, and when the user clicks +one of them the message text changes and the appropriate audio plays back. It is +a small sacrifice to make for now, and you are sure there is a solution to be +found once you have become more proficient with QML. + +The next challenge you run into is that \l{qt-deployment}{deploying} the +application to a Symbian phone is not as clearly understood as you expected. +Again you are sure there is something you are missing, but for the time being +you manually copy the .sis file to the "Installs" directory on the phone +(connected to the development machine by USB) and then install it through the +Application Manager. + +When you finally manage to install the application on the device you notice +something that looks rather peculiar, and something you had not thought of. When +the phone is turned into landscape mode, your text remains at the same absolute +coordinates as when it was in portrait mode. You had not realized you needed to +anchor it in order to achieve the centering you wanted. There was an +\l{qt-testing}{easy fix} for this, but you were glad you saw this earlier rather +than later. + + +\section1 Innovating + +After the ups and downs of learning to develop a basic application +using Qt Quick, you start to see greater possibilities for using Qt technologies +for your current and future projects: + +\list +\o Extending HTML5 based applications that tie Javascript to a Qt C++ back end +using \l{Qt WebKit} +\o An \l{qt-rendering-painting-system}{OpenGL} based UI for embedded platforms +\o \l{Gestures Programming}{Touch} screen support +\o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/location-overview.html}{Location} based applications +\o \l{qt-technologies}{Much, much more} +\endlist + + +\section1 The Achievement + +After your boss returned from vacation you presented him with the finished Qt +Quick application, demonstrating it on both a mobile device as well as desktop +(it happened to work well on both with little modification). You also provided +him a presentation that detailed your road map for taking things to the next +level -- targeting other platforms, such as the web, as well as improving on the +existing application you just completed. + +Even though the final product did not turn out the way you originally planned, +your boss was still sufficiently impressed. Not only was the go ahead given for +future projects, but ramping up a small team of developers and designers was +also suggested to help support your efforts. + +*/ diff --git a/doc/src/howtos/exceptionsafety.qdoc b/doc/src/howtos/exceptionsafety.qdoc index c4b5ebc..b3795d6 100644 --- a/doc/src/howtos/exceptionsafety.qdoc +++ b/doc/src/howtos/exceptionsafety.qdoc @@ -100,8 +100,9 @@ if any allocation fails. Allocations can fail if the system runs out of memory or doesn't have enough continuous memory to allocate the requested size. - Exceptions to that rule are documented. As an example, \l QImage::create() - returns false if not enough memory exists instead of throwing an exception. + Exceptions to that rule are documented. As an example, QImage constructors will + create a \l{QImage::isNull()}{null} image if not enough memory exists instead + of throwing an exception. \section1 Recovering from exceptions diff --git a/doc/src/howtos/qmlbestpractices/qmlbestpractices-coding.qdoc b/doc/src/howtos/qmlbestpractices/qmlbestpractices-coding.qdoc new file mode 100644 index 0000000..246c4e4 --- /dev/null +++ b/doc/src/howtos/qmlbestpractices/qmlbestpractices-coding.qdoc @@ -0,0 +1,97 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qml-best-practices-coding.html +\ingroup qml-best-practices +\contentspage QML Best Practices Guides +\previouspage QML Best Practices Guides +\startpage QML Best Practices Guides +\title QML Best Practices: Coding Conventions + +\brief QML Coding Conventions and Importing Files + +There are many different ways to code using QML. These are a set of +guidelines to help your code look better and consistent. + +\section1 Coding Conventions + +The official QML Coding Conventions may be found at +\l {QML Coding Conventions}. This is the recommended convention that will be +used throughout the QML documentation. + +In addition, Qt's official code style may be found at the \l {Qt Coding Style}. + +\section1 Importing Files into QML + +To import items such as directories, use the "import" keyword, similar to +the way the \c {import QtQuick 1.0} statement is used. + +\snippet doc/src/snippets/declarative/imports/best-practices.qml imports + +To facilitate the import of QML components, it is best to begin the QML +file with an uppercase character. This way, the user can simply declare the +component using the file name as the component name. For example, if a QML +component is in a file named \c Button.qml, then the user may import the +component by declaring a \c {Button {}}. Note that this method only works if +the QML files are in the same directory. + +It is also possible to import QML files which have file names that begin in +lower case or files in a different directory by using a \c qmldir file. + +A \c qmldir file tells your QML application which QML components, plugins, +or directories to import. The \c qmldir file must reside in an imported +directory. By using the \c qmldir file, users may import any QML file and assign any +valid QML component name to the component. + +For more information, read the section on +\l{qml-loading-components}{Loading a Component}. + +\section1 Commenting Code + +Commenting code allows others to read the source code better. As well, comments +allow the programmer to think about his or her code; a confusing comment may +mean the code is confusing. + +Similar to JavaScript or C++, there are two ways of commenting QML code: +\list +\o Single line comments start with \c{//} and finish at the end of the line +\o Multiline comments start with \c{/*} and finish with *\/ +\endlist + +\section1 Group Properties + +Many QML properties are \l{attached-properties}{attached} or +\l {qml-grouped-properties}{group} properties. For convenience, you may treat +them as another element when dealing with multiple properties belonging to the +same group. + +\snippet doc/src/snippets/declarative/bestpractices/group.qml not grouped +Treating groups of properties as a block can ease confusion and help relate the +properties with other properties. +\snippet doc/src/snippets/declarative/bestpractices/group.qml grouped +*/ diff --git a/doc/src/howtos/qmlbestpractices/qmlbestpractices-datatypes.qdoc b/doc/src/howtos/qmlbestpractices/qmlbestpractices-datatypes.qdoc new file mode 100644 index 0000000..0f6d74b --- /dev/null +++ b/doc/src/howtos/qmlbestpractices/qmlbestpractices-datatypes.qdoc @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! + \page qml-best-practices-datatypes.html + \ingroup qml-best-practices + \contentspage QML Best Practices Guides + \previouspage QML Best Practices Guides + \startpage QML Best Practices Guides + \title QML Best Practices: Data Types + + \brief Using Basic Data Types and Custom Types in QML + + QML supports many basic data types, Qt data types, and custom data types. + + \section1 Basic Data Types + + \section1 Qt Data Types + + \section1 Exporting Qt Types to QML + + Programmers may create C++ data structures and expose them to QML, making + data accessible from QML. + + \section2 Using QStringLists in QML +*/ diff --git a/doc/src/howtos/scalabilityintro.qdoc b/doc/src/howtos/scalabilityintro.qdoc new file mode 100644 index 0000000..5b4e58b --- /dev/null +++ b/doc/src/howtos/scalabilityintro.qdoc @@ -0,0 +1,324 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \title Scalability + \page scalability.html + \preliminary + + \omit preliminary docs for next SDK release \endomit + \omit Somewhere I need to mention applications with more than + one page (top-level layouts). \endomit + + A scalable application is an application that can run on more than + one form factor. In particular, it can cope with different screen + sizes, DPI, and aspect ratios. You need to consider scalability + when: + + \list + \o your application will be deployed to more than one device + handset, or more than one device form factor. + \o your application will be deployed for a long period of time, + so that new device handsets might appear on the market after + your initial deployment. + \endlist + + This document discusses how scalable applications can be created. + + \section1 Developing Scalable UIs + + This section shows the basics of how we advice scalable + applications to be implemented using QML. We recommend that you + follow these techniques: + + \list + \o Create separate top-level layout + definitions for each form factor. + \o Keep the layouts small and let components + scale relative to their immediate parent. + \o Define device independent measurements, such as dp + (device independent pixels), and use + these to scale components and for layout measurement. + \o Define layouts in a + proportional way using the built-in layout features of QML. + \endlist + + Using small top-level layouts makes your codebase smaller and + easier to maintain. Also, components that scales relative to their + parent are more reusable. The layouts should be children of the + application's root item. You can change between them by, for + instance, using the opacity property of Item; that is, if your + application has more tham one top-level layout. Such a top-level + layout is also often referred to as a page, i.e., a layout that + uses the entire screen. For instance, an organizer application + will typically have separate pages for showing the calender and + editing todo items. + + You should define the measurements separate from the UI, for + instance by using a JavaScript object that you fill in with a + script on application start up. + + QML provides several ways of laying out components, e.g, using + anchor based layout, the more classic Grid; Column; and Row + elements, and by setting the dimensions of Items directly. When + laying out components in scalable applications, you should + generally prefer using anchors and set width and height based on + parent size where possible. Layouts are not only relevant to + top-level layouts; components often contain child Items. + + The following sections describe in more detail the different + aspects of scalability that should be considered in order to + achieve the desired level of flexibility within your application. + + \section1 Implementing the Top-Level Layouts + + As mentioned, each application should use separate top-level + layout QML definitions to support separate layout configurations / + form factors. + + Consider an application that has to be deployed to at least two + devices, which both have very different screen sizes and DPI + values. The two form factors of the application will share many + common components and attributes, and will most likely connect to + the same data model. + + Therefore, the top-level definitions should be quite + straightforward and short, with the majority of the functionality + refactored into contained Components. It is important to try to + avoid unnecessary duplication between these top-level definitions, + in order to improve maintainability. + + There are some patterns that you might consider when designing + your top level layouts: + + \list + \o In some cases, the contents of an entire page in a smaller + handset could form a component element of a layout in a + larger device. Therefore, consider making that a separate + component (i.e. defined in a separate QML file), and in the + smaller handset, the Page will simply contain an instance of + that component. On the larger device, there may be enough + space to show two separate items. For example, in an email + viewer, if the screen is large enough, it may be possible to + show the email list view, and the email reader view side by + side. + \o In some cases, the contents of a view might be quite similar + on all screen sizes, but with an expanded content area. In + this case, it may be possible to re-use the same layout + definition, if defined appropriately using anchors. + \endlist + + The \l{Loader} component can be used to load separate QML files + based on some criteria, such as Device Profile (configuration of + screen pixel resolution and DPI density). In the case of form + factor, this information will not change during the application's + lifetime, therefore there is no issue with memory usage or + performance. + + \section1 Defining Measurements + + When you are defining the measurements within an application or + component layout, there are a number aspects to consider: + + \list + \o The layout structure, the high-level relationship between + items. Which item is the parent? How are the items arranged + relatively on the screen? Are they in a grid or column? + \o The layout measurements. How big is an item, or a margin + inside the edge of an item, or an anchor between items? + \o The implicit size of contained items. Some child items will + require a certain amount of space, such as a button + containing a text. That may also depend on the current + platform and style. How do you ensure that you leave enough + space, and what happens if your children change size? + \endlist + + These aspects combine together to resolve the final layout for a + given Device Profile. However, although there are dependencies + between them, it is important to manage and control the different + aspects separately. + + It is strongly recommended that Layout measurements should be + stored in a separate place from the component layout structure + definition files. The reason for this is that layout structure, + for a given form factor, can be re-used for different Device + Profiles. However, measurements will almost always vary between + Device Profiles or Device Categories. + + If the opposite approach (complete duplication of entire QML + files) was taken, then all of the layout states and structure + definitions would be duplicated between the copied QML files, and + only the measurement values would change. + + The main benefit of using separate measurement definition files + are: + + \list + \o To reduce the amount of duplication, and hence increase + maintainability. + \o It becomes much easier to change the layout structure, + perhaps due to subsequent specification changes. In that + case, the layout structure can be modified once, and many or + all of the layout measurements would remain unchanged. + \o It becomes much easier to add support for additional Device + Profiles, simply by adding another measurement definition + file. + \endlist + + \section1 Using QML's Layout Features + + For a given form factor, top-level Layouts structure definitions, + or component layout structure definitions, should in general be + defined in a proportional way using a combination of + + \list + \o \l{Item::anchors.top}{anchors} within an Item + \o \l{Row} / \l{Column} / \l{Grid} + \o simple javascript expressions such as width: Math.round(parent.width / 3.0). + \endlist + + These basic building blocks, along with the powerful evaluation + capabilities of javascript expressions within every QML binding, + are designed to allow the majority of the layout structure + definition to be defined in a Device Profile independent way. + + There are some limitations of the basic grid type layouts. They + are designed to accommodate a number of Items, but use the current + sizes of those items. There is a similar issue with the basic + anchor type layout. In particular, it can be difficult to spread a + number of child items proportionately across an area of their + container. + + By combining the features of the layout managers with simple + javascript expressions, a richer variety of designs can be + expressed, without having to resort to additional layout + measurement parameters or measurement values. + + Here are some things not to do with layouts: + + \list + \o Don't define complex javascript functions that are regularly + evaluated. This will cause poor performance, particularly + during animated transitions. + \o Don't define all of your layouts using x, y, width and + height. Reserve this for items that cannot easily be defined + using anchors (anchors are evaluated in a more efficient + way). + \o Don't make assumptions about the container size, or about + the size of child items. Try to make flexible layout + definitions that can absorb changes in the available space. + \endlist + + \section1 Orientation Switches + + Application top-level page definitions, and reusable component + definitions, should use one QML layout definition for the layout + structure. This single definition should include the layout design + for separate Device Orientations and Aspect Ratios. The reason for + this is that performance during an orientation switch is critical, + and it is therefore a good idea to ensure that all of the + components needed by both orientations are loaded when the + orientation changes. + + On the contrary, you should perform thorough tests if you choose + to use a \l{Loader} to load additional QML that is needed in separate + orientations, as this will affect the performance of the + orientation change. + + In order to enable layout animations between the orientations, the + anchor definitions must reside within the same containing + component. Therefore the structure of a page or a component + should consist of a common set of child components, a common set + of anchor definitions, and a collection of states (defined in a + StateGroup) representing the different aspect ratios supported by + the component. (However note that orientation change animations + are not possible on Symbian due to compatibility support for S60 + applications). + + If a component contained within a page needs to be + hosted in numerous different form factor definitions, then the + layout states of the view should depend on the aspect ratio of the + page (its immediate container). Similarly, different instances of + a component might be situated within numerous different containers + in a UI, and so its layout states should be determined by the + aspect ratio of its parent. The conclusion is that layout states + should always follow the aspect ratio of the direct container (not + the "orientation" of the current device screen). + + Within each layout \l{State}, you should define the relationships + between items using native QML layout definitions. See below for + more information. During transitions between the states (triggered + by the top level orientation change), in the case of anchor + layouts, AnchorAnimation elements can be used to control the + transitions. In some cases, you can also use a NumberAnimation on + e.g. the width of an item. Remember to avoid complex javascript + calculations during each frame of animation. Using simple anchor + definitions and anchor animations can help with this in the + majority of cases. + + There are a few additional cases to consider: + + \list + \o What if you have a single page that looks completely + different between landscape and portrait, i.e. all of the + child items are different? For each page, have two child + components, with separate layout definitions, and make one + or other of the items have zero opacity in each state. You + can use a cross-fade animation by simply applying a + NumberAnimation transition to the opacity. + \o What if you have a single page that shares 30% or more of + the same layout contents between portrait and landscape? In + that case, consider having one component with landscape and + portrait states, and a collection of separate child items + whose opacity (or position) depends on the orientation + state. This will enable you to use layout animations for the + items that are shared between the orientations, whilst the + other items are either faded in/out, or animated on/off + screen. + \o What if you have two pages on a handheld device that need to + be on screen at the same time, for example on a larger form + factor device? In this case, notice that your view component + will no longer be occupying the full screen. Therefore it's + important to remember in all components (in particular, list + delegate items) should depend on the size of the containing + component width, not on the screen width. It may be + necessary to set the width in a Component.onCompleted() + handler in this case, to ensure that the list item delegate + has been constructed before the value is set. + \o What if the two orientations take up too much memory to have + them both in memory at once? Use a \l{Loader} if necessary, if + you cannot keep both versions of the view in memory at once, + but beware performance on the cross-fade animation during + layout switch. One solution could be to have two "splash + screen" items that are children of the Page, then you cross + fade between those during rotation. Then you can use a + \l{Loader} to load another child component that loads the actual + model data to another child Item, and cross-fade to that + when the \l{Loader} has completed. + \endlist + */ + diff --git a/doc/src/howtos/unix-signal-handlers.qdoc b/doc/src/howtos/unix-signal-handlers.qdoc index 2fa558e..20beb38 100644 --- a/doc/src/howtos/unix-signal-handlers.qdoc +++ b/doc/src/howtos/unix-signal-handlers.qdoc @@ -59,7 +59,7 @@ sigaction(2) man pages before plowing through the following code snippets. - \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.qdoc 0 + \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.cpp 0 In the MyDaemon constructor, use the socketpair(2) function to initialize each file descriptor pair, and then create the @@ -68,24 +68,24 @@ appropriate slot function, which effectively converts the Unix signal to the QSocketNotifier::activated() signal. - \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.qdoc 1 + \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.cpp 1 Somewhere else in your startup code, you install your Unix signal handlers with sigaction(2). - \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.qdoc 2 + \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.cpp 2 In your Unix signal handlers, you write a byte to the \e write end of a socket pair and return. This will cause the corresponding QSocketNotifier to emit its activated() signal, which will in turn cause the appropriate Qt slot function to run. - \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.qdoc 3 + \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.cpp 3 In the slot functions connected to the QSocketNotifier::activated() signals, you \e read the byte. Now you are safely back in Qt with your signal, and you can do all the Qt stuff you weren'tr allowed to do in the Unix signal handler. - \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.qdoc 4 + \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.cpp 4 */ diff --git a/doc/src/images/guide.png b/doc/src/images/guide.png Binary files differnew file mode 100644 index 0000000..f4b0df1 --- /dev/null +++ b/doc/src/images/guide.png diff --git a/doc/src/images/listview-decorations.png b/doc/src/images/listview-decorations.png Binary files differnew file mode 100644 index 0000000..445c648 --- /dev/null +++ b/doc/src/images/listview-decorations.png diff --git a/doc/src/images/listview-section.png b/doc/src/images/listview-section.png Binary files differnew file mode 100644 index 0000000..a3664fc --- /dev/null +++ b/doc/src/images/listview-section.png diff --git a/doc/src/images/listview-setup.png b/doc/src/images/listview-setup.png Binary files differnew file mode 100644 index 0000000..5293d05 --- /dev/null +++ b/doc/src/images/listview-setup.png diff --git a/doc/src/images/mobile.png b/doc/src/images/mobile.png Binary files differnew file mode 100644 index 0000000..af460e2 --- /dev/null +++ b/doc/src/images/mobile.png diff --git a/doc/src/images/qml-dial.png b/doc/src/images/qml-dial.png Binary files differdeleted file mode 100644 index da5c031..0000000 --- a/doc/src/images/qml-dial.png +++ /dev/null diff --git a/doc/src/images/qml-intro-anchors1.png b/doc/src/images/qml-intro-anchors1.png Binary files differdeleted file mode 100644 index fdb301e..0000000 --- a/doc/src/images/qml-intro-anchors1.png +++ /dev/null diff --git a/doc/src/images/qml-intro-anchors2.png b/doc/src/images/qml-intro-anchors2.png Binary files differdeleted file mode 100644 index 84f43bd..0000000 --- a/doc/src/images/qml-intro-anchors2.png +++ /dev/null diff --git a/doc/src/images/qml-intro-anchors3.png b/doc/src/images/qml-intro-anchors3.png Binary files differdeleted file mode 100644 index 21ae97b..0000000 --- a/doc/src/images/qml-intro-anchors3.png +++ /dev/null diff --git a/doc/src/images/qml-intro-helloa.png b/doc/src/images/qml-intro-helloa.png Binary files differdeleted file mode 100644 index 00b34b0..0000000 --- a/doc/src/images/qml-intro-helloa.png +++ /dev/null diff --git a/doc/src/images/qml-listview-snippet.png b/doc/src/images/qml-listview-snippet.png Binary files differdeleted file mode 100644 index 0ee0ffc..0000000 --- a/doc/src/images/qml-listview-snippet.png +++ /dev/null diff --git a/doc/src/images/qml.png b/doc/src/images/qml.png Binary files differnew file mode 100644 index 0000000..b1e4ab6 --- /dev/null +++ b/doc/src/images/qml.png diff --git a/doc/src/images/qmldesigner-visual-editor.png b/doc/src/images/qmldesigner-visual-editor.png Binary files differnew file mode 100644 index 0000000..9cd4b8b --- /dev/null +++ b/doc/src/images/qmldesigner-visual-editor.png diff --git a/doc/src/images/qt-logo_large.png b/doc/src/images/qt-logo_large.png Binary files differnew file mode 100644 index 0000000..4e230bd --- /dev/null +++ b/doc/src/images/qt-logo_large.png diff --git a/doc/src/images/qtcreator-target-selector.png b/doc/src/images/qtcreator-target-selector.png Binary files differnew file mode 100644 index 0000000..1f26138 --- /dev/null +++ b/doc/src/images/qtcreator-target-selector.png diff --git a/doc/src/images/thread_clock.png b/doc/src/images/thread_clock.png Binary files differnew file mode 100644 index 0000000..b8a8aa0 --- /dev/null +++ b/doc/src/images/thread_clock.png diff --git a/doc/src/images/threads-examples.png b/doc/src/images/threads-examples.png Binary files differnew file mode 100644 index 0000000..b6e4bcc --- /dev/null +++ b/doc/src/images/threads-examples.png diff --git a/doc/src/images/threadvisual-example.png b/doc/src/images/threadvisual-example.png Binary files differnew file mode 100644 index 0000000..2a49874 --- /dev/null +++ b/doc/src/images/threadvisual-example.png diff --git a/doc/src/images/tools.png b/doc/src/images/tools.png Binary files differnew file mode 100644 index 0000000..4d717b5 --- /dev/null +++ b/doc/src/images/tools.png diff --git a/doc/src/index.qdoc b/doc/src/index.qdoc index be59c2f..079a03b 100644 --- a/doc/src/index.qdoc +++ b/doc/src/index.qdoc @@ -26,94 +26,141 @@ ****************************************************************************/ /*! - \page index.html - \keyword Qt Reference Documentation +\page index.html +\keyword Qt Reference Documentation - \div {indexbox guide} - \div {heading} - Qt Developer Guide - \enddiv - \div {indexboxcont indexboxbar} - \div {section indexIcon} \emptyspan - \enddiv - \div {section} - Qt is a cross-platform application and UI - framework. Using Qt, you can write web-enabled - applications once and deploy them across desktop, - mobile and embedded operating systems without - rewriting the source code. - \enddiv - \div {section sectionlist} - \list - \o \l{Getting Started Guides}{Getting started} - \o \l{Installation}{Installation} - \o \l{how-to-learn-qt.html}{How to learn Qt} - \o \l{tutorials.html}{Tutorials} - \o \l{Qt Examples}{Examples} - \o \l{qt4-7-intro.html}{What's new in Qt 4.7} - \endlist - \enddiv +\div {class="indexbox guide"} + \div {class="heading"} + Qt Developer Guide + \enddiv +\enddiv +\div {class="indexbox tools"} + \div {class="indexboxcont indexboxbar"} + \div {class="sectionlist normallist"} + \div {class="heading"} + What is Qt + \enddiv + \image qt-logo_large.png + Qt is a cross-platform application and UI framework. Using Qt, you can + write applications once and deploy them across desktop, mobile, and + embedded operating systems without rewriting the source code. + \enddiv + \div {class="sectionlist normallist"} + \list + \o \l{http://doc.qt.nokia.com/nokia-qtsdk-1.0/index.html}{Qt SDK} + \o \l{http://developer.qt.nokia.com/wiki/QtCreatorWhitepaper}{Qt Creator} + \o \l{http://doc.qt.nokia.com/qtsimulator-1.1/index.html}{Qt Simulator} + \endlist + \list + \o \l{http://developer.qt.nokia.com/wiki/QtWhitepaper}{Qt C++ Framework} + \o \l{Qt Quick} + \o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/index.html}{Qt Mobility} + \o \l{Qt WebKit} + \endlist + \list + \o \l{Supported Platforms}{Platform Support} + \o \l{What's New in Qt 4.7} - latest release + \endlist + \enddiv + \div {class="sectionlist normallist"} + \div {class="heading"} + See Qt \enddiv - \enddiv - \div {indexbox api} - \div {heading} - Qt API - \enddiv - \div {indexboxcont indexboxbar } - \div {sectionlist tricol} - \list - \o \l{All Classes}{All Classes} - \o \l{All Functions}{All Functions} - \o \l{All Modules}{All Modules} - \o \l{All Namespaces}{All Namespaces} - \o \l{Global Qt Declarations}{Global Declarations} - \o \l{Qt Licenses and Credits}{Licenses and Credits} - \endlist - \enddiv - \div {sectionlist tricol} - \list - \o \l{Programming with Qt} - \o \l{UI Design with Qt} - \o \l{Cross-Platform and Platform-Specific Development} - \o \l{Qt and Key Technologies} - \o \l{Best Practice Guides} - \endlist - \enddiv - \div {sectionlist} - \list - \o \l{qtquick.html}{Qt Quick} - \o \l{qdeclarativeintroduction.html}{Introduction to QML} - \o \l{qdeclarativeelements.html}{QML Elements} - \o \l{qdeclarativeexamples.html}{QML Examples and Demos} - \endlist - \enddiv + \image mobile.png + \list + \o \l{Qt Demonstrations}{Application Gallery} + \o \l{Tutorials} + \o \l{Qt Examples}{Examples} + \o \l{QML Examples and Demos} + \endlist + \enddiv + \enddiv +\enddiv +\div {class="indexbox tools"} + \div {class="indexboxcont indexboxbar"} + \div {class="sectionlist normallist"} + \div {class="heading"} + Develop with Qt \enddiv - \enddiv - \div {indexbox tools} - \div {heading} - Qt Tools - \enddiv - \div {indexboxcont} - \div {section indexIcon} \emptyspan - \enddiv - \div {section} - Qt offers a selection of development tools for - different tasks. Use Qt Creator for project and code - management as well as building powerfull UIs. - \enddiv - \div {section sectionlist} - \list - \o \l{http://doc.qt.nokia.com/qtcreator-2.0/index.html}{Qt Creator} - \o \l{designer-manual.html}{Qt Designer} - \o \l{linguist-manual.html}{Qt Linguist} - \o \l{assistant-manual.html}{Qt Assistant} - \o \l{qmake-manual.html}{Qt qmake} - \o \l{http://doc.qt.nokia.com/qtsimulator-1.0/index.html}{Qt Simulator} - \o \l{http://qt.nokia.com/developer/eclipse-integration}{Eclipse Integration} - \o \l{http://qt.nokia.com/products/appdev}{Add-On Products and Services} - \o \l{qvfb.html}{Virtual Framebuffer} - \endlist - \enddiv + \image tools.png + \list + \o \l{Develop with Qt}{Steps to Programming Qt Applications} + \o \l{qt-creator-configure-target}{Configure Qt and Creator for Platforms} + \o \l{qt-technologies}{Qt Features and Technologies} + \o \l{qt-utilities}{Utilities and Testing} + \o \l{qt-deployment}{Deploying Applications and Publish to Ovi Store} + \endlist + \enddiv + \div {class="sectionlist normallist"} + \div {class="heading"} + Featured Articles \enddiv - \enddiv + \image guide.png + \list + \o \l{Scalability}{How to Create Scalable Applications} + \o \l{http://doc.qt.nokia.com/nokia-qtsdk-1.0/creator-developing-symbian.html}{Setting Up Development Environment for Symbian} + \o \l{http://doc.qt.nokia.com/nokia-qtsdk-1.0/creator-developing-maemo.html}{Setting Up Development Environment for Maemo} + \o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-publish-ovi.html}{Publishing Qt Applications to Ovi Store} + \endlist + \list + \o \l{Qt Development: The Steps from Challenge to Achievement}{The Steps from Challenge to Achievement} + A case analysis of a business development problem and a search for +innovative solutions using Qt. + \endlist + \enddiv + \div {class="sectionlist normallist"} + \div {class="heading"} + UI Creation with Qt + \enddiv + \image qml.png + \list + \o \l{qt-ui-creation}{Create UI with Qt} + \o \l{qt-rendering-painting-system}{Qt's Rendering and Painting Systems} + \o \l{Qt Quick} - develop fluid UIs with QML + \o \l{Widgets and Layouts} - elements for C++ interfaces + \endlist + \enddiv + \enddiv +\enddiv +\div {class="indexbox tools"} + \div {class="heading"} + Reference + \enddiv + \div {class="indexboxcont indexboxbar"} + \div {class="sectionlist normallist"} + \div {class="heading"} + Qt API + \enddiv + \list + \o \l{All Classes}{All Classes} + \o \l{All Functions}{All Functions} + \o \l{All Modules}{All Modules} + \o \l{All Namespaces}{All Namespaces} + \o \l{Global Qt Declarations}{Global Declarations} + + \endlist + \enddiv + \div {class="sectionlist normallist"} + \list + \o \l{Qt Quick} + \o \l{QML Elements} + \endlist + \list + \o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/index.html}{Qt Mobility APIs} + \o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/qml-plugins.html}{Mobility QML Plugins} + \endlist + \enddiv + \div {class="sectionlist normallist"} + \div {class="heading"} + Qt Manuals + \enddiv + \list + \o \l{http://doc.qt.nokia.com/qtcreator-2.0/index.html}{Qt Creator} + \o \l{http://doc.qt.nokia.com/qtsimulator/index.html}{Qt Simulator} + \o \l{linguist-manual.html}{Qt Linguist} + \o \l{assistant-manual.html}{Qt Assistant} + \endlist + \enddiv + \enddiv +\enddiv */ diff --git a/doc/src/internationalization/i18n.qdoc b/doc/src/internationalization/i18n.qdoc index e22f953..f58a9a5 100644 --- a/doc/src/internationalization/i18n.qdoc +++ b/doc/src/internationalization/i18n.qdoc @@ -34,13 +34,13 @@ */ /*! - \page internationalization.html \title Internationalization with Qt \brief Information about Qt's support for internationalization and multiple languages. \nextpage Writing Source Code for Translation \ingroup qt-basic-concepts - + \group internationalization + \keyword internationalization \keyword i18n @@ -192,7 +192,7 @@ to achieve this is to use QObject::tr(). For example, assuming the \c LoginWidget is a subclass of QWidget: - \snippet doc/src/snippets/code/doc_src_i18n.qdoc 0 + \snippet doc/src/snippets/code/doc_src_i18n.cpp 0 This accounts for 99% of the user-visible strings you're likely to write. @@ -202,7 +202,7 @@ appropriate class, or the QCoreApplication::translate() function directly: - \snippet doc/src/snippets/code/doc_src_i18n.qdoc 1 + \snippet doc/src/snippets/code/doc_src_i18n.cpp 1 If you need to have translatable text completely outside a function, there are two macros to help: QT_TR_NOOP() @@ -212,11 +212,11 @@ Example of QT_TR_NOOP(): - \snippet doc/src/snippets/code/doc_src_i18n.qdoc 2 + \snippet doc/src/snippets/code/doc_src_i18n.cpp 2 Example of QT_TRANSLATE_NOOP(): - \snippet doc/src/snippets/code/doc_src_i18n.qdoc 3 + \snippet doc/src/snippets/code/doc_src_i18n.cpp 3 If you disable the \c{const char *} to QString automatic conversion by compiling your software with the macro \c @@ -244,13 +244,13 @@ The QString::arg() functions offer a simple means for substituting arguments: - \snippet doc/src/snippets/code/doc_src_i18n.qdoc 4 + \snippet doc/src/snippets/code/doc_src_i18n.cpp 4 In some languages the order of arguments may need to change, and this can easily be achieved by changing the order of the % arguments. For example: - \snippet doc/src/snippets/code/doc_src_i18n.qdoc 5 + \snippet doc/src/snippets/code/doc_src_i18n.cpp 5 produces the correct output in English and Norwegian: \snippet doc/src/snippets/code/doc_src_i18n.qdoc 6 @@ -325,7 +325,7 @@ Typically, your application's \c main() function will look like this: - \snippet doc/src/snippets/code/doc_src_i18n.qdoc 8 + \snippet doc/src/snippets/code/doc_src_i18n.cpp 8 Note the use of QLibraryInfo::location() to locate the Qt translations. Developers should request the path to the translations at run-time by @@ -346,7 +346,7 @@ need to output Cyrillic in the ISO 8859-5 encoding. Code for this would be: - \snippet doc/src/snippets/code/doc_src_i18n.qdoc 9 + \snippet doc/src/snippets/code/doc_src_i18n.cpp 9 For converting Unicode to local 8-bit encodings, a shortcut is available: the QString::toLocal8Bit() function returns such 8-bit @@ -360,7 +360,7 @@ demonstrated by this conversion from ISO 8859-5 Cyrillic to Unicode conversion: - \snippet doc/src/snippets/code/doc_src_i18n.qdoc 10 + \snippet doc/src/snippets/code/doc_src_i18n.cpp 10 Ideally Unicode I/O should be used as this maximizes the portability of documents between users around the world, but in reality it is @@ -392,7 +392,7 @@ formats. Such localizations can be accomplished using appropriate tr() strings. - \snippet doc/src/snippets/code/doc_src_i18n.qdoc 11 + \snippet doc/src/snippets/code/doc_src_i18n.cpp 11 In the example, for the US we would leave the translation of "AMPM" as it is and thereby use the 12-hour clock branch; but in @@ -417,7 +417,7 @@ the text displayed by widgets using the \l{QObject::tr()}{tr()} function in the usual way. For example: - \snippet doc/src/snippets/code/doc_src_i18n.qdoc 12 + \snippet doc/src/snippets/code/doc_src_i18n.cpp 12 All other change events should be passed on by calling the default implementation of the function. @@ -511,7 +511,7 @@ /*! \page i18n-source-translation.html \title Writing Source Code for Translation - \ingroup i18n + \ingroup internationalization \previouspage Internationalization with Qt \contentspage Internationalization with Qt \nextpage Translation Rules for Plurals @@ -708,7 +708,7 @@ Typically, your application's \c main() function will look like this: - \snippet doc/src/snippets/code/doc_src_i18n.qdoc 8 + \snippet doc/src/snippets/code/doc_src_i18n.cpp 8 Note the use of QLibraryInfo::location() to locate the Qt translations. Developers should request the path to the translations at run-time by @@ -723,7 +723,7 @@ /*! \page i18n-plural-rules.html \title Translation Rules for Plurals - \ingroup i18n + \ingroup internationalization \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. diff --git a/doc/src/internationalization/linguist-manual.qdoc b/doc/src/internationalization/linguist-manual.qdoc index 1f413f9..7932fe8 100644 --- a/doc/src/internationalization/linguist-manual.qdoc +++ b/doc/src/internationalization/linguist-manual.qdoc @@ -29,6 +29,7 @@ \page linguist-manual.html \title Qt Linguist Manual \ingroup qttools + \ingroup internationalization \startpage {index.html}{Qt Reference Documentation} \nextpage Qt Linguist Manual: Release Manager @@ -46,10 +47,10 @@ at the person with overall responsibility for the release of the application. They will typically coordinate the work of the software engineers and the translator. The chapter describes the - use of two tools. The \l{lupdate} tool is used to synchronize - source code and translations. The \l{lrelease} tool is used to - create run-time translation files for use by the released - application. + use of two tools. The \l{linguist-manager.html#lupdate}{lupdate} + tool is used to synchronize source code and translations. The + \l{linguist-manager.html#lrelease}{lrelease} tool is used to create + run-time translation files for use by the released application. The \l{linguist-translators.html}{Translators} chapter is for translators. It describes the use of the \QL tool. @@ -77,7 +78,7 @@ programmer is able to add additional context information to phrases when necessary. The release manager generates a set of translation files that are produced from the source files and passes these to the - translator. The translator opens the translation files using \QL, + translator. The translator opens the translation files using \QL, enters their translations and saves the results back into the translation files, which they pass back to the release manager. The release manager then generates fast compact versions of these @@ -144,25 +145,22 @@ /*! \page linguist-manager.html \title Qt Linguist Manual: Release Manager + \ingroup internationalization \contentspage {Qt Linguist Manual}{Contents} \previouspage Qt Linguist Manual \nextpage Qt Linguist Manual: Translators - \keyword lupdate - \keyword lrelease - Two tools are provided for the release manager, \l lupdate and \l lrelease. These tools can process \l qmake project files, or operate directly on the file system. \section1 Qt Project Files - The easiest method to use \l{#lupdate} {lupdate} and \l{#lrelease} - {lrelease} is by specifying a \c .pro Qt project file. There must - be an entry in the \c TRANSLATIONS section of the project file for - each language that is additional to the native language. A typical - entry looks like this: + The easiest method to use \l lupdate and \l lrelease is by specifying + a \c .pro Qt project file. There must be an entry in the \c TRANSLATIONS + section of the project file for each language that is additional to + the native language. A typical entry looks like this: \snippet examples/linguist/arrowpad/arrowpad.pro 1 @@ -173,8 +171,8 @@ An example of a complete \c .pro file with four translation source files: - \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 0 - \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 1 + \snippet doc/src/snippets/code/doc_src_linguist-manual.pro 0 + \snippet doc/src/snippets/code/doc_src_linguist-manual.pro 1 QTextCodec::setCodecForTr() makes it possible to choose a 8-bit encoding for literal strings that appear within \c tr() calls. @@ -186,14 +184,14 @@ application, \QL needs you to set the \c CODECFORTR entry in the \c .pro file as well. For example: - \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 1 + \snippet doc/src/snippets/code/doc_src_linguist-manual.pro 1 Also, if your compiler uses a different encoding for its runtime system as for its source code and you want to use non-ASCII characters in string literals, you will need to set the \c CODECFORSRC. For example: - \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 2 + \snippet doc/src/snippets/code/doc_src_linguist-manual.pro 2 Microsoft Visual Studio 2005 .NET appears to be the only compiler for which this is necessary. However, if you want to write @@ -201,9 +199,8 @@ in your source files. You can still specify non-ASCII characters portably using escape sequences, for example: - \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 3 + \snippet doc/src/snippets/code/doc_src_linguist-manual.cpp 3 - \target lupdate manual \section1 lupdate Usage: \c {lupdate myproject.pro} @@ -238,8 +235,8 @@ can also process Localization Interchange File Format (XLIFF) format files; files in this format typically have file names that end with the \c .xlf suffix. - - \note The minimum supported version for XLIFF format files is + + \note The minimum supported version for XLIFF format files is 1.1. XLIFF 1.0 version files are not supported. Pass the \c -help option to \c lupdate to obtain the list of @@ -271,7 +268,7 @@ are available the application will detect them and use them automatically. - Note that lrelease will only incorporate translations that are + Note that \l lrelease will only incorporate translations that are marked as "finished". Otherwise the original text will be used instead. @@ -285,12 +282,13 @@ 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. + runtime. */ /*! \page linguist-translators.html \title Qt Linguist Manual: Translators + \ingroup internationalization \contentspage {Qt Linguist Manual}{Contents} \previouspage Qt Linguist Manual: Release Manager @@ -315,7 +313,7 @@ arranged around a central \l{The Translation Area} {translation area}. The \l{Context Window} {context list} is normally shown on the left, and the \l{Sources and Forms Window} {source code}, - \l{Strings Window} {string list}, and either the \l{Phrases and + \l{Strings Window} {string list}, and either the \l{Phrases and Guesses Window} {phrases and guesses}, or the \l{Warnings Window} {warnings} are shown above and below the \l{The Translation Area} {translations area}. @@ -331,9 +329,9 @@ \key{tick mark} button on the toolbar, or click the icon to the left of the selected source string in the string list. Repeat this process until all strings in the string list are marked with - \inlineimage linguist-check-on.png + \inlineimage linguist-check-on.png or - \inlineimage linguist-check-warning.png + \inlineimage linguist-check-warning.png . Then select the next context and continue. Translation options are shown in the \l{Phrases and Guesses @@ -389,17 +387,17 @@ that aren't in a subclass of QObject. To the left of the \e{Context} column is a column labeled - \inlineimage linguist-check-obsolete.png + \inlineimage linguist-check-obsolete.png . This column uses the following list of icons to summarize the current translation state for each context: \list - \o \inlineimage linguist-check-on.png + \o \inlineimage linguist-check-on.png All strings in the context have been translated, and all the translations passed the \l{Validation Tests} {validation tests}. - \o \inlineimage linguist-check-warning.png + \o \inlineimage linguist-check-warning.png All strings in the context have been translated or marked as translated, but at least one translation failed the \l{Validation Tests} {validation tests}. @@ -427,19 +425,19 @@ selected. Its \e{Items} entry shows \bold{18/18}, which means it has 18 translatable strings and all 18 strings currently have translations. However, the context has been marked with the - \inlineimage linguist-check-warning.png - icon, which means that at least one of the current translations - failed a \l{Validation Tests} {validation test}. In the - \l{Strings Window} {strings window} to the right, we see that one - of the strings is indeed marked with the - \inlineimage linguist-check-warning.png + \inlineimage linguist-check-warning.png + icon, which means that at least one of the current translations + failed a \l{Validation Tests} {validation test}. In the + \l{Strings Window} {strings window} to the right, we see that one + of the strings is indeed marked with the + \inlineimage linguist-check-warning.png icon. The context window is a dockable window. It can be dragged to another position in the main window, or dragged out of the main window to be a separate window. If you move the context window, \QL remembers the new position and puts the context window there - whenever you start the program. If the context window has been + whenever you start the program. If the context window has been closed, it can be restored by pressing \key{F6}. \section2 Strings Window @@ -475,16 +473,16 @@ \o The source string has a translation (possibly empty); the user has accepted the translation, and the translation passes all the \l{Validation Tests} {validation tests}. If the translation is - empty, the user has chosen to leave it empty. Click the icon to - revoke acceptance of the translation and decrement the number of + empty, the user has chosen to leave it empty. Click the icon to + revoke acceptance of the translation and decrement the number of accepted translations in the \e{Items} column of the \l{Context - Window} {context list} by 1. The state is reset to - \inlineimage linguist-check-off.png + Window} {context list} by 1. The state is reset to + \inlineimage linguist-check-off.png if the string has a translation, or to \inlineimage linguist-check-empty.png - if the string's translation is empty. If \c{lupdate} changes the - contents of a string, its acceptance state is automatically reset - to \inlineimage linguist-check-off.png + if the string's translation is empty. If \c{lupdate} changes the + contents of a string, its acceptance state is automatically reset + to \inlineimage linguist-check-off.png . \row @@ -493,44 +491,44 @@ \o The user has accepted the translation, but the translation does not pass all the \l{Validation Tests} {validation tests}. The validation test failures are shown in the \l{Warnings Window} - {warnings window}. Click the icon to revoke acceptance of the - translation. The state is reset to \inlineimage linguist-danger.png - , and the number of accepted translations in the \e{Items} column - of the \l{Context Window} {context list} is decremented by 1. + {warnings window}. Click the icon to revoke acceptance of the + translation. The state is reset to \inlineimage linguist-danger.png + , and the number of accepted translations in the \e{Items} column + of the \l{Context Window} {context list} is decremented by 1. \row \o Not Accepted \o \inlineimage linguist-check-off.png - \o The string has a non-empty translation that passes all the - \l{Validation Tests} {validation tests}, but the user has not yet + \o The string has a non-empty translation that passes all the + \l{Validation Tests} {validation tests}, but the user has not yet accepted the translation. Click the icon or press \key{Ctrl+Enter} - to accept the translation. The state is reset to + to accept the translation. The state is reset to \inlineimage linguist-check-on.png - , and the number of accepted translations in the \e{Items} column - of the \l{Context Window} {context list} is incremented by 1. + , and the number of accepted translations in the \e{Items} column + of the \l{Context Window} {context list} is incremented by 1. \row \o No Translation \o \inlineimage linguist-check-empty.png - \o The string does not have a translation. Click the icon to - accept the empty translation anyway. The state is reset to + \o The string does not have a translation. Click the icon to + accept the empty translation anyway. The state is reset to \inlineimage linguist-check-on.png - , and the number of accepted translations in the \e{Items} column + , and the number of accepted translations in the \e{Items} column of the \l{Context Window} {context list} is incremented by 1. \row \o Validation Failures \o \inlineimage linguist-danger.png - \o The string has a translation, but the translation does not - pass all the \l{Validation Tests} {validation tests}. Validation - test failures are shown in the \l{Warnings Window} {warnings} - window. Click on the icon or press \key{Ctrl+Return} to accept - the translation even with validation failures. The state is + \o The string has a translation, but the translation does not + pass all the \l{Validation Tests} {validation tests}. Validation + test failures are shown in the \l{Warnings Window} {warnings} + window. Click on the icon or press \key{Ctrl+Return} to accept + the translation even with validation failures. The state is reset to \inlineimage linguist-check-warning.png - . We recommended editing the translation to fix the causes of + . We recommended editing the translation to fix the causes of the validation failures. The state will reset automatically to \inlineimage linguist-check-off.png - , when all the failures have been fixed. + , when all the failures have been fixed. \row \o Obsolete @@ -558,12 +556,12 @@ If the developer provides a \l{QObject::tr()} {disambiguating comment}, it will appear below the source text area, under the - label \menu{Developer comments}. + label \menu{Developer comments}. Below the source text and optional developer comments are two text entry widgets for the translator, one for entering the translation of the current string, and one for the translator to enter an - optional comment to be read by other translators. + optional comment to be read by other translators. When \l{Translating Multiple Languages Simultaneously} {multiple languages} are being translated, this sequence of fields is @@ -578,7 +576,7 @@ translation(s) will be listed in this window. If the current string is the same as, or similar to, another string that has already been translated, that other string and its translation - will also be listed in this window. + will also be listed in this window. To use a translation from the Phrases and Guesses Window, you can double click the translation, and it will be copied into the @@ -607,7 +605,7 @@ If the source context shows the wrong source line, it probably means the translation file is out of sync with the source files. To re-sync the translation file with the source files, see the - \l{lupdate manual} {lupdate manual}. + \l{linguist-manager.html#lupdate}{lupdate} manual. The Sources and Forms window is a dockable window. If it has been closed, it can be made visible again by pressing the \e{Sources @@ -638,12 +636,12 @@ and you are given an application's Polish translation file and asked to update the application's Japanese translation file. You are more comfortable translating Polish to Japanese than you are - translating English to Japanese. + translating English to Japanese. Below is the UI snapshot shown earlier, but this time with both \e{Polish} and \e{Japanese} translation files loaded. - \image linguist-linguist_2.png + \image linguist-linguist_2.png The first thing to notice is that the \l{The Translation Area} {translation area} has text editing areas for both Polish and @@ -662,18 +660,18 @@ selected in the snapshot shown above. Recall that in the first UI snapshot (Polish only), the numbers for this context were \e{18/18}, meaning 18 translatable strings had been found in the - context, and all 18 strings had accepted translations. In the UI + context, and all 18 strings had accepted translations. In the UI snapshot above, the numbers for the \bold{MessageEditor} context are now \e{1/18}, meaning that both languages have 18 translatable strings for that context, but for Japanese, only 1 of the 18 - strings has an accepted translation. The - \inlineimage linguist-check-off.png + strings has an accepted translation. The + \inlineimage linguist-check-off.png icon in the Japanese column means that at least one string in the - context doesn't have an accepted Japanese translation yet. In fact, - 17 of the 18 strings don't have accepted Japanese translations yet. - We will see \e{18/18} in the \e{Items} column when all 18 strings - have accepted translations for all the loaded translation files, - e.g., both Polish and Japanese in the snapshot. + context doesn't have an accepted Japanese translation yet. In fact, + 17 of the 18 strings don't have accepted Japanese translations yet. + We will see \e{18/18} in the \e{Items} column when all 18 strings + have accepted translations for all the loaded translation files, + e.g., both Polish and Japanese in the snapshot. \section1 Common Tasks @@ -726,7 +724,7 @@ key in the translation text ("File") precede it with an ampersand, e.g. \e{\&File}. If a string to be translated has an ampersand in it, then the translation for that string should also have an - ampersand in it, preferably in front of the same character. + ampersand in it, preferably in front of the same character. The meaning of an Alt key accelerator can be determined from the phrase in which the ampersand is embedded. The translator can @@ -810,7 +808,7 @@ If the translated text is similar to the source text, choose the \e {Copy from source text} entry in the \menu Translation menu (press - \key{Ctrl+B}) which will copy the source text into the + \key{Ctrl+B}) which will copy the source text into the \l{The Translation Area} {translation area}. \QL automatically lists possible translations from any open @@ -839,9 +837,9 @@ A \QL phrase book is a set of source phrases, target (translated) phrases, and optional definitions. Typically one phrase book - will be created per language and family of applications. Phrase books - are used to provide a common set of translations to help ensure consistency. - They can also be used to avoid duplication of effort since the translations + will be created per language and family of applications. Phrase books + are used to provide a common set of translations to help ensure consistency. + They can also be used to avoid duplication of effort since the translations for a family of applications can be produced once in the phrase book. If the translator reaches an non-translated phrase that is the same as a source phrase in a phrase book, \QL will show the @@ -861,25 +859,25 @@ The phrase book contents can be displayed and changed by selecting \menu{Phrase|Edit Phrase Book}, and then activating the phrase book you want to work on. This will pop up the Phrase Book Dialog as shown - in the image above. To add a new phrase click the \gui{New Phrase} - button (or press Alt+N) and type in a new source phrase. Press Tab and - type in the translation. Optionally press Tab and enter a definition -- - this is useful to distinguish different translations of the same source - phrase. This process may be repeated as often as necessary. You can delete + in the image above. To add a new phrase click the \gui{New Phrase} + button (or press Alt+N) and type in a new source phrase. Press Tab and + type in the translation. Optionally press Tab and enter a definition \mdash + this is useful to distinguish different translations of the same source + phrase. This process may be repeated as often as necessary. You can delete a phrase by selecting it in the phrases list and clicking - Remove Phrase. Click the \gui Close button (press Esc) once you've finished + Remove Phrase. Click the \gui Close button (press Esc) once you've finished adding (and removing) phrases. \section2 Shortcuts for Editing Phrase Books You can also create a new phrase book entry directly out of the translation you are working on: Clicking \menu{Phrases|Add to Phrase Book} or pressing - \key{Ctrl+T} will add the source text and the content of the first translation + \key{Ctrl+T} will add the source text and the content of the first translation field to the current phrase book. If multiple phrase books are loaded, you have to specify the phrase book to add the entry to in a dialogue. - If you detect an error in a phrase book entry that is shown in the - \l{Phrases and Guesses Window}, you can also edit it in place by right - clicking on the entry, and selecting \menu{Edit}. After fixing the error + If you detect an error in a phrase book entry that is shown in the + \l{Phrases and Guesses Window}, you can also edit it in place by right + clicking on the entry, and selecting \menu{Edit}. After fixing the error press \key{Return} to leave the editing mode. \section2 Batch Translation @@ -890,7 +888,7 @@ translate source texts that are also in a phrase book. Selecting \menu{Tools|Batch Translation} will show you the batch translation dialog, which let you configure which phrase books to use in what order during the - batch translation process. Furthermore you can set whether only entries + batch translation process. Furthermore you can set whether only entries with no present translation should be considered, and whether batch translated entries should be set to finished (see also \l {String Translation States}). @@ -929,7 +927,7 @@ 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 + files during the translation process. Activate \menu{Tools|Open/Refresh Form Preview} to open the window shown above. The list of UI files \QL has detected are displayed in the Forms List on the left hand. If the path to the files has changed, you can load @@ -947,17 +945,18 @@ \list \o TS \e {translation source files} \BR are human-readable XML files containing source phrases and their translations. These files are - usually created and updated by \l lupdate and are specific to an - application. + usually created and updated by \l{linguist-manager.html#lupdate}{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. However, for - standard Qt projects, only the TS file format is used. \note The minimum - supported version for XLIFF format files is 1.1. XLIFF 1.0 version files + can be used to edit XLIFF files generated by other programs. However, for + standard Qt projects, only the TS file format is used. \note The minimum + supported version for XLIFF format files is 1.1. XLIFF 1.0 version files are not supported. \o QM \e {Qt message files} \BR are binary files that contain translations used by an application at run-time. These files are - generated by \l lrelease, but can also be generated by \QL. + generated by \l{linguist-manager.html#lrelease}{lrelease}, but can also + be generated by \QL. \o \c .qph \e {Qt phrase book files} \BR are human-readable XML files containing standard phrases and their translations. These files are created and updated by \QL and may be used by any @@ -982,13 +981,15 @@ name, format and/or put in a different location. \o \gui {Release} \BR create a Qt message QM file with the same base name as the current translation source file. The release manager's - command line tool \l lrelease performs the same function on - \e all of an application's translation source files. + command line tool \l{linguist-manager.html#lrelease}{lrelease} + performs the same function on \e all of an application's translation + source files. \o \gui {Release As...} \BR pops up a save as file dialog. The filename entered will be a Qt message QM file of the translation based on the current translation source file. The release manager's - command line tool \l lrelease performs the same function on - \e all of an application's translation source files. + command line tool \l{linguist-manager.html#lrelease}{lrelease} + performs the same function on \e all of an application's translation + source files. \o \gui {Print... Ctrl+P} \BR pops up a print dialog. If you click OK the translation source and the translations will be printed. \o \gui {Exit Ctrl+Q} \BR closes \QL. @@ -1018,10 +1019,10 @@ Source phrases, translations and comments may be searched. \o \gui {Find Next F3} \BR finds the next occurrence of the text that was last entered in the Find dialog. - \o \gui {Search and Translate...} \BR pops up the Search and + \o \gui {Search and Translate...} \BR pops up the Search and Replace Dialog. Use this dialog to translate the same text in multiple items. \o \gui {Translation File Settings...} \BR let you configure the target - language and the country/region of a translation source file. + language and the country/region of a translation source file. \endlist \o \gui {Translation} @@ -1123,7 +1124,7 @@ \o \gui {Manual F1} \BR opens this manual. \o \gui {About Qt Linguist} \BR Shows information about \QL. \o \gui {About Qt} \BR Shows information about \e{Qt}. - \o \gui {What's This? Shift+F1} \BR Click on one item in the main window + \o \gui {What's This? Shift+F1} \BR Click on one item in the main window to get additional information about it. \endlist @@ -1219,6 +1220,7 @@ /*! \page linguist-programmers.html \title Qt Linguist Manual: Programmers + \ingroup internationalization \contentspage {Qt Linguist Manual}{Contents} \previouspage Qt Linguist Manual: Translators @@ -1262,28 +1264,31 @@ Translation files are created as follows: \list 1 - \o Run \l lupdate initially to generate the first set of TS - translation source files with all the user-visible text but no - translations. + \o Run \l {linguist-manager.html#lupdate}{lupdate} initially to + generate the first set of TS translation source files with all the + user-visible text but no translations. \o The TS files are given to the translator who adds translations using \QL. \QL takes care of any changed or deleted source text. - \o Run \l lupdate to incorporate any new text added to the - application. \l lupdate synchronizes the user-visible text from the - application with the translations; it does not destroy any data. + \o Run \l{linguist-manager.html#lupdate}{lupdate} to incorporate any new + text added to the application. \l{linguist-manager.html#lupdate}{lupdate} + synchronizes the user-visible text from the application with the + translations; it does not destroy any data. \o Steps 2 and 3 are repeated as often as necessary. - \o When a release of the application is needed \l lrelease is run to + \o When a release of the application is needed + \l{linguist-manager.html#lrelease}{lrelease} is run to read the TS files and produce the QM files used by the application at runtime. \endlist - For \l lupdate to work successfully, it must know which translation - files to produce. The files are simply listed in the application's \c - .pro Qt project file, for example: + For \l{linguist-manager.html#lupdate}{lupdate} to work successfully, + it must know which translation files to produce. The files are simply + listed in the application's \c .pro Qt project file, for example: \snippet examples/linguist/arrowpad/arrowpad.pro 1 - If your sources contain genuine non-Latin1 strings, \l lupdate needs + If your sources contain genuine non-Latin1 strings, + \l{linguist-manager.html#lupdate}{lupdate} needs to be told about it in the \c .pro file by using, for example, the following line: @@ -1291,7 +1296,8 @@ CODECFORTR = UTF-8 \endcode - See the \l lupdate and \l lrelease sections. + See the \l{linguist-manager.html#lupdate}{lupdate} and + \l{linguist-manager.html#lrelease}{lrelease} sections. \section2 Loading Translations @@ -1333,11 +1339,11 @@ User-visible strings are marked as translation targets by wrapping them in a \c tr() call, for example: - \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 6 + \snippet doc/src/snippets/code/doc_src_linguist-manual.cpp 6 would become - \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 7 + \snippet doc/src/snippets/code/doc_src_linguist-manual.cpp 7 All QObject subclasses that use the \c Q_OBJECT macro implement the \c tr() function. @@ -1346,29 +1352,29 @@ usually called as a member function of a QObject subclass, in other cases an explicit class name can be supplied, for example: - \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 8 + \snippet doc/src/snippets/code/doc_src_linguist-manual.cpp 8 or - \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 9 + \snippet doc/src/snippets/code/doc_src_linguist-manual.cpp 9 \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 - the \c tr() call. This is sufficient in the vast majority of cases. - Sometimes however, the translator will need further information to - uniquely identify a source text; for example, a dialog that contained - two separate frames, each of which contained an "Enabled" option would - need each identified because in some languages the translation would - differ between the two. This is easily achieved using the + The \l{linguist-manager.html#lupdate}{lupdate} program automatically + provides a \e context for every source text. This context is the class + name of the class that contains the \c tr() call. This is sufficient in + the vast majority of cases. Sometimes however, the translator will need + further information to uniquely identify a source text; for example, + a dialog that contained two separate frames, each of which contained an + "Enabled" option would need each identified because in some languages the + translation would differ between the two. This is easily achieved using the two argument form of the \c tr() call, e.g. - \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 10 + \snippet doc/src/snippets/code/doc_src_linguist-manual.cpp 10 and - \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 11 + \snippet doc/src/snippets/code/doc_src_linguist-manual.cpp 11 Ctrl key accelerators are also translatable: @@ -1385,44 +1391,46 @@ solved by adding a comment using the keyword \e TRANSLATOR which describes the navigation steps to reach the text in question; e.g. - \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 12 + \snippet doc/src/snippets/code/doc_src_linguist-manual.cpp 12 These comments are particularly useful for widget classes. \section2 Handling Plural Forms - Qt includes a \c tr() overload that will make it very easy to - write "plural-aware" internationalized applications. This overload + Qt includes a \c tr() overload that will make it very easy to + write "plural-aware" internationalized applications. This overload has the following signature: - \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 17 + \snippet doc/src/snippets/code/doc_src_linguist-manual.cpp 17 - Depending on the value of \c n, the \c tr() function will return a different - translation, with the correct grammatical number for the target language. + Depending on the value of \c n, the \c tr() function will return a different + translation, with the correct grammatical number for the target language. Also, any occurrence of \c %n is replaced with \c{n}'s value. For example: - \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 18 + \snippet doc/src/snippets/code/doc_src_linguist-manual.cpp 18 - If a French translation is loaded, this will expand to "0 item - remplac\unicode{233}", "1 item remplac\unicode{233}", "2 items - remplac\unicode{233}s", etc., depending on \c{n}'s value. - And if no translation is loaded, the original string is used, with \c %n + If a French translation is loaded, this will expand to "0 item + remplac\unicode{233}", "1 item remplac\unicode{233}", "2 items + remplac\unicode{233}s", etc., depending on \c{n}'s value. + And if no translation is loaded, the original string is used, with \c %n replaced with count's value (e.g., "6 item(s) replaced"). - To handle plural forms in the native language, you need to load a - translation file for this language, too. \l lupdate has the + To handle plural forms in the native language, you need to load a + translation file for this language, too. + \l{linguist-manager.html#lupdate}{lupdate} has the \c -pluralonly command line option, which allows the creation of TS files containing only entries with plural forms. - See the \l{http://doc.qt.nokia.com/qq/}{Qt Quarterly} Article + See the \l{http://doc.qt.nokia.com/qq/}{Qt Quarterly} Article \l{http://doc.qt.nokia.com/qq/qq19-plurals.html}{Plural Forms in Translations} for further details on this issue. \section2 Coping With C++ Namespaces C++ namespaces and the \c {using namespace} statement can confuse - \l lupdate. It will interpret \c MyClass::tr() as meaning just - that, not as \c MyNamespace::MyClass::tr(), even if \c MyClass is + \l{linguist-manager.html#lupdate}{lupdate}. It will interpret + \c MyClass::tr() as meaning just that, not as + \c MyNamespace::MyClass::tr(), even if \c MyClass is defined in the \c MyNamespace namespace. Runtime translation of these strings will fail because of that. @@ -1430,7 +1438,7 @@ comment at the beginning of the source files that use \c MyClass::tr(): - \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 13 + \snippet doc/src/snippets/code/doc_src_linguist-manual.cpp 13 After the comment, all references to \c MyClass::tr() will be understood as meaning \c MyNamespace::MyClass::tr(). @@ -1443,20 +1451,21 @@ use either the tr() function of an appropriate class, or the QCoreApplication::translate() function directly: - \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 14 + \snippet doc/src/snippets/code/doc_src_linguist-manual.cpp 14 \section3 Using QT_TR_NOOP() and QT_TRANSLATE_NOOP() If you need to have translatable text completely outside a function, there are two macros to help: QT_TR_NOOP() and QT_TRANSLATE_NOOP(). - These macros merely mark the text for extraction by \l{lupdate}. + These macros merely mark the text for extraction by + \l{linguist-manager.html#lupdate}{lupdate}. The macros expand to just the text (without the context). Example of QT_TR_NOOP(): - \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 15 + \snippet doc/src/snippets/code/doc_src_linguist-manual.cpp 15 Example of QT_TRANSLATE_NOOP(): - \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 16 + \snippet doc/src/snippets/code/doc_src_linguist-manual.cpp 16 \section1 Tutorials @@ -1484,8 +1493,9 @@ applications for translation. At the beginning of a project add the translation source files to be - used to the project file and add calls to \l lupdate and \l lrelease to - the makefile. + used to the project file and add calls to + \l{linguist-manager.html#lupdate}{lupdate} and + \l{linguist-manager.html#lrelease}{lrelease} to the Makefile. During the project all the programmer must do is wrap any user-visible text in \c tr() calls. They should also use the two argument form for @@ -1498,6 +1508,7 @@ /*! \page linguist-ts-file-format.html \title Qt Linguist Manual: TS File Format + \ingroup internationalization \contentspage {Qt Linguist Manual}{Contents} \previouspage Qt Linguist Manual: Programmers @@ -1508,5 +1519,5 @@ may change in future Qt releases. \quotefile tools/linguist/shared/ts.dtd - + */ diff --git a/doc/src/ja_JP/development/qmake-manual.qdoc b/doc/src/ja_JP/development/qmake-manual.qdoc index a6cfe3d..3b908f7 100644 --- a/doc/src/ja_JP/development/qmake-manual.qdoc +++ b/doc/src/ja_JP/development/qmake-manual.qdoc @@ -58,16 +58,16 @@ æ–°ã—ã„行を作りã€\c{SOURCES +=}ã€ç¶šã„㦠hello.cpp を入力ã—ã¾ã™ã€‚ ã¤ã¾ã‚Šã€ä»¥ä¸‹ã®ã‚ˆã†ã«ãªã‚Šã¾ã™: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 108 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 108 ã“れを以下ã®ã‚ˆã†ã«ãªã‚‹ã¾ã§ãƒ—ãƒã‚¸ã‚§ã‚¯ãƒˆã®å„ソースファイルã«å¯¾ã—ã¦è¡Œã„ã¾ã™: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 109 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 109 make ã«ä¼¼ãŸã‚·ãƒ³ã‚¿ãƒƒã‚¯ã‚¹ã‚’使ã„ãŸã„å ´åˆã¯ã€ 以下ã®ã‚ˆã†ã«æ”¹è¡Œã‚’エスケープã—ã¦ã™ã¹ã¦ã®ãƒ•ã‚¡ã‚¤ãƒ«ã‚’ 1 è¡Œã«æ›¸ãã¾ã™: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 110 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 110 ソースファイルã®ä¸€è¦§ã‚’プãƒã‚¸ã‚§ã‚¯ãƒˆãƒ•ã‚¡ã‚¤ãƒ«ã«è¿½åŠ ã—ã¾ã—ãŸã€‚ 次ã«ãƒ˜ãƒƒãƒ€ãƒ•ã‚¡ã‚¤ãƒ«ã‚’è¿½åŠ ã—ã¾ã™ã€‚ @@ -77,7 +77,7 @@ ã“れを終ãˆã‚‹ã¨ã€ãƒ—ãƒã‚¸ã‚§ã‚¯ãƒˆãƒ•ã‚¡ã‚¤ãƒ«ã¯ä»¥ä¸‹ã®ã‚ˆã†ã«ãªã‚‹ã§ã—ょã†: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 111 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 111 ターゲットã®åå‰ã¯è‡ªå‹•çš„ã«è¨å®šã•ã‚Œã€ プãƒã‚¸ã‚§ã‚¯ãƒˆãƒ•ã‚¡ã‚¤ãƒ«ã¨åŒã˜åå‰ã«ãªã‚Šã¾ã™ã€‚ @@ -86,7 +86,7 @@ ターゲット㯠Windows ã§ã¯ \c hello.exe ã€Unix ã§ã¯ \c hello ã«ãªã‚Šã¾ã™ã€‚ プãƒã‚¸ã‚§ã‚¯ãƒˆãƒ•ã‚¡ã‚¤ãƒ«ã§åˆ¥ã®åå‰ã‚’指定ã™ã‚‹ã“ã¨ã‚‚ã§ãã¾ã™: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 112 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 112 最後㫠\l{qmake Variable Reference#CONFIG}{CONFIG} 変数をè¨å®šã—ã¾ã™ã€‚ ã“ã®ã‚¢ãƒ—リケーション㯠Qt アプリケーションãªã®ã§ \c CONFIG ã« @@ -96,19 +96,19 @@ 最終的ãªãƒ—ãƒã‚¸ã‚§ã‚¯ãƒˆãƒ•ã‚¡ã‚¤ãƒ«ã¯ä»¥ä¸‹ã®ã‚ˆã†ã«ãªã‚Šã¾ã™: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 113 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 113 \c qmake を使ã£ã¦ã€ã“ã®ã‚¢ãƒ—リケーションã®ãŸã‚ã® Makefile を生æˆã—ã¾ã™ã€‚ プãƒã‚¸ã‚§ã‚¯ãƒˆã®ãƒ‡ã‚£ãƒ¬ã‚¯ãƒˆãƒªã§ã‚³ãƒžãƒ³ãƒ‰ãƒ©ã‚¤ãƒ³ã«æ¬¡ã®ã‚ˆã†ã«å…¥åŠ›ã—ã¾ã™: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 114 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 114 ãã—ã¦ã€ä½¿ç”¨ã™ã‚‹ã‚³ãƒ³ãƒ‘イラã«ã‚ˆã£ã¦ \c make ã¾ãŸã¯ \c nmake を入力ã—ã¾ã™ã€‚ Visual Studio ユーザã®å ´åˆã€\c qmake ã¯ã€ä»¥ä¸‹ã®ã‚ˆã†ã« \c .dsp ファイルã¾ãŸã¯ \c .vcproj ファイルも作æˆã§ãã¾ã™: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 115 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 115 \section1 アプリケーションをデãƒãƒƒã‚°ã§ãるよã†ã«ã™ã‚‹ @@ -119,7 +119,7 @@ ãŸã¨ãˆã°: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 116 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 116 ç›´å‰ã®ä¾‹ã¨åŒæ§˜ã«ã€Makefile を生æˆã™ã‚‹ã«ã¯ \c qmake を使ã„ã¾ã™ã€‚ アプリケーションをデãƒãƒƒã‚°ç’°å¢ƒã§å®Ÿè¡Œã™ã‚‹éš›ã«å½¹ã«ç«‹ã¤æƒ…å ±ã‚’å¾—ã‚‰ã‚Œã‚‹ã‚ˆã†ã«ãªã‚Šã¾ã™ã€‚ @@ -137,7 +137,7 @@ Windows 用ã®ãƒ•ã‚¡ã‚¤ãƒ«ã‚’è¿½åŠ ã™ã‚‹ã‚·ãƒ³ãƒ—ルãªã‚¹ã‚³ãƒ¼ãƒ—ã¯ä»¥ä¸‹ã®ã‚ˆã†ã«ãªã‚Šã¾ã™: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 117 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 117 \c qmake ㌠Windows 上ã§å®Ÿè¡Œã•ã‚Œã‚‹ã¨ã€ã‚½ãƒ¼ã‚¹ãƒ•ã‚¡ã‚¤ãƒ«ã®ãƒªã‚¹ãƒˆã« \c hellowin.cpp ãŒè¿½åŠ ã•ã‚Œã¾ã™ã€‚ @@ -146,7 +146,7 @@ ã“れを終ãˆã‚‹ã¨ã€ãƒ—ãƒã‚¸ã‚§ã‚¯ãƒˆãƒ•ã‚¡ã‚¤ãƒ«ã¯ä»¥ä¸‹ã®ã‚ˆã†ã«ãªã‚Šã¾ã™: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 118 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 118 ã“ã‚Œã¾ã§ã¨åŒæ§˜ã«ã€Makefile を生æˆã™ã‚‹ã«ã¯ \c qmake を使ã„ã¾ã™ã€‚ @@ -159,13 +159,13 @@ 使ã„æ–¹ã¯ã‚¹ã‚³ãƒ¼ãƒ—ã®æ¡ä»¶ã‚’ã“れらã®é–¢æ•°ã§ç½®ãæ›ãˆã‚‹ã ã‘ã§ã™ã€‚ \c main.cpp ファイルã®ç¢ºèªã¯ä»¥ä¸‹ã®ã‚ˆã†ã«ãªã‚Šã¾ã™ : - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 119 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 119 è¨˜å· \c{!} ã¯ãƒ†ã‚¹ãƒˆã‚’å¦å®šã—ã¾ã™ã€‚ ã¤ã¾ã‚Š \c{exists( main.cpp )} ã¯ãƒ•ã‚¡ã‚¤ãƒ«ãŒå˜åœ¨ã™ã‚‹å ´åˆã«çœŸã«ãªã‚Šã€ \c{!exists( main.cpp )} ã¯ãƒ•ã‚¡ã‚¤ãƒ«ãŒå˜åœ¨ã—ãªã„å ´åˆã«çœŸã«ãªã‚Šã¾ã™ã€‚ - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 120 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 120 å‰ã¨åŒæ§˜ã«ã€\c qmake を実行ã—㦠Makefile を生æˆã—ã¾ã™ã€‚ 仮㫠\c main.cpp ã®åå‰ã‚’変更ã™ã‚‹ã¨ã€ä¸Šè¨˜ã®ãƒ¡ãƒƒã‚»ãƒ¼ã‚¸ãŒè¡¨ç¤ºã•ã‚Œã€ @@ -185,12 +185,12 @@ ã¾ãš 1 ã¤ã®ã‚¹ã‚³ãƒ¼ãƒ—を作æˆã—ã€ãã®ä¸ã«ã‚‚ㆠ1 ã¤ã‚¹ã‚³ãƒ¼ãƒ—を作æˆã—ã¾ã™ã€‚ ãã—㦠2 ã¤ã®ã‚¹ã‚³ãƒ¼ãƒ—ã®ä¸ã«è¨å®šã‚’書ãã¾ã™ã€‚例ãˆã°: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 121 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 121 ãƒã‚¹ãƒˆã•ã‚ŒãŸã‚¹ã‚³ãƒ¼ãƒ—ã¯ã‚³ãƒãƒ³ã‚’使ã£ã¦ã¤ãªãã“ã¨ãŒã§ãã¾ã™ã€‚ 最終的ãªãƒ—ãƒã‚¸ã‚§ã‚¯ãƒˆãƒ•ã‚¡ã‚¤ãƒ«ã¯ä»¥ä¸‹ã®ã‚ˆã†ã«ãªã‚Šã¾ã™: - \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 122 + \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 122 以上ã§ã™ã€‚\c qmake ã®ãƒãƒ¥ãƒ¼ãƒˆãƒªã‚¢ãƒ«ãŒçµ‚了ã—ã¾ã—ãŸã€‚ ãã‚Œã§ã¯ã€ã‚ãªãŸã®é–‹ç™ºãƒ—ãƒã‚¸ã‚§ã‚¯ãƒˆã®ãƒ—ãƒã‚¸ã‚§ã‚¯ãƒˆãƒ•ã‚¡ã‚¤ãƒ«ã‚’作æˆã—ã¦ã¿ã¾ã—ょã†ã€‚ diff --git a/doc/src/ja_JP/development/qtestlib.qdoc b/doc/src/ja_JP/development/qtestlib.qdoc index c1001dc..3ff1f36 100644 --- a/doc/src/ja_JP/development/qtestlib.qdoc +++ b/doc/src/ja_JP/development/qtestlib.qdoc @@ -71,7 +71,7 @@ 次ã«ã€ãƒ†ã‚¹ãƒˆé–¢æ•°ã‚’実装ã—ã¾ã™ã€‚実装ã¯ä»¥ä¸‹ã®ã‚ˆã†ã«ãªã‚Šã¾ã™: - \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 8 + \snippet doc/src/snippets/code/doc_src_qtestlib.cpp 8 \l QVERIFY() マクãƒã¯ã€å¼•æ•°ã¨ã—ã¦æ¸¡ã•ã‚Œã‚‹å¼ã‚’評価ã—ã¾ã™ã€‚ å¼ãŒçœŸã¨è©•ä¾¡ã•ã‚Œã‚‹ã¨ãƒ†ã‚¹ãƒˆé–¢æ•°ã®å®Ÿè¡ŒãŒç¶™ç¶šã•ã‚Œã¾ã™ã€‚ @@ -131,7 +131,7 @@ ã“ã‚Œã¾ã§ã¯ã€ãƒ†ã‚¹ãƒˆãƒ‡ãƒ¼ã‚¿ã‚’テスト関数ã«ãƒãƒ¼ãƒ‰ã‚³ãƒ¼ãƒ‰ã—ã¦ã„ã¾ã—ãŸã€‚ ã“ã®å ´åˆã€ãƒ†ã‚¹ãƒˆãƒ‡ãƒ¼ã‚¿ã‚’è¿½åŠ ã—ãŸé–¢æ•°ã¯ä»¥ä¸‹ã®ã‚ˆã†ã«ãªã‚Šã¾ã™: - \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 11 + \snippet doc/src/snippets/code/doc_src_qtestlib.cpp 11 関数ãŒç¹°ã‚Šè¿”ã—ã‚’è¡Œã†ã‚³ãƒ¼ãƒ‰ã«ã‚ˆã£ã¦åˆ†æ•£ã™ã‚‹ã®ã‚’防ããŸã‚ã«ã€ QTestLib ã¯ãƒ†ã‚¹ãƒˆãƒ‡ãƒ¼ã‚¿ã®ãƒ†ã‚¹ãƒˆé–¢æ•°ã¸ã®è¿½åŠ をサãƒãƒ¼ãƒˆã—ã¾ã™ã€‚ diff --git a/doc/src/ja_JP/examples/arrowpad.qdoc b/doc/src/ja_JP/examples/arrowpad.qdoc index 9085654..56f14a1 100644 --- a/doc/src/ja_JP/examples/arrowpad.qdoc +++ b/doc/src/ja_JP/examples/arrowpad.qdoc @@ -71,7 +71,7 @@ \c Q_OBJECT ã®ãƒžã‚¯ãƒã¯ã€ä»¥ä¸‹ã®å†…容㧠\c ArrowPad ã« \c tr(x) を定義ã—ã¾ã™: - \snippet doc/src/snippets/code/doc_src_examples_arrowpad.qdoc 0 + \snippet doc/src/snippets/code/doc_src_examples_arrowpad.cpp 0 å„ソーステã‚ストãŒè¡¨ç¤ºã•ã‚Œã‚‹ã‚¯ãƒ©ã‚¹ã‚’把æ¡ã—ã¦ãŠãã¨ã€ \e {Qt Linguist} ã§è«–ç†çš„ã«é–¢é€£ã®ã‚ã‚‹æ–‡å—列をグループ化ã™ã‚‹ã“ã¨ãŒå‡ºæ¥ã¾ã™ã€‚ diff --git a/doc/src/ja_JP/examples/trollprint.qdoc b/doc/src/ja_JP/examples/trollprint.qdoc index dfe7eaa..ddc6880 100644 --- a/doc/src/ja_JP/examples/trollprint.qdoc +++ b/doc/src/ja_JP/examples/trollprint.qdoc @@ -136,12 +136,12 @@ 変更ã™ã¹ãè¡Œã¯4è¡Œã‚ã‚Šã¾ã™ã€‚ ラジオボタンã®æœ€åˆã®ãƒšã‚¢ã® \c tr() 呼ã³å‡ºã—ã«ã€2ã¤ç›®ã®å¼•æ•° "two-sided"(両é¢) ã‚’ã«è¿½åŠ ã—ã¾ã™: - \snippet doc/src/snippets/code/doc_src_examples_trollprint.qdoc 0 + \snippet doc/src/snippets/code/doc_src_examples_trollprint.cpp 0 ãã—ã¦ã€ãƒ©ã‚¸ã‚ªãƒœã‚¿ãƒ³ã®2番目ã®ãƒšã‚¢ã® \c tr() 呼ã³å‡ºã—ã«ã€ 2ã¤ç›®ã®å¼•æ•° "colors"(色) ã‚’è¿½åŠ ã—ã¾ã™ã€‚ - \snippet doc/src/snippets/code/doc_src_examples_trollprint.qdoc 1 + \snippet doc/src/snippets/code/doc_src_examples_trollprint.cpp 1 ã“ã“ã§ã€\c lupdate を実行ã—ã€\e {Qt Linguist} 㧠\c trollprint_pt.ts ã‚’é–‹ãã¾ã™ã€‚2 ã¤ã®å¤‰æ›´å€‹æ‰€ãŒã‚ã‹ã‚‹ã¯ãšã§ã™ã€‚ @@ -184,7 +184,7 @@ ã“ã‚Œã¯ã€ã‚½ãƒ¼ã‚¹ã‚³ãƒ¼ãƒ‰ã§ \c TRANSLATOR コメントを使用ã—ã¦è¡Œã„ã¾ã™: - \snippet doc/src/snippets/code/doc_src_examples_trollprint.qdoc 2 + \snippet doc/src/snippets/code/doc_src_examples_trollprint.cpp 2 一部ã®ã‚½ãƒ¼ã‚¹ãƒ•ã‚¡ã‚¤ãƒ«ã€ç‰¹ã«ãƒ€ã‚¤ã‚¢ãƒã‚°ã‚¯ãƒ©ã‚¹ã®ã‚³ãƒ¡ãƒ³ãƒˆã« ダイアãƒã‚°ã«åˆ°é”ã™ã‚‹ã¾ã§ã«å¿…è¦ãªæ“作を記述ã—ã¾ã™ã€‚ @@ -201,7 +201,7 @@ コメントã¯å½¹ç«‹ã¤ãƒŠãƒ“ã‚²ãƒ¼ã‚·ãƒ§ãƒ³æƒ…å ±ã‚’æä¾›ã™ã‚‹ãŸã‚〠翻訳ã«è¦ã™ã‚‹æ™‚間を節約ã§ãã¾ã™: - \snippet doc/src/snippets/code/doc_src_examples_trollprint.qdoc 3 + \snippet doc/src/snippets/code/doc_src_examples_trollprint.cpp 3 \section1 Troll Print 1.1 diff --git a/doc/src/legal/qtquicklicense.qdoc b/doc/src/legal/qtquicklicense.qdoc new file mode 100644 index 0000000..aa9e201 --- /dev/null +++ b/doc/src/legal/qtquicklicense.qdoc @@ -0,0 +1,40 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qtquicklicense.html + \title Qt Quick Licensing Information + \ingroup licensing + \brief Qt Quick and QtDeclarative Licensing Information. + + +Applications created using Qt Quick are subject to the terms and conditions of the GNU Lesser General Public License as Qt Quick includes dependencies to QtScript and JavaScriptCore which are licensed under the terms of the GNU Library General Public License ("LGPL"). Qt Commercial Edition licensees that wish to distribute applications that use the Qt Quick need to be aware of their obligations under the LGPL. Individual contributor names and copyright dates can be found inline in the code. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + +On the Qt web site, you can find a +\l{Qt Licensing Overview} and information on \l{Qt License Pricing} +for commercial editions of Qt and other Qt-related products. +*/ diff --git a/doc/src/mainpage.qdoc b/doc/src/mainpage.qdoc new file mode 100644 index 0000000..269dc52 --- /dev/null +++ b/doc/src/mainpage.qdoc @@ -0,0 +1,232 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page gettingstarted-develop.html +\title Develop with Qt +\ingroup gettingstarted + +\div {class="indexboxcont indexboxbar"} +Developing a Qt application involves many different steps and stages. From +configuring Creator to distributing binaries to different platforms, Qt provides +many options along the way. +\image quick_screens.png +\enddiv + +\div {class="indexboxcont indexboxbar normallist"} +\keyword qt-creator-configure-target +\section1 Configuring Qt and Creator Targets +Qt and Creator are configurable to compile applications on many platform targets +and multiple platforms. + +\section2 Configuring Creator for Qt Development: +Creator is the integrated development environment for developing Qt applications. +Creator encompasses every step of application development from interface design +to application testing and deployment. +\list +\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-project-managing.html}{Creating Qt Projects} +\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-building-running.html}{Building and Running Applications} + \list + \o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-running-targets.html}{Targets} - edit and set compiler targets + \o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-build-settings.html}{Build Settings} - edit and set build configurations + \o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-run-settings.html}{Run Settings} - edit and set application run settings + \endlist +\o \l{http://doc.qt.nokia.com/nokia-qtsdk-1.0/creator-developing-symbian.html}{Setting Up Development Environment for Symbian} +\o \l{http://doc.qt.nokia.com/nokia-qtsdk-1.0/creator-developing-maemo.html}{Setting Up Development Environment for Maemo} +\endlist + +\keyword qt-platform-support +\section2 Qt Platform Support +Alternatively, Qt may be installed on its own without the Nokia Qt SDK. + +Information regarding Qt Support on Different Platforms: +\list +\o \l{Installing Qt for the Symbian platform}{Symbian and Mobile Development} +\o \l{Support for Windows}{Microsoft Windows} +\o \l{Support for Windows CE and Windows Mobile}{Microsoft Windows CE} +\o \l{Support for Mac OS X}{Apple Mac OS X} +\o \l{Support for Linux/X11}{Linux and X11 Platforms} +\o \l{Support for Embedded Linux}{Qt for Embedded Linux} +\endlist +For more information about the platforms supported +and their installation pages, view the \l {Supported Platforms} and the +\l {Cross-Platform and Platform-Specific Development} pages. +\enddiv + +\div {class="indexboxcont indexboxbar normallist"} +\keyword qt-technologies +\section1 Qt Technologies + +Qt introduces an innovative alternative for inter-object communication, called +"signals and slots", that replaces the old and unsafe callback technique used in +many legacy frameworks. Qt also provides a conventional event model for handling +mouse clicks, key presses, and other user input. Qt's cross-platform GUI +applications can support all the user interface functionality required by modern +applications, such as menus, context menus, drag and drop, and dockable +toolbars. Desktop integration features provided by Qt can be used to extend +applications into the surrounding desktop environment, taking advantage of some +of the services provided on each platform. + +The \l{All Modules}{Qt Modules} page has a listing of the technology modules offered by Qt. + +\keyword qt-desktop-meta-object-system +\section2 Qt's Meta-Object System +Qt offers a unique event system based on meta-objects, signals and slots, and property systems. +\list +\o \l{The Meta-Object System}{Qt's Meta-Object System} - Qt's mechanism for signals and slots, inter-object communication, run-time type information, and dynamic property system +\o \l{The Event System}{Event System} - event handling and delivery +\o \l{The Property System}{Property System} - dynamic object properties +\endlist + +\keyword qt-ui-creation +\section2 UI Creation +Qt offers several options with regards to user interface creation: widget based +applications using layouts and Qt Quick interfaces with QML. +\list +\o \l{Qt Quick} - create UIs using QML + \list + \o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-visual-editor.html}{Creator's QML Design Mode} - design Qt Quick interfaces using Creator's design mode + \endlist +\o \l{Widgets and Layouts} - primary elements for C++ based interfaces + \list + \o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-using-qt-designer.html}{Creator's Designer} - design interfaces using Qt Designer. + \endlist +\o \l{UI Design with Qt} - covers many Qt features for UI creation +\endlist + +\section2 Inter-Process Communication, Threading, and Networking +In addition to \l{qt-desktop-meta-object-system}{Qt's Meta-Object System}, Qt has several technologies +that deal with inter-process communication. +\list +\o \l{Inter-Process Communication in Qt}{Inter-Process Communication} - various overviews of protocols implemented in Qt +\o \l{Network programming with Qt}{Network Programming} - various overviews to network APIs +\o \l{D-Bus} - D-Bus implementation in Qt +\o \l{Thread Support in Qt}{Thread Support} - overview of threading APIs and concurrent programming topics +\endlist + +\keyword qt-rendering-painting-system +\section2 Rendering and Paint System +Qt has various support for different rendering and painting methods. +\list +\o \l{Coordinate System} - Information about the coordinate system used by the paint system +\o \l{Graphics View Framework} - manages a large number of 2D items and visualizes the items +\o \l{Paint System} - A system for painting on the screen or on print devices using the same API +\o \l{QtSvg Module} - module for displaying and creating SVG files +\o Rendering APIs: + \list + \o \l{QtOpenGL Module} - module for rendering with the OpenGL API + \o \l{OpenVG Rendering in Qt}{QtOpenVG Module} - provides support for OpenVG painting + \endlist +\o \l{Printing with Qt} - A guide to producing printed output with Qt's paint system and widgets. +\endlist + +\keyword qt-webkit +\section2 QtWebKit Module +Web applications are increasing in importance and abundance and Qt has +\l{http://www.webkit.org/}{WebKit} support. +\list +\o \l{WebKit in Qt} - WebKit Module +\endlist + +\keyword qt-utilities +\section2 Utilities +Qt supports many utilities that work on multiple platforms. +\list +\o \l{Container Classes}{Containers} - Qt's implementation of various data structures such as linked lists and hash maps +\o \l{Rich Text Processing} - for manipulating structured rich text documents +\o \l{XML Processing} - high level manipulation of XML data using different interfaces +\o \l{Making Applications Scriptable} - provides Qt applications with ECMAScript processor. +\o \l{Qt Linguist Manual}{Qt Linguist} - for translating applications into local languages. +\endlist +For more information, visit the \l{Qt's Tools}{Qt Tools} page. +\enddiv +\div {class="indexboxcont indexboxbar normallist"} +\keyword qt-testing +\section1 Testing Qt Applications +Testing and debugging are part of the development process and Qt offers the +developer multiple methods of testing their code. +\list +\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-debugging.html} {Debugging Applications in Creator} - various debugging options in Creator +\o \l {http://doc.qt.nokia.com/qtsimulator/index.html}{Simulator} - testing mobile applications by simulating a mobile environment +\o \l {QML Viewer} - an executable that is able to run QML files +\o \l{QTestLib Manual}{QTestLib} - a unit testing framework built into Qt +\endlist +\enddiv + +\div {class="indexboxcont indexboxbar normallist"} +\keyword qt-deployment +\section1 Deployment +Symbian phones, Maemo devices, desktop environments, embedded Linux devices -- Qt applications are deployable to many environments. +To deploy Qt applications onto multiple platforms, there are special +considerations that each platform introduce. +\list +\o \l{Deploying Qt Applications}{Deploying Qt Libraries} - compares static versus shared libraries and deploying Qt libraries +\o \l{Deploying Qt Applications#licensing}{Deploying Third Party Libraries} - deployment of libraries that are not under Qt's dual-license model. +\o Platform-Specific Deployment: + \list + \o \l{Deploying an Application on X11 Platforms}{X11} - deploying Qt applications on X11 platforms + \o \l{Deploying an Application on Windows}{Windows} - deploying Qt applications on Windows operating systems + \o \l{Deploying an Application on Mac OS X}{Mac OS X} - deploying Qt applications on Mac OS X + \o \l{Deploying Qt for Embedded Linux Applications}{Embedded Linux} - deploying Qt applications on embedded Linux + \o \l{Deploying an Application on the Symbian Platform}{Symbian} - deploying Qt applications on the Symbian platform + \endlist +\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-deployment-symbian.html}{Symbian Deployment in Creator} - Symbian application deployment built into Creator +\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-deployment-maemo.html}{ Deploying Qt Applications on Maemo Devices} +\endlist + +\section1 Ovi Store Publishing +Creator can publish applications to Ovi Store directly. +\list +\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-publish-ovi.html}{Publishing Qt Applications to Ovi Store} +\endlist +For additional information, visit the \l{Cross-Platform and Platform-Specific Development} +and the \l {Supported Platforms} page. + +\enddiv +\div {class="indexboxcont indexboxbar normallist"} +\section1 Where to Go from Here + +Qt Demos and Examples +\list +\o \l{Qt Demonstrations}{Application Gallery} +\o \l{Tutorials} +\o \l {Qt Examples} +\o \l {QML Examples and Demos} +\endlist + +Qt Information +\list +\o \l{Programming with Qt} +\o \l{UI Design with Qt} +\o \l{Cross-platform and Platform-specific Development} +\o \l{Qt and Key Technologies} +\o \l{Best Practice Guides} +\o \l{Qt Licenses and Credits}{Licenses and Credits} +\endlist +\enddiv +*/ + diff --git a/doc/src/modules.qdoc b/doc/src/modules.qdoc index 38a7a8b..30b0f16 100644 --- a/doc/src/modules.qdoc +++ b/doc/src/modules.qdoc @@ -70,7 +70,7 @@ modules are included by default. To link only against QtCore, add the following line to your \c .pro file: - \snippet doc/src/snippets/code/doc_src_modules.qdoc 0 + \snippet doc/src/snippets/code/doc_src_modules.pro 0 On Windows, if you do not use \l qmake or other build tools such as CMake, you also need to link against @@ -91,7 +91,7 @@ All other Qt modules rely on this module. To include the definitions of the module's classes, use the following directive: - \snippet doc/src/snippets/code/doc_src_qtcore.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qtcore.cpp 0 */ @@ -105,7 +105,7 @@ To include the definitions of both modules' classes, use the following directive: - \snippet doc/src/snippets/code/doc_src_qtgui.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qtgui.pro 0 */ /*! @@ -118,12 +118,12 @@ To include the definitions of the module's classes, use the following directive: - \snippet doc/src/snippets/code/doc_src_qtmultimedia.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qtmultimedia.cpp 1 To link against the module, add this line to your \l qmake \c .pro file: - \snippet doc/src/snippets/code/doc_src_qtmultimedia.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qtmultimedia.pro 0 The functionality provided by the \l{Phonon Module} is on a higher level and in many cases more suitable for application developers. @@ -140,12 +140,12 @@ To include the definitions of the module's classes, use the following directive: - \snippet doc/src/snippets/code/doc_src_qtnetwork.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qtnetwork.cpp 1 To link against the module, add this line to your \l qmake \c .pro file: - \snippet doc/src/snippets/code/doc_src_qtnetwork.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qtnetwork.pro 0 */ /*! @@ -175,12 +175,12 @@ To include the definitions of the module's classes, use the following directive: - \snippet doc/src/snippets/code/doc_src_qtopengl.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qtopengl.cpp 0 To link against the module, add this line to your \l qmake \c .pro file: - \snippet doc/src/snippets/code/doc_src_qtopengl.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qtopengl.pro 1 The Qt OpenGL module is implemented as a platform-independent Qt/C++ wrapper around the platform-dependent GLX (version 1.3 or later), @@ -266,11 +266,11 @@ To include the definitions of the module's classes, use the following directive: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 0 To link against the module, add this line to your \l qmake \c .pro file: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qtscript.pro 1 For detailed information on how to make your application scriptable with QtScript, see \l{Making Applications @@ -323,11 +323,11 @@ To include the definitions of the module's classes, use the following directive: - \snippet doc/src/snippets/code/doc.src.qtscripttools.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qtscripttools.cpp 0 To link against the module, add this line to your \l qmake \c .pro file: - \snippet doc/src/snippets/code/doc.src.qtscripttools.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qtscripttools.pro 1 */ /*! @@ -338,12 +338,12 @@ To include the definitions of the module's classes, use the following directive: - \snippet doc/src/snippets/code/doc_src_qtsql.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qtsql.cpp 0 To link against the module, add this line to your \l qmake \c .pro file: - \snippet doc/src/snippets/code/doc_src_qtsql.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qtsql.pro 1 See the \l{SQL Programming} guide for information about using this module in your applications. @@ -362,12 +362,12 @@ To include the definitions of the module's classes, use the following directive: - \snippet doc/src/snippets/code/doc_src_qtsvg.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qtsvg.cpp 0 To link against the module, add this line to your \l qmake \c .pro file: - \snippet doc/src/snippets/code/doc_src_qtsvg.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qtsvg.pro 1 \section1 License Information @@ -412,12 +412,12 @@ To include the definitions of the module's classes, use the following directive: - \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qtxml.cpp 0 To link against the module, add this line to your \l qmake \c .pro file: - \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qtxml.pro 1 Further XML support is provided by the \l{Qt Solutions} group who provide, for example, classes that support SOAP and MML with the @@ -437,12 +437,12 @@ To include the definitions of the module's classes, use the following directive: - \snippet doc/src/snippets/code/doc_src_qtxmlpatterns.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qtxmlpatterns.cpp 0 To link against the module, add this line to your \l qmake \c .pro file: - \snippet doc/src/snippets/code/doc_src_qtxmlpatterns.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qtxmlpatterns.pro 1 \section1 Further Reading @@ -523,7 +523,7 @@ The following declaration in a \c qmake project file ensures that an application is compiled and linked appropriately: - \snippet doc/src/snippets/code/doc_src_phonon.qdoc 1 + \snippet doc/src/snippets/code/doc_src_phonon.pro 0 \section1 Qt Backends @@ -586,12 +586,12 @@ To include the definitions of the module's classes, use the following directive: - \snippet doc/src/snippets/code/doc_src_qt3support.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qt3support.cpp 0 To link against the module, add this line to your \l qmake \c .pro file: - \snippet doc/src/snippets/code/doc_src_qt3support.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qt3support.pro 1 \note Since this module provides compatibility classes for diverse parts of the Qt 3 API, it has dependencies on the QtCore, @@ -615,12 +615,12 @@ To include the definitions of the module's classes, use the following directive: - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 0 To link against the module, add this line to your \c qmake .pro file: - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qtdesigner.pro 1 */ /*! @@ -640,7 +640,7 @@ in a \c qmake project file to ensure that the application is compiled and linked appropriately. - \snippet doc/src/snippets/code/doc_src_qtuiloader.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qtuiloader.pro 0 A form loader object, provided by the QUiLoader class, is used to construct the user interface. This user interface can @@ -652,7 +652,7 @@ To include the definitions of the module's classes, use the following directive: - \snippet doc/src/snippets/code/doc_src_qtuiloader.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qtuiloader.cpp 1 \sa{Calculator Builder Example}, {World Time Clock Builder Example} */ @@ -672,7 +672,7 @@ To include the definitions of the module's classes, use the following directive: - \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qthelp.cpp 0 To link against the module, add this line to your \l qmake \c .pro file: @@ -731,12 +731,12 @@ To include the definitions of the module's classes, use the following directive: - \snippet doc/src/snippets/code/doc_src_qttest.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qttest.cpp 0 To link against the module, add this line to your \l qmake \c .pro file: - \snippet doc/src/snippets/code/doc_src_qttest.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qttest.pro 1 See the \l{QTestLib Manual} for a detailed introduction on how to use Qt's unit testing features with your applications. @@ -865,13 +865,13 @@ To use this module, use the following code in your application: - \snippet doc/src/snippets/code/doc_src_qtdbus.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qtdbus.cpp 0 If you're using qmake to build your application, you can add this line to your .pro file to make it link against the QtDBus libraries: - \snippet doc/src/snippets/code/doc_src_qtdbus.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qtdbus.pro 1 \note The source code for this module is located in the \c{src/qdbus} directory. When installing Qt from source, this module is built when Qt's diff --git a/doc/src/objectmodel/objecttrees.qdoc b/doc/src/objectmodel/objecttrees.qdoc index ba677b9..cb63c17 100644 --- a/doc/src/objectmodel/objecttrees.qdoc +++ b/doc/src/objectmodel/objecttrees.qdoc @@ -77,7 +77,7 @@ behavior applies. Normally, the order of destruction still doesn't present a problem. Consider the following snippet: - \snippet doc/src/snippets/code/doc_src_objecttrees.qdoc 0 + \snippet doc/src/snippets/code/doc_src_objecttrees.cpp 0 The parent, \c window, and the child, \c quit, are both \l {QObject} {QObjects} because QPushButton inherits QWidget, and QWidget inherits @@ -91,7 +91,7 @@ But now consider what happens if we swap the order of construction, as shown in this second snippet: - \snippet doc/src/snippets/code/doc_src_objecttrees.qdoc 1 + \snippet doc/src/snippets/code/doc_src_objecttrees.cpp 1 In this case, the order of destruction causes a problem. The parent's destructor is called first because it was created last. It then calls diff --git a/doc/src/objectmodel/properties.qdoc b/doc/src/objectmodel/properties.qdoc index 7d1ecec..92c182e 100644 --- a/doc/src/objectmodel/properties.qdoc +++ b/doc/src/objectmodel/properties.qdoc @@ -46,12 +46,12 @@ To declare a property, use the \l {Q_PROPERTY()} {Q_PROPERTY()} macro in a class that inherits QObject. - \snippet doc/src/snippets/code/doc_src_properties.qdoc 0 + \snippet doc/src/snippets/code/doc_src_properties.cpp 0 Here are some typical examples of property declarations taken from class QWidget. - \snippet doc/src/snippets/code/doc_src_properties.qdoc 1 + \snippet doc/src/snippets/code/doc_src_properties.cpp 1 A property behaves like a class data member, but it has additional features accessible through the \l {Meta-Object System}. @@ -83,6 +83,10 @@ existing signal in that class that is emitted whenever the value of the property changes. + \o A \c REVISION number is optional. If included, it defines the + the property and its notifier signal to be used in a particular + revision of the API that is exposed to QML. + \o The \c DESIGNABLE attribute indicates whether the property should be visible in the property editor of GUI design tool (e.g., \l {Qt Designer}). Most properties are \c DESIGNABLE (default @@ -131,7 +135,7 @@ be a user-defined type. In this example, class QDate is considered to be a user-defined type. - \snippet doc/src/snippets/code/doc_src_properties.qdoc 2 + \snippet doc/src/snippets/code/doc_src_properties.cpp 2 Because QDate is user-defined, you must include the \c{<QDate>} header file with the property declaration. @@ -152,7 +156,7 @@ the code snippet below, the call to QAbstractButton::setDown() and the call to QObject::setProperty() both set property "down". - \snippet doc/src/snippets/code/doc_src_properties.qdoc 3 + \snippet doc/src/snippets/code/doc_src_properties.cpp 3 Accessing a property through its \c WRITE accessor is the better of the two, because it is faster and gives better diagnostics at @@ -162,7 +166,7 @@ can \e discover a class's properties at run time by querying its QObject, QMetaObject, and \l {QMetaProperty} {QMetaProperties}. - \snippet doc/src/snippets/code/doc_src_properties.qdoc 4 + \snippet doc/src/snippets/code/doc_src_properties.cpp 4 In the above snippet, QMetaObject::property() is used to get \l {QMetaProperty} {metadata} about each property defined in some @@ -189,7 +193,7 @@ for the \c READ and \c WRITE functions. The declaration of MyClass then might look like this: - \snippet doc/src/snippets/code/doc_src_properties.qdoc 5 + \snippet doc/src/snippets/code/doc_src_properties.cpp 5 The \c READ function is const and returns the property type. The \c WRITE function returns void and has exactly one parameter of @@ -200,7 +204,7 @@ QObject that is an instance of MyClass, we have two ways to set its priority property: - \snippet doc/src/snippets/code/doc_src_properties.qdoc 6 + \snippet doc/src/snippets/code/doc_src_properties.cpp 6 In the example, the enumeration type that is the property type is declared in MyClass and registered with the \l{Meta-Object System} @@ -262,7 +266,7 @@ Q_CLASSINFO(), that can be used to attach additional \e{name}--\e{value} pairs to a class's meta-object, for example: - \snippet doc/src/snippets/code/doc_src_properties.qdoc 7 + \snippet doc/src/snippets/code/doc_src_properties.cpp 7 Like other meta-data, class information is accessible at run-time through the meta-object; see QMetaObject::classInfo() for details. diff --git a/doc/src/objectmodel/signalsandslots.qdoc b/doc/src/objectmodel/signalsandslots.qdoc index 4c018b5..8b52df5 100644 --- a/doc/src/objectmodel/signalsandslots.qdoc +++ b/doc/src/objectmodel/signalsandslots.qdoc @@ -440,7 +440,7 @@ You can even use both mechanisms in the same project. Just add the following line to your qmake project (.pro) file. - \snippet doc/src/snippets/code/doc_src_containers.qdoc 22 + \snippet doc/src/snippets/code/doc_src_containers.cpp 22 It tells Qt not to define the moc keywords \c{signals}, \c{slots}, and \c{emit}, because these names will be used by a 3rd party diff --git a/doc/src/overviews.qdoc b/doc/src/overviews.qdoc index f51e320..eb9b2be 100644 --- a/doc/src/overviews.qdoc +++ b/doc/src/overviews.qdoc @@ -42,8 +42,8 @@ Qt is a cross-platform application and UI framework for writing web-enabled applications for desktop, mobile, and embedded operating systems. This page contains links to articles and overviews - explaining key components and techniques used in Qt development. - + explaining key components and techniques used in Qt development. + \generatelist {related} */ @@ -62,7 +62,7 @@ /*! \group qt-graphics - \ingroup qt-basic-concepts + \ingroup qt-basic-concepts \title Qt Graphics and Printing \brief The Qt components for doing graphics. @@ -112,7 +112,7 @@ \ingroup technology-apis \ingroup best-practices \ingroup qt-basic-concepts - + These pages document Qt's API's for using SQL database systems in Qt applications. @@ -133,7 +133,7 @@ \generatelist{related} */ -/*! +/*! \group licensing \title Qt Licenses and Credits @@ -146,3 +146,56 @@ \generatelist {related} */ + +/*! + \group qml-best-practices + \title QML Best Practices Guides + + \brief QML Programming Best Practices Guides + + These documents provide guidelines and best practices for using QML and Qt + to solve specific technical problems. + + \generatelist {related} +*/ +/*! + \group qml-features + \title QML Features + + \brief Features of the QML Language + +These are overviews of the many features of the QML language and \l{Qt Quick}. + +\list +\o \l{QML Basic Elements}{Basic Elements} +\o \l{QML Basic Types}{Data Types} +\o \l{Property Binding} +\o \l{Using QML Positioner and Repeater Items}{Component Layouts} +\o \l{Anchor-based Layout in QML}{Layouts using Anchors} +\o \l{QML Mouse Events}{Mouse Events} +\o \l{QML Text Handling and Validators}{Text Handling and Validators} +\o \l{Keyboard Focus in QML}{Keyboard Focus} +\o \l{QML Signal and Handler Event System}{Signal and Handler Event System} +\o \l{Importing Reusable Components} +\o \l{QML States}{States} +\o \l{QML Animation and Transitions}{Animation and Transitions} +\o \l{QML Data Models}{Structuring Data with Models} +\o \l{Presenting Data with Views} +\o \l{Extending QML Functionalities using C++} +\o \l{Using QML Bindings in C++ Applications} +\o \l{Integrating QML Code with Existing Qt UI Code} +\o \l{Dynamic Object Management in QML}{Dynamic Object Management} +\o \l{Network Transparency}{Loading Resources in QML} +\o \l{QML Internationalization}{Internationalization} +\endlist +*/ +/*! + \group qml-architecture + \title QML Architecture + + \brief QML Architecture + + These are overviews of the architecture of QML and Qt Declarative Module. + + \generatelist {related} +*/ diff --git a/doc/src/painting-and-printing/coordsys.qdoc b/doc/src/painting-and-printing/coordsys.qdoc index 252159e..d0906d8 100644 --- a/doc/src/painting-and-printing/coordsys.qdoc +++ b/doc/src/painting-and-printing/coordsys.qdoc @@ -97,10 +97,10 @@ \row \o - \snippet doc/src/snippets/code/doc_src_coordsys.qdoc 0 + \snippet doc/src/snippets/code/doc_src_coordsys.cpp 0 \o - \snippet doc/src/snippets/code/doc_src_coordsys.qdoc 1 + \snippet doc/src/snippets/code/doc_src_coordsys.cpp 1 \endtable When rendering with a pen with an even number of pixels, the @@ -163,10 +163,10 @@ \row \o - \snippet doc/src/snippets/code/doc_src_coordsys.qdoc 2 + \snippet doc/src/snippets/code/doc_src_coordsys.cpp 2 \o - \snippet doc/src/snippets/code/doc_src_coordsys.qdoc 3 + \snippet doc/src/snippets/code/doc_src_coordsys.cpp 3 \endtable \section1 Transformations @@ -319,7 +319,7 @@ -50) to (50, 50) with (0, 0) in the center by calling the QPainter::setWindow() function: - \snippet doc/src/snippets/code/doc_src_coordsys.qdoc 4 + \snippet doc/src/snippets/code/doc_src_coordsys.cpp 4 Now, the logical coordinates (-50,-50) correspond to the paint device's physical coordinates (0, 0). Independent of the paint @@ -333,7 +333,7 @@ viewport and "window" maintain the same aspect ratio to prevent deformation: - \snippet doc/src/snippets/code/doc_src_coordsys.qdoc 5 + \snippet doc/src/snippets/code/doc_src_coordsys.cpp 5 If we make the logical coordinate system a square, we should also make the viewport a square using the QPainter::setViewport() diff --git a/doc/src/platforms/emb-performance.qdoc b/doc/src/platforms/emb-performance.qdoc index 1ae35bc..6c96921 100644 --- a/doc/src/platforms/emb-performance.qdoc +++ b/doc/src/platforms/emb-performance.qdoc @@ -103,7 +103,7 @@ operators. Improved memory allocation and performance may be gained by re-implementing these functions: - \snippet doc/src/snippets/code/doc_src_emb-performance.qdoc 1 + \snippet doc/src/snippets/code/doc_src_emb-performance.cpp 1 The example above shows the necessary code to switch to the plain C memory allocators. diff --git a/doc/src/platforms/emb-pointer.qdoc b/doc/src/platforms/emb-pointer.qdoc index b580077..941cba2 100644 --- a/doc/src/platforms/emb-pointer.qdoc +++ b/doc/src/platforms/emb-pointer.qdoc @@ -144,7 +144,7 @@ its headers using -L and -I options in the \c qmake.conf file in your \c mkspec. Also it can be helpful to add a -rpath-link: - \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 7 + \snippet doc/src/snippets/code/doc_src_emb-pointer.pro 7 In order to use this mouse driver, tslib must also be correctly installed on the target machine. This includes providing a \c diff --git a/doc/src/platforms/mac-differences.qdoc b/doc/src/platforms/mac-differences.qdoc index 251e900..1f71270 100644 --- a/doc/src/platforms/mac-differences.qdoc +++ b/doc/src/platforms/mac-differences.qdoc @@ -99,7 +99,7 @@ If you use \c qmake and Makefiles, use the \c QMAKE_LFLAGS_SONAME setting: - \snippet doc/src/snippets/code/doc_src_mac-differences.qdoc 0 + \snippet doc/src/snippets/code/doc_src_mac-differences.pro 0 Alternatively, you can modify the install name using the install_name_tool(1) on the command line. See its manpage for more @@ -165,7 +165,7 @@ the bundle resides on the disk. The following code returns the path of the application bundle: - \snippet doc/src/snippets/code/doc_src_mac-differences.qdoc 1 + \snippet doc/src/snippets/code/doc_src_mac-differences.cpp 1 Note: When OS X is set to use Japanese, a bug causes this sequence to fail and return an empty string. Therefore, always test the diff --git a/doc/src/platforms/supported-platforms.qdoc b/doc/src/platforms/supported-platforms.qdoc index b58d1d7..f1e8004 100644 --- a/doc/src/platforms/supported-platforms.qdoc +++ b/doc/src/platforms/supported-platforms.qdoc @@ -26,10 +26,688 @@ ****************************************************************************/ /*! + \page windows-support.html + \title Support for Windows + \brief Platform support for Windows. + \ingroup platform-specific + \ingroup platform-details + + \section1 Qt on Windows + + Qt is a comprehensive application and UI framework for developing Windows + applications that can also be deployed across many other desktop and + embedded operating systems without rewriting the source code. Use the + code from one single code-base and rebuild for all + \l{Supported Platforms}{supported Windows versions and other platforms}. + + \section1 Getting Started on Windows + + \list + \o \l{Supported Platforms}{Supported Windows platforms} - Qt + supports a wide range of Windows platforms. + \o \l{Qt for Windows Requirements}{Qt for Windows Requirements} + - Requirements for developing with Qt on Windows. + \o \l{Installing Qt for Windows}{Installing Qt for Windows} + - Build Qt for Windows development. + \o \l{Platform and Compiler Notes - Windows}{Platform and Compiler Notes - Windows} + - Windows platform specific notes. + \o \l{Getting Started Guides}{Getting started} - Getting started developing for Windows + \endlist + + \section1 Key Features for Windows Development + + \section2 Rich Class Library + + The Qt class library includes all the functionality needed to build + advanced GUI applications. + + \list + \o Complete set of customizable \l{UI Design with Qt}{UI + controls/widgets} + \o 3D graphics support with \l{QtOpenGL Module}{OpenGL} + or Direct3D + \o Powerful \l{Thread Support in Qt}{multi-threading} features + \o \l{Graphics View Framework}{2D graphics canvas} capable of + handling millions of items + \o Integrated \l{Phonon multimedia framework}{Phonon multimedia + framework} + \o \l{WebKit in Qt}{WebKit} integration + \o \l{Network programming with Qt}{Networking}, \l{QtXml Module} + {XML} and \l{SQL in Qt}{database} functionality + \o \l{ECMAScript Reference}{ECMA standard} scripting engine + \endlist + + \section2 Integrated Development Tools + + Qt includes a set of integrated development tools to speed + development on the Windows platform. + + \list + \o \l{Qt Designer Manual}{Qt Designer} provides a drag and drop + visual GUI builder. + \o \l{Qt Linguist Manual}{Qt Linguist} provides internationalization + and translation features. + \o \l{Qt Assistant Manual}{Qt Assistant} is a customizable HTML help + file reader providing the complete Qt documentation offline. + \endlist + + \section2 Cross-Platform Development using Qt Creator + + \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is + a complete Cross-platform IDE included in the Qt SDK. The IDE allows + programmers to create, build, debug and run Qt applications accross all + supported platforms. + + \section2 Visual Studio Add-in. + + The Qt Visual Studio Add-in allows programmers to create, build, debug + and run Qt applications from within Microsoft Visual Studio 2005, 2008 + and 2010. The add-in contains project wizards, Qt project import/export + support, integrated Qt resource manager and automated build setup for + the Qt Meta-Object Compiler, User Interface Compiler, and Resource + Compiler. + + Additional \l{Cross-Platform and Platform-Specific Development} + information. +*/ + +/*! + \page linuxX11-support.html + \title Support for Linux/X11 + \brief Platform support for Linux/X11. + \ingroup platform-specific + \ingroup platform-details + + \section1 Qt on Linux/X11 + + Qt is a comprehensive application and UI framework for developing + Linux/X11 applications that can also be deployed across many other + desktop and embedded operating systems without rewriting the source code. + Use the code from one single code-base and rebuild for all + \l{Supported Platforms}{supported X11 versions and other platforms}. + + \section1 Getting Started on Linux/X11 + + \list + \o \l{Supported Platforms}{Supported Linux/X11 platforms} - Qt + supports a wide range of Linux/X11 platforms. + \o \l{Qt for X11 Requirements}{Qt for X11 Requirements} + - Software required to run Qt on Linux/X11. + \o \l{Installing Qt for X11 Platforms}{Installing Qt for X11 Platforms} + - Build Qt for Linux/X11 development. + \o \l{Platform and Compiler Notes - X11}{Platform and Compiler Notes - X11} + - Platform specific notes. + \o \l{Getting Started Guides}{Getting started} + \endlist + + \section1 Key Features for Linux/X11 Development + + \section2 Integrated Development Tools + + Qt includes a set of integrated development tools to speed development + on X11 platforms. + + \list + \o \l{Qt Designer Manual}{Qt Designer} provides a drag and drop + visual GUI builder. + \o \l{Qt Linguist Manual}{Qt Linguist} provides internationalization + and translation features. + \o \l{Qt Assistant Manual}{Qt Assistant} is a customizable HTML help + file reader providing the complete Qt documentation offline. + \o Integration with + \l{http://doc.qt.nokia.com/qt-eclipse-1.6/index.html}{Eclipse} + and KDevelop IDEs are also available. + \endlist + + \section2 Cross-Platform Development using Qt Creator + + \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is + a complete Cross-platform IDE included in the Qt SDK. The IDE allows + programmers to create, build, debug and run Qt applications accross all + supported platforms. + + \section2 Rich Class Library + + The Qt class library includes all the functionality needed to build + advanced GUI applications. + + \list + \o Complete set of customizable \l{UI Design with Qt}{UI + controls/widgets} + \o 3D graphics support with \l{QtOpenGL Module}{OpenGL + integration} + \o Powerful \l{Thread Support in Qt}{multi-threading} features + \o \l{Graphics View Framework}{2D graphics canvas} capable of + handling millions of items + \o Integrated \l{Phonon multimedia framework}{Phonon multimedia + framework} + \o \l{WebKit in Qt}{WebKit} integration + \o \l{Network programming with Qt}{Networking}, \l{QtXml Module} + {XML} and \l{SQL in Qt}{database} functionality + \o \l{ECMAScript Reference}{ECMA standard} scripting engine + \endlist + + \section2 Qt is the Foundation of KDE + + Qt is best known in the Linux community as the basis for the KDE + desktop environment. Almost everything in KDE is based on Qt, and + Qt forms the foundation for thousands of open source KDE applications + developed by community members worldwide. + + Additional \l{Cross-Platform and Platform-Specific Development} + information. + +*/ + +/*! + \page mac-support.html + \title Support for Mac OS X + \brief Platform support for Mac OS X. + \ingroup platform-specific + \ingroup platform-details + + \section1 Qt on Mac OS X + + Qt is a comprehensive application and UI framework for developing Mac + applications that can also be deployed across many other desktop and + embedded operating systems without rewriting the source code. Use the + code from one single code-base and rebuild for all + \l{Supported Platforms}{supported Windows versions and other platforms}. + + \section1 Getting Started on Mac + + \list + \o \l{Supported Platforms}{Supported Mac OS X platforms} - Qt supports + a wide range of Mac platform variants. + \o \l{Qt for Mac OS X Requirements}{Qt for Mac OS X Requirements} + - Software required to run Qt on Mac OS X. + \o \l{Installing Qt for X11 Platforms}{Installing Qt for X11 Platforms} + - Build Qt for Mac OS X development. + \o \l{Platform and Compiler Notes - Mac OS X}{Platform and Compiler Notes - Mac OS X} + - Platform specific notes. + \o \l{Getting Started Guides}{Getting started} + \endlist + + \section1 Key Features for Mac OS X Development + + \section2 Integrated Development Tools + + Qt includes a set of integrated development tools to speed development + on the Mac platform. + + \list + \o \l{Qt Designer Manual}{Qt Designer} provides a drag and drop + visual GUI builder. + \o \l{Qt Linguist Manual}{Qt Linguist} provides internationalization + and translation features. + \o \l{Qt Assistant Manual}{Qt Assistant} is a customizable HTML help + file reader providing the complete Qt documentation offline. + \endlist + + \section2 Cross-Platform Development using Qt Creator + + \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is + a complete Cross-platform IDE included in the Qt SDK. The IDE allows + programmers to create, build, debug and run Qt applications accross all + supported platforms. + + \section2 Rich Class Library + + The Qt class library includes all the functionality needed to build + advanced GUI applications. + + \list + \o Complete set of customizable \l{UI Design with Qt}{UI + controls/widgets} + \o 3D graphics support with \l{QtOpenGL Module}{OpenGL + integration} + \o Powerful \l{Thread Support in Qt}{multi-threading} features + \o \l{Graphics View Framework}{2D graphics canvas} capable of + handling millions of items + \o Integrated \l{Phonon multimedia framework}{Phonon multimedia + framework} + \o \l{WebKit in Qt}{WebKit} integration + \o \l{Network programming with Qt}{Networking}, \l{QtXml Module} + {XML} and \l{SQL in Qt}{database} functionality + \o \l{ECMAScript Reference}{ECMA standard} scripting engine + \endlist + + \section3 Supports Intel Hardware and Universal Binaries + + Qt is written without making assumptions about the number representation, + endianness or architecture of the underlying processor. To support Intel + hardware on the Apple platforms, Qt customers simply need to recompile + their apps. + + Additional \l{Cross-Platform and Platform-Specific Development} + information. + + \note Qt also provides support for 64-bit applications on top of Cocoa APIs. +*/ +/*! + \page windowsCE-Mobile-support.html + \title Support for Windows CE and Windows Mobile + \brief Platform support for Windows CE and Windows Mobile. + \ingroup platform-specific + \ingroup platform-details + + \section1 Qt on Windows CE and Windows Mobile + + Qt is a C++ application and UI framework. You can use Qt to write + rich and high performance applications using an intuitive API + available for a wide range of devices. Use the code from one single + code-base and rebuild for all \l{Supported Platforms}{supported + Windows CE/Mobile versions as well as other other platforms}. + + Supporting most existing Windows CE configurations and with minimal + hardware dependencies, Qt is easy to build even for custom hardware + configurations. Unused components and features can even be compiled out. + + \section1 Getting Started on Windows CE/Mobile + + \list + \o \l{Supported Platforms}{Supported Windows CE/Mobile platforms} + - Qt supports a wide range of Windows CE/Mobile platform variants. + \o \l{Qt for Windows CE Requirements}{Qt for Windows CE/Mobile + Requirements} - Software required to run Qt on Windows CE/Mobile. + \o \l{Installing Qt for Windows CE}{Installing Qt for + Windows CE/Mobile Platforms} - Build Qt for Windows CE/Mobile + development. + \o \l{Platform and Compiler Notes - Windows CE}{Platform and + Compiler Notes - Windows CE/Mobile} - Platform specific notes. + \o \l{Getting Started Guides}{Getting started} + \endlist + + \section1 Key Features for Windows CE/Mobile Development + + On top of all the tools and API and class libraries that Qt offers, + Qt for Windows CE provides you with added functionality for an + optimized embedded development environment. + + \section2 Native and Customizable Look and Feel + + Windows Mobile and Windows CE styles are available with Qt. At runtime, + Qt applications will detect which style to use. The look and feel of + your applications can also be easily customized in a fraction of + the time and lines of code required for traditional UI styling with + Qt Style Sheets. + + \section2 Advanced Text Layout Engine + + Qt for Windows CE supports TrueType® and raster fonts. Qt also has + extended Unicode support and right-to-left languages. Qt’s rich text + engine adds capabilities for complex text layouts including tables, + path tracing and text which flows around shapes. + + \section2 Qt for Windows CE/Mobile also provide support for: + + \list + \o Graphics Acceleration using \l{Qt for Windows CE and OpenGL + ES}{OpenGL ES} + \o \l{Graphics View Framework}{2D graphics canvas} capable of + handling millions of items. + \o \l{Qt Designer Manual}{Qt Designer} for GUI layout and + forms builder. + \o \l{Qt Linguist Manual}{Qt Linguist} provides internationalization + and translation features. + \endlist + + Applications created with Qt for Windows CE/Mobile can be ported to + Symbian, Maemo and any other OS that Qt supports. + + Additional \l{Cross-Platform and Platform-Specific Development} + information. + +*/ + +/*! + \page embeddedLinux-support.html + \title Support for Embedded Linux + \brief Platform support for Embedded Linux. + \ingroup platform-specific + \ingroup platform-details + + \section1 Qt on Embedded Linux + + Qt is the leading application and UI framework for devices powered + by embedded Linux. You can use Qt to create highly memory efficient + devices and applications that have completely unique user experiences. + + Qt runs anywhere Linux runs. Qt’s intuitive API means fewer lines of + code and higher level functionality in less time. Use the code from + one single code-base and rebuild for all \l{Supported Platforms} + {supported platforms}. + + \section1 Getting Started on Embedded Linux + + \list + \o \l{Supported Platforms}{Supported Linux platforms} + - Qt supports a wide range of Linux platform variants. + \o \l{Qt for Embedded Linux Requirements}{Qt for Embedded Linux + Requirements} - Software required to run Qt on Embedded Linux. + \o \l{Installing Qt for Embedded Linux}{Installing Qt for Embedded + Linux} - Build Qt for development on Embedded Linux. + \o \l{Platform and Compiler Notes - Embedded Linux}{Platform and + Compiler Notes - Embedded Linux} - Platform specific notes. + \o \l{Getting Started Guides}{Getting started} + \endlist + + \section1 Key Features for Embedded Linux Development + + On top of all the tools and API and class libraries that Qt offers, + such as WebKit, Qt for Embedded Linux provides you with key components + for an optimized embedded development environment. + + \section2 Compact and Efficient Windowing System \l{Qt for Embedded Linux Classes}{QWS} + + Qt builds on the standard API for embedded Linux devices with its own + compact window system. Qt-based applications write directly to the + Linux framebuffer, eliminating the need for the X11 windowing system. + + \section2 Virtual Frame Buffer (QVFb) + + Qt for Embedded Linux provides a \l{The Virtual Framebuffer}{virtual + frame buffer} that will match the physical device display, pixel for + pixel. This gives the developer a realistic testing infrastructure + testing on the desktop where the frame buffer simulates the physical + device display’s width, height and color depth. + + \section2 Inter-Process Communication (IPC) + + IPC allows for creation of rich multi-application user experiences. + Two main concepts define inter-process communication: channels and + messages. + + \section2 Extended Font Format + + Qt supports a wide range of font formats on embedded Linux including: + TrueType®, Postscript® Type1 and Qt pre-rendered fonts. Qt has + extended Unicode support including automatic data extraction at build + time and automatic update at runtime. + + Plug-ins for custom font formats are also available allowing new font + engines to be easily added at runtime. Font sharing capabilities + between applications allow for increased memory efficiency. + + Applications created with Qt for Embedded Linux can be ported to + Windows CE and any other OS that Qt supports. + + Additional \l{Cross-Platform and Platform-Specific Development} + information. + +*/ +/*! + \page symbian-support.html + \title Support for Symbian + \brief Platform support for Symbian. + \ingroup platform-specific + \ingroup platform-details + + \section1 Qt on Symbian + + Qt provides support for the Symbian platform with integration + to the S60 framework. If you are developing apps for the Symbian, + Maemo or MeeGo platforms in most cases, you can use Qt under the + free LGPL licensing option. Qt is cross-platform, and that means + that you can use the code from one single code-base and rebuild + for all \l{Supported Platforms}{supported platforms}. + + \section1 Getting Started on Symbian + + \list + \o \l{Supported Platforms}{Supported platform} + - Details on the Qt support for Symbian. + \o \l{Qt for the Symbian platform Requirements}{Qt for the + Symbian platform Requirements} - Software required to run Qt + on Symbian. + \o \l{Installing Qt for the Symbian platform}{Installing Qt + for the Symbian platform} - Build Qt for Symbian development. + \o \l{Platform and Compiler Notes - Symbian}{Platform Notes - Symbian} + - Platform specific notes. + \o \l{Getting Started Guides}{Getting started} + \endlist + + \section1 Key Features for Symbian Development + + On top of all the tools and the API and class libraries that Qt + offers, Qt provides you with added functionality for an optimized + Symbian development experience. + + \section2 Native Look and Feel + + Qt will detect which theme the phone is running and applies the + style at runtime to your Qt application. The look and feel of your + applications can also be easily customized in a fraction of the + time and lines of code required for traditional UI styling with + Qt Style Sheets. + + \section2 Graphics Features + + Qt for Symbian contains a powerful paint engine that provides + features such as anti, aliasing, gradients, curves and transparency. + It also has animation support with timelines and easing curves. It + is already targeting future device technology by supporting hardware + acceleration using OpenVG. + + \section2 Device Configurations + + Using Qt for Symbian all supported Symbian devices provides automatic + support for swiching between landscape and portrait mode, different + screen resolutions as well as touch screen and key pad input. + + \section2 Cross-Platform Development using Qt Creator + + \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is + a complete Cross-platform IDE included in the Qt SDK. The IDE allows + programmers to create, build, debug and run Qt applications accross all + supported platforms. + + \section3 Licensing + + Qt for Symbian is available under the Qt Commercial License, the LGPL + v. 2.1 "LGPL") and the GPL v. 3.0. Symbian currently licenses their + software products under either the Symbian Foundation License or the + Eclipse Public License ("EPL"). While the LGPL and the EPL are not + compatible and may not be combined on a file-by-file basis, they may + be used in a common environment provided that the interaction between + Qt and Symbian is limited to: dynamic linking, inter-process + communication and data exchange. Therefore, most Symbian developers + can use Qt for Symbian under the LGPL. + + Additional \l{Cross-Platform and Platform-Specific Development} + information. + +*/ +/*! + \page maemo-support.html + \title Support for Maemo + \brief Platform support for Maemo. + \ingroup platform-specific + \ingroup platform-details + + \section1 Qt on Maemo + + Qt is a comprehensive application and UI framework for developing + Maemo applications that can also be deployed across major + device and desktop operating systems without rewriting the source code. + If you are developing apps for the Symbian, Mameo platforms + in most cases, you can use Qt under the free LGPL licensing option. + Qt is cross-platform, and that means that you can use the code from + one single code-base and rebuild for all \l{Supported Platforms} + {supported platforms}. Maemo 6 is now MeeGo. + + \section1 Getting Started on Maemo + \list + \o \l{Supported Platforms}{Supported Maemo platforms} + - Qt support for Maemo versions. + \omit + \o \l{Qt for Maemo Requirements}{Qt for Maemo + Requirements} - Software required to run Qt on Maemo. + \o \l{Installing Qt for Maemo}{Installing Qt for + Maemo} - Build Qt for Maemo development. + \o \l{Platform and Compiler Notes - Maemo}{Platform and + Compiler Notes - Maemo} - Platform specific notes. + \endomit + \o \l{Getting Started Guides}{Getting started} + \endlist + + \section1 Key Features for Maemo Development + + \section2 Native Look and Feel + + Qt will detect which theme the device is running and applies the + style at runtime to your Qt application. Widgets are optimized + for touch screen usage. + + \section2 Graphics Features + + Qt for Maemo provides a powerful paint engine that cotain + features such as anti aliasing, gradients, curves and transparency. + It also has animation support with timelines and easing curves. Qt + for Maemo also supports hardware acceleration using ARM NEON + and OpenGL ES 2.0. + + \section2 Device Configurations + + Applications developed with Qt for Maemo will across all + supported Maemo devices provide automatic support for switching + between landscape and portrait mode. They will support input methods, + including predictive text input and on-screen keyboard. The + applications will also have support for one finger touch events and + gestures, and have configurable kinetic scrolling. + + \section2 Maemo - Linux/X11 + + Qt supports a wide range of X11 platform variants, such as: Solaris, + AIX, HP-UX, Maemo 5 and MeeGo. Qt for Maemo contains all Qt modules + and features the same functionality as the Qt on X11 version. + + \section2 Cross-Platform Development using Qt Creator + + \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is + a complete Cross-platform IDE included in the Qt SDK. The IDE allows + programmers to create, build, debug and run Qt applications accross all + supported platforms. + + Additional \l{Cross-Platform and Platform-Specific Development} + information. +*/ + +/*! + + \page meego-support.html + \title Support for MeeGo + \brief Platform support for MeeGo. + \ingroup platform-specific + \ingroup platform-details + + \section1 Qt on MeeGo + + Qt is a comprehensive application and UI framework for developing + MeeGo applications that can also be deployed across major + device and desktop operating systems without rewriting the source code. + If you are developing apps for the Symbian, MeeGo platforms + in most cases, you can use Qt under the free LGPL licensing option. + Qt is cross-platform, and that means that you can use the code from + one single code-base and rebuild for all \l{Supported Platforms} + {supported platforms}. + + \section1 Getting Started on MeeGo + + \list + \o \l{Supported Platforms}{Supported MeeGo platforms} + - Qt support for MeeGo versions. + \omit + \o \l{Qt for MeeGo Requirements}{Qt for MeeGo + Requirements} - Software required to run Qt on MeeGo. + \o \l{Installing Qt for MeeGo}{Installing Qt for + MeeGo} - Build Qt for MeeGo development. + \o \l{Platform and Compiler Notes - MeeGo}{Platform and + Compiler Notes - MeeGo} - Platform specific notes. + \endomit + \o \l{Getting Started Guides}{Getting started} + \endlist + + \section1 Key Features for MeeGo Development + + \section2 Native Look and Feel + + Qt will detect which theme the device is running and applies the + style at runtime to your Qt application. Widgets are optimized + for touch screen usage. + + \section2 Graphics Features + + Qt for MeeGo provides a powerful paint engine that cotain + features such as anti aliasing, gradients, curves and transparency. + It also has animation support with timelines and easing curves. Qt + for MeeGo also supports hardware acceleration using ARM NEON, x86, + and OpenGL ES 2.0. + + \section2 Device Configurations + + Qt is the foundation of MeeGo UI and application development and + therefore Qt will be present in all upcoming MeeGo devices. Qt + can provide automatic support for: + \list + \o Switching between landscape and portrait mode + \o Input Methods, including predictive text input and on-screen + keyboard + \o Configurable kinetic scrolling + \endlist + + \section2 Maemo - Linux/X11 + + Qt supports a wide range of X11 platform variants, such as: Solaris, + AIX, HP-UX, Maemo 5 and MeeGo. Qt for MeeGo contains all Qt modules + and features the same functionality as the Qt on X11 version. + + \section2 Cross-Platform Development using Qt Creator + + \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is + a complete Cross-platform IDE included in the Qt SDK. The IDE allows + programmers to create, build, debug and run Qt applications accross all + supported platforms. + + Additional \l{Cross-Platform and Platform-Specific Development} + information. +*/ + +/*! \page supported-platforms.html \title Supported Platforms \brief The platforms supported by Nokia for Qt. \ingroup platform-specific + \group platform-details + + Qt is a cross-platform application and UI framework. Using Qt, + you can write web-enabled applications once and deploy them + across desktop, mobile and embedded operating systems without + rewriting the source code. + + \section1 Qt is Available for the Following Platforms + + \table + \header + \o {2,1} Qt Cross Platform Support + \header + \o {1,1} Desktop + \o {1,1} Mobile/Embedded + \row + \o \l{Support for Windows}{Windows} + \o \l{Support for Windows CE and Windows Mobile}{Windows CE and Windows Mobile} + \row + \o \l{Support for Linux/X11}{Linux/X11} + \o \l{Support for Embedded Linux}{Embedded Linux} + \row + \o \l{Support for Mac OS X}{Mac OS X} + \o \l{Support for Symbian}{Symbian} + \row + \o\l{Support for MeeGo}{MeeGo} + \o\l{Support for Maemo}{Maemo} + \endtable + + \section1 Supported Platform Details The Qt team strives to provide support for the platforms most frequently used by Qt users. We have designed our internal testing procedure to @@ -70,7 +748,7 @@ \o MSVC 2008 \row \o Microsoft Windows 7 \o MSVC 2008 - \row \o Apple Mac OS X 10.6 "Snow Leopard" + \row \o Apple Mac OS X 10.6 "Snow Leopard" \o As provided by Apple \row \o Apple Mac OS X 10.5 "Leopard" x86_64 (Cocoa 32 and 64bit) \o As provided by Apple @@ -78,6 +756,10 @@ \o gcc (\l{http://www.codesourcery.com/}{Codesourcery version)} \row \o Windows CE 5.0 (ARMv4i, x86, MIPS) \o MSVC 2005 WinCE 5.0 Standard (x86, pocket, smart, mipsii) + \row \o Maemo 5(Linux, ARM, X11) + \o gcc (\l{http://www.scratchbox.org/}{Scratchbox)} + \row \o MeeGo (Linux, ARM, X11) + \o gcc (\l{http://www.scratchbox.org/}{Scratchbox)} \row \o Symbian (Symbian/S60 5.0) \o RVCT 2.2 [build 686 or later], WINSCW 3.2.5 [build 482 or later], GCCE (for applications) \endtable @@ -85,9 +767,9 @@ \section1 Tier 2 Platforms Tier 2 platforms are subject to ad hoc and internal testing. However, Qt users - should note that errors may be present in released product versions for Tier 2 - platforms and, subject to resource availability, known errors in Tier 2 platforms - may or may not be corrected prior to new version releases. + should note that errors may be present in released product versions for Tier 2 + platforms and, subject to resource availability, known errors in Tier 2 platforms + may or may not be corrected prior to new version releases. \table \header \o Platform @@ -116,15 +798,13 @@ \o MSVC 2005 WinCE 5.0 Standard (x86, pocket, smart, mipsii) \row \o Windows Embedded CE 6.0 (ARMv4i, x86, MIPS) \o MSVC 2008 WinCE Embedded 6.0 Professional - \row \o Maemo 5(Linux, ARM, X11) - \o gcc (\l{http://www.scratchbox.org/}{Scratchbox)} \row \o Symbian (Symbian/S60 3.1, 3.2) \o RVCT 2.2 [build 686 or later], WINSCW 3.2.5 [build 482 or later], GCCE (for applications) \endtable - \note The PPC architecture on Mac has been downgraded from tier 1 to tier 2 for 4.7. - - \section1 Tier 3 Platforms (Not supported by Nokia) + \note The PPC architecture on Mac has been downgraded from tier 1 to tier 2 for 4.7. + + \section1 Tier 3 Platforms (Not Supported by Nokia) All platforms not specifically listed above are not supported by Nokia. Nokia does not run its unit test suite or perform any other internal tests on platforms not @@ -147,7 +827,7 @@ warranties and conditions, either express or implied, including, but not limited to, implied warranties of merchantability, fitness for a particular purpose, title and non-infringement with regard to the Licensed Software. - + \section1 Planned Changes for Qt 4.8 The following changes to the list of supported platforms are at time of publishing diff --git a/doc/src/platforms/wince-customization.qdoc b/doc/src/platforms/wince-customization.qdoc index a59dd6f..49ba852 100644 --- a/doc/src/platforms/wince-customization.qdoc +++ b/doc/src/platforms/wince-customization.qdoc @@ -146,7 +146,7 @@ application that attempts to dynamically load the Qt for Windows CE libraries using \c LoadLibrary. The following code can be used for this: - \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 9 + \snippet doc/src/snippets/code/doc_src_wince-customization.cpp 9 Once you have compiled and deployed the application as well as the Qt libraries, start a remote debugger. The debugger will then print the diff --git a/doc/src/porting/porting-qsa.qdoc b/doc/src/porting/porting-qsa.qdoc index ea83e97..e831583 100644 --- a/doc/src/porting/porting-qsa.qdoc +++ b/doc/src/porting/porting-qsa.qdoc @@ -64,7 +64,7 @@ can have named properties. For instance to create an point object with the properties x and y one would write the following Qt Script code: - \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 0 + \snippet doc/src/snippets/code/doc_src_porting-qsa.js 0 The object \c point in this case is constructed as a plain object and we assign two properties, \c x and \c y, to it with the values 12 and @@ -73,17 +73,17 @@ global namespace of the script engine. Similarly, global functions are named properties of the global object; for example: - \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 1 + \snippet doc/src/snippets/code/doc_src_porting-qsa.js 1 An equivalent construction that illustrates that the function is a property of the global object is the following assignment: - \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 2 + \snippet doc/src/snippets/code/doc_src_porting-qsa.js 2 Since functions are objects, they can be assigned to objects as properties, becoming member functions: - \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 3 + \snippet doc/src/snippets/code/doc_src_porting-qsa.js 3 In the code above, we see the first subtle difference between QSA and Qt Script. In QSA one would write the point class like this: @@ -99,7 +99,7 @@ All the code above runs with QSA except the assignment of a function to \c{point.manhattanLength}, which we repeat here for clarity: - \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 5 + \snippet doc/src/snippets/code/doc_src_porting-qsa.js 5 This is because, in QSA, the value of \c this is decided based on the location of the declaration of the function it is used in. In the @@ -129,7 +129,7 @@ function with the newly created object as the \c this pointer. So, in a sense, it is equivalent to: - \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 8 + \snippet doc/src/snippets/code/doc_src_porting-qsa.js 8 This is similar to the manhattenLength() example above. Again, the main difference between QSA and Qt Script is that one has to @@ -149,7 +149,7 @@ one could write this in Qt Script as: - \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 10 + \snippet doc/src/snippets/code/doc_src_porting-qsa.js 10 In QSA, the member functions were part of the class declaration, and were therefore shared between all instances of a given class. @@ -173,7 +173,7 @@ To make the \c toString() function part of the prototype, we write code like this: - \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 11 + \snippet doc/src/snippets/code/doc_src_porting-qsa.js 11 Here, we made the \c toString() function part of the prototype so that, when we call \c{car.toString()} it will be resolved via the @@ -195,7 +195,7 @@ without any special members, but it is possible to replace this object with another prototype object. - \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 13 + \snippet doc/src/snippets/code/doc_src_porting-qsa.js 13 In the code above, we have a constructor, \c{GasolineCar}, which calls the "base class" implementation of the constructor to @@ -223,7 +223,7 @@ as static members as properties of the constructor function. For example: - \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 15 + \snippet doc/src/snippets/code/doc_src_porting-qsa.js 15 Note that in QSA, static member variables were also accessible in instances of the given class. In Qt Script, with the approach @@ -374,7 +374,7 @@ the interpreter using their object names as the names of the variables. - \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 16 + \snippet doc/src/snippets/code/doc_src_porting-qsa.cpp 16 The code above adds the button to the global namespace under the name "button". One obvious limitation here is that there is potential for @@ -382,7 +382,7 @@ provides a more flexible way of adding QObjects to the scripting environment. - \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 17 + \snippet doc/src/snippets/code/doc_src_porting-qsa.cpp 17 In the code above we create a QPushButton and wrap it in a script value using the function, QScriptEngine::newQObject(). This gives us @@ -404,14 +404,14 @@ Below is listed some code from the filter example in the QSA package. - \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 18 + \snippet doc/src/snippets/code/doc_src_porting-qsa.cpp 18 The equivalent in Qt Script is written in much the same way as constructors are written in scripts. We register a callback C++ function under the name "ImageSource" in the global namespace and return the QObject from this function: - \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 19 + \snippet doc/src/snippets/code/doc_src_porting-qsa.cpp 19 In the Qt Script case we use the same approach that we use to expose a QObject, namely via QScriptEngine::newQObject(). This function also diff --git a/doc/src/porting/porting4-canvas.qdoc b/doc/src/porting/porting4-canvas.qdoc index 445f66d..1e20384 100644 --- a/doc/src/porting/porting4-canvas.qdoc +++ b/doc/src/porting/porting4-canvas.qdoc @@ -152,7 +152,7 @@ \row \o Q3Canvas::onCanvas() \o The is no equivalent to this function in Graphics View. However, you can combine QGraphicsScene::sceneRect() and QRectF::intersects(): - \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 0 + \snippet doc/src/snippets/code/doc_src_porting4-canvas.cpp 0 \row \o Q3Canvas::rect() \o The equivalent, QGraphicsScene::sceneRect(), returns a QRectF (double @@ -251,7 +251,7 @@ out the public tile API can then be declared as new members of this class. Here is one example of how to implement tile support: - \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 1 + \snippet doc/src/snippets/code/doc_src_porting4-canvas.cpp 1 Depending on how your scene uses tiles, you may be able to simplify this approach. In this example, we will try to mimic the behavior @@ -264,30 +264,30 @@ two-dimensional vector of ints to keep track of what tiles should be used at what parts of the scene. - \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 2 + \snippet doc/src/snippets/code/doc_src_porting4-canvas.cpp 2 In setTiles(), we store the pixmap and tile properties as members of the class. Then we resize the tiles vector to match the width and height of our tile grid. - \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 3 + \snippet doc/src/snippets/code/doc_src_porting4-canvas.cpp 3 The setTile() function updates the tiles index, and then updates the corresponding rect in the scene by calling tileRect(). - \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 4 + \snippet doc/src/snippets/code/doc_src_porting4-canvas.cpp 4 The first tileRect() function returns a QRect for the tile at position (x, y). - \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 5 + \snippet doc/src/snippets/code/doc_src_porting4-canvas.cpp 5 The second tileRect() function returns a QRect for a tile number. With these functions in place, we can implement the drawBackground() function. - \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 6 + \snippet doc/src/snippets/code/doc_src_porting4-canvas.cpp 6 In drawBackground(), we redraw all tiles that have been exposed by intersecting each tile rect with the exposed background @@ -522,7 +522,7 @@ For compatibility, you may want to shift the ellipse up and to the left to keep the ellipse centered. Example: - \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 7 + \snippet doc/src/snippets/code/doc_src_porting4-canvas.cpp 7 Note: QGraphicsEllipseItem uses QAbstractGraphicsShapeItem::pen() for outlines, whereas Q3CanvasEllipse did not use @@ -588,7 +588,7 @@ QPainterPath::moveTo() and QPainterPath::cubicTo(). Here is how you can convert a bezier curve Q3PointArray to a QPainterPath: - \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 8 + \snippet doc/src/snippets/code/doc_src_porting4-canvas.cpp 8 Note: QGraphicsPathItem uses QAbstractGraphicsShapeItem::pen() for outlines, whereas Q3CanvasSpline did not use @@ -653,7 +653,7 @@ functionality using Graphics View, you can load the images by using QDir: - \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 9 + \snippet doc/src/snippets/code/doc_src_porting4-canvas.cpp 9 \section2 Q3CanvasText diff --git a/doc/src/porting/porting4-designer.qdoc b/doc/src/porting/porting4-designer.qdoc index d84af3f..ef3e746 100644 --- a/doc/src/porting/porting4-designer.qdoc +++ b/doc/src/porting/porting4-designer.qdoc @@ -104,7 +104,7 @@ For example, here's the \c uic output for a simple \c helloworld.ui form (some details were removed for simplicity): - \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 0 + \snippet doc/src/snippets/code/doc_src_porting4-designer.cpp 0 In this case, the main container was specified to be a QWidget (or any subclass of QWidget). Had we started with a QMainWindow @@ -116,7 +116,7 @@ an instance of the main container (a plain QWidget), and call \c setupUi(): - \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 1 + \snippet doc/src/snippets/code/doc_src_porting4-designer.cpp 1 The second approach is to inherit from both the \c Ui::HelloWorld class and the main container, and to call \c setupUi() in the @@ -124,7 +124,7 @@ its subclasses, e.g. QDialog) must appear first in the base class list so that \l{moc} picks it up correctly. For example: - \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 2 + \snippet doc/src/snippets/code/doc_src_porting4-designer.cpp 2 This second method is useful when porting Qt 3 forms to Qt 4. \c HelloWorldWidget is a class whose instance is the actual form @@ -212,7 +212,7 @@ them to the widgets in the form after calling \c setupUi(). For example: - \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 5 + \snippet doc/src/snippets/code/doc_src_porting4-designer.cpp 5 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 @@ -233,7 +233,7 @@ \tt{\e{signalName}}, then this signal will be connected to the main container's slot. For example: - \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 6 + \snippet doc/src/snippets/code/doc_src_porting4-designer.cpp 6 Because of the naming convention, \c setupUi() automatically connects \c pushButton's \c clicked() signal to \c @@ -257,14 +257,14 @@ Next, we add the resource file to our \c .pro file: - \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 8 + \snippet doc/src/snippets/code/doc_src_porting4-designer.pro 8 When \c qmake is run, it will create the appropriate Makefile rules to call \c rcc on the resource file, and compile and link the result into the application. The icons may be accessed as follows: - \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 9 + \snippet doc/src/snippets/code/doc_src_porting4-designer.cpp 9 In each case, the leading colon tells Qt to look for the file in the virtual file tree defined by the set of resource files diff --git a/doc/src/porting/porting4-dnd.qdoc b/doc/src/porting/porting4-dnd.qdoc index 92b9fc1..993b8d2 100644 --- a/doc/src/porting/porting4-dnd.qdoc +++ b/doc/src/porting/porting4-dnd.qdoc @@ -54,7 +54,7 @@ \l{Q3DragObject::}{drag()} function is called, and it receives no information about how the operation ended. - \snippet doc/src/snippets/code/doc_src_dnd.qdoc 0 + \snippet doc/src/snippets/code/doc_src_dnd.cpp 0 Similarly, in Qt 4, drag operations are also initiated when a QDrag object is constructed and its \l{QDrag::}{exec()} function is called. In contrast, @@ -94,7 +94,7 @@ indicating success or failure of these checks via the event's \l{QDragEnterEvent::}{accept()} function, as shown in this simple example: - \snippet doc/src/snippets/code/doc_src_dnd.qdoc 1 + \snippet doc/src/snippets/code/doc_src_dnd.cpp 1 In Qt 4, you can examine the MIME type describing the data to determine whether the widget should accept the event or, for common data types, you @@ -113,7 +113,7 @@ accept dropped data in the form of text or images might provide an implementation of \l{QWidget::}{dropEvent()} that looks like the following: - \snippet doc/src/snippets/code/doc_src_dnd.qdoc 2 + \snippet doc/src/snippets/code/doc_src_dnd.cpp 2 In Qt 4, the event is handled in a similar way: diff --git a/doc/src/porting/porting4.qdoc b/doc/src/porting/porting4.qdoc index a3960c3..1c11a02 100644 --- a/doc/src/porting/porting4.qdoc +++ b/doc/src/porting/porting4.qdoc @@ -760,7 +760,7 @@ function. The solution is to reimplement QWidget::paintEvent() in your QAbstractButton subclass as follows: - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 0 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 0 \table \header \o Q3Button function \o QAbstractButton equivalent @@ -860,11 +860,11 @@ \o QMemArray::at() returned a non-const reference, whereas the new QByteArray::at() returns a const value. Code like - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 1 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 1 will no longer compile. Instead, use QByteArray::operator[]: - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 2 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 2 \o The QMemArray::contains(char) function has been renamed QByteArray::count(char). In addition, there now exists a @@ -935,11 +935,11 @@ function returns \c void and either adds it to the cache or deletes it right away. Old code like - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 3 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 3 becomes - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 4 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 4 \o The new QCache class \e always takes ownership of the items it stores (i.e. auto-delete is always on). If you use Q3Cache @@ -950,11 +950,11 @@ pointers, not the objects that the pointers refer to. For example, - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 5 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 5 becomes - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 6 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 6 An alternative is to stick to using Q3Cache. \endlist @@ -1051,7 +1051,7 @@ you can simply replace colorGroup() with palette(): - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 7 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 7 \section1 QColorDrag @@ -1089,7 +1089,7 @@ '\\0' issue is handled by having QByteArray allocate one extra byte that it always sets to '\\0'. For example: - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 8 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 8 The Qt3Support library contains a class called Q3CString that inherits from the new QByteArray class and that @@ -1416,26 +1416,26 @@ \header \o Q3Dict idiom \o QMultiHash idiom \row \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 9 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 9 \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 10 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 10 \row \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 11 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 11 \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 12 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 12 \row \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 13 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 13 (also called from Q3Dict's destructor) \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 14 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 14 In 99% of cases, the following idiom also works: - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 15 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 15 However, it may lead to crashes if \c hash is referenced from the value type's destructor, because \c hash contains @@ -1471,11 +1471,11 @@ Be aware that QHashIterator has a different way of iterating than Q3DictIterator. A typical loop with Q3DictIterator looks like this: - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 16 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 16 Here's the equivalent QHashIterator loop: - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 17 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 17 See \l{Java-style iterators} for details. @@ -2377,7 +2377,7 @@ Use QObject::findChildren() instead of QObject::queryList(). For example: - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 18 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 18 QObject::killTimers() has been removed because it was unsafe to use in subclass. (A subclass normally doesn't know whether the @@ -2712,48 +2712,48 @@ \header \o QPtrList idiom \o QList idiom \row \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 19 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 19 \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 20 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 20 \row \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 21 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 21 \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 22 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 22 \row \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 23 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 23 \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 24 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 24 \row \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 25 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 25 \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 26 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 26 \row \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 27 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 27 \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 28 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 28 \row \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 29 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 29 (removes the current item) \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 30 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 30 \row \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 31 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 31 (also called from QPtrList's destructor) \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 32 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 32 In 99% of cases, the following idiom also works: - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 33 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 33 However, it may lead to crashes if \c list is referenced from the value type's destructor, because \c list contains @@ -2790,11 +2790,11 @@ Be aware that QListIterator has a different way of iterating than QPtrList. A typical loop with QPtrList looks like this: - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 34 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 34 Here's the equivalent QListIterator loop: - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 35 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 35 Finally, QPtrListIterator<T> must also be ported. There are no fewer than four iterator classes that can be used as a @@ -2821,11 +2821,11 @@ iterating than QPtrList. A typical loop with QPtrList looks like this: - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 36 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 36 Here's the equivalent QListIterator loop: - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 37 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 37 Finally, QPtrListStdIterator<T> must also be ported. This is easy, because QList also provides STL-style iterators @@ -2864,26 +2864,26 @@ \header \o QPtrQueue idiom \o QQueue idiom \row \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 38 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 38 \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 39 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 39 \row \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 40 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 40 \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 41 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 41 \row \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 42 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 42 (also called from QPtrQueue's destructor) \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 43 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 43 In 99% of cases, the following idiom also works: - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 44 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 44 However, it may lead to crashes if \c queue is referenced from the value type's destructor, because \c queue contains @@ -2923,26 +2923,26 @@ \header \o QPtrStack idiom \o QStack idiom \row \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 45 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 45 \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 46 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 46 \row \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 47 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 47 \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 48 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 48 \row \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 49 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 49 (also called from QPtrStack's destructor) \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 50 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 50 In 99% of cases, the following idiom also works: - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 51 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 51 However, it may lead to crashes if \c stack is referenced from the value type's destructor, because \c stack contains @@ -3024,36 +3024,36 @@ \header \o QPtrVector idiom \o QVector idiom \row \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 52 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 52 \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 53 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 53 \row \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 54 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 54 \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 55 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 55 \row \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 56 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 56 \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 57 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 57 \row \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 58 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 58 \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 59 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 59 \row \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 60 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 60 (also called from QPtrVector's destructor) \o - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 61 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 61 In 99% of cases, the following idiom also works: - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 62 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 62 However, it may lead to crashes if \c vect is referenced from the value type's destructor, because \c vect contains @@ -3193,7 +3193,7 @@ An easy way of porting to Qt 4 is to include this class into your project and to use it instead of \c QShared: - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 63 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 63 If possible, we recommend that you use QSharedData and QSharedDataPointer instead. They provide thread-safe reference @@ -3217,11 +3217,11 @@ Previously, you would do the following with Q3SimpleRichText: - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 63a + \snippet doc/src/snippets/code/doc_src_porting4.cpp 63a However, with QTextDocument, you use the following code instead: - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 63b + \snippet doc/src/snippets/code/doc_src_porting4.cpp 63b See \l{Rich Text Processing} for an overview of the Qt 4 rich text classes. @@ -3233,7 +3233,7 @@ The slider's rect can now be retrieved using the code snippet below: - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 63c + \snippet doc/src/snippets/code/doc_src_porting4.cpp 63c In addition, the direction of a vertical QSlider has changed, i.e. the bottom is now the minimum, and the top the maximum. You @@ -3454,7 +3454,7 @@ byte array; you should avoid taking a pointer to the data contained in temporary objects. - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 64 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 64 In the above example, the \c goodData pointer is valid for the lifetime of the \c asciiData byte array. If you need to keep a copy of the data @@ -3464,11 +3464,11 @@ \o QString::at() returned a non-const reference, whereas the new QString::at() returns a const value. Code like - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 65 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 65 will no longer compile. Instead, use QString::operator[]: - \snippet doc/src/snippets/code/doc_src_porting4.qdoc 66 + \snippet doc/src/snippets/code/doc_src_porting4.cpp 66 \o The QString::contains(\e x) function (where \e x is a character or a string) has been renamed QString::count(\e x). diff --git a/doc/src/porting/qt3to4.qdoc b/doc/src/porting/qt3to4.qdoc index 336601f..3c95b4c 100644 --- a/doc/src/porting/qt3to4.qdoc +++ b/doc/src/porting/qt3to4.qdoc @@ -122,7 +122,7 @@ In some cases, you might get compiler errors because of identifiers in the global namespace (e.g., \c CTRL). Adding - \snippet doc/src/snippets/code/doc_src_qt3to4.qdoc 2 + \snippet doc/src/snippets/code/doc_src_qt3to4.cpp 2 at the beginning of the source file that contains the indentifier solves the problem. diff --git a/doc/src/porting/qt4-accessibility.qdoc b/doc/src/porting/qt4-accessibility.qdoc index 6e56942..2d9e8c3 100644 --- a/doc/src/porting/qt4-accessibility.qdoc +++ b/doc/src/porting/qt4-accessibility.qdoc @@ -68,7 +68,7 @@ variable set to 1. For example, this is set in the following way with the bash shell: - \snippet doc/src/snippets/code/doc_src_qt4-accessibility.qdoc environment + \snippet doc/src/snippets/code/doc_src_qt4-accessibility.cpp environment Accessibility features are built into Qt by default when the libraries are configured and built. @@ -132,17 +132,17 @@ information for a custom widget. We can use QAccessibleWidget as a base class and reimplement various functions: - \snippet doc/src/snippets/code/doc_src_qt4-accessibility.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qt4-accessibility.cpp 0 Here's how we would implement the \l{QAccessibleInterface::doAction()}{doAction()} function to call a function named click() on the wrapped MyWidget object when the user invokes the object's default action or "presses" it. - \snippet doc/src/snippets/code/doc_src_qt4-accessibility.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qt4-accessibility.cpp 1 To export the widget interface as a plugin, we must subclass QAccessibleFactory: - \snippet doc/src/snippets/code/doc_src_qt4-accessibility.qdoc 2 + \snippet doc/src/snippets/code/doc_src_qt4-accessibility.cpp 2 */ diff --git a/doc/src/porting/qt4-arthur.qdoc b/doc/src/porting/qt4-arthur.qdoc index 434aa29..460a048 100644 --- a/doc/src/porting/qt4-arthur.qdoc +++ b/doc/src/porting/qt4-arthur.qdoc @@ -119,7 +119,7 @@ Setting a linear gradient brush is done by creating a QLinearGradient object and setting it as a brush. - \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qt4-arthur.cpp 0 The code shown above produces a pattern as show in the following pixmap: @@ -130,7 +130,7 @@ focal point. Setting a radial brush is done by creating a QRadialGradient object and setting it as a brush. - \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qt4-arthur.cpp 1 The code shown above produces a pattern as shown in the following pixmap: @@ -141,7 +141,7 @@ angle. Setting a conical brush is done by creating a QConicalGradient object and setting it as a brush. - \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 2 + \snippet doc/src/snippets/code/doc_src_qt4-arthur.cpp 2 The code shown above produces a pattern as shown in the following pixmap: @@ -156,7 +156,7 @@ transparent color, while 255 represents a fully opaque color. For example: - \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 3 + \snippet doc/src/snippets/code/doc_src_qt4-arthur.cpp 3 The code shown above produces the following output: @@ -180,7 +180,7 @@ provide the option of turning on anti-aliased edges when drawing graphics primitives. - \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 4 + \snippet doc/src/snippets/code/doc_src_qt4-arthur.cpp 4 This produces the following output: @@ -221,7 +221,7 @@ first add a rectangle, which becomes a closed subpath. We then add two bezier curves, and finally draw the entire path. - \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 5 + \snippet doc/src/snippets/code/doc_src_qt4-arthur.cpp 5 The code above produces the following output: @@ -236,18 +236,18 @@ painting to an off-screen pixmap then copying the pixmap to the screen. For example: - \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 6 + \snippet doc/src/snippets/code/doc_src_qt4-arthur.cpp 6 Since the double-buffering is handled by QWidget internally this now becomes: - \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 7 + \snippet doc/src/snippets/code/doc_src_qt4-arthur.cpp 7 Double-buffering is turned on by default, but can be turned off for individual widgets by setting the widget attribute Qt::WA_PaintOnScreen. - \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 8 + \snippet doc/src/snippets/code/doc_src_qt4-arthur.cpp 8 \section2 Pen and Brush Transformation @@ -270,7 +270,7 @@ possible to specify both texture and gradient fills for both text and outlines. - \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 9 + \snippet doc/src/snippets/code/doc_src_qt4-arthur.cpp 9 The code above produces the following output: @@ -290,7 +290,7 @@ Painting on an image is as simple as drawing on any other paint device. - \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 10 + \snippet doc/src/snippets/code/doc_src_qt4-arthur.cpp 10 \section2 SVG Rendering Support diff --git a/doc/src/porting/qt4-mainwindow.qdoc b/doc/src/porting/qt4-mainwindow.qdoc index 1eff2c2..ebfbc8d 100644 --- a/doc/src/porting/qt4-mainwindow.qdoc +++ b/doc/src/porting/qt4-mainwindow.qdoc @@ -86,7 +86,7 @@ the first time it is called. You can also call QMainWindow::setMenuBar() to use a custom menu bar in the main window. - \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 0 \dots \snippet examples/mainwindows/menus/mainwindow.cpp 5 \dots @@ -110,7 +110,7 @@ \snippet examples/mainwindows/sdi/mainwindow.cpp 0 \dots - \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 1 In this example, the toolbar is restricted to the top and bottom toolbar areas of the main window, and is initially placed in the @@ -132,7 +132,7 @@ required, the default can be changed with the QMainWindow::setCorner() function: - \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 2 + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 2 The following diagram shows the configuration produced by the above code. Note that the left and right dock widgets will occupy the top and bottom @@ -143,7 +143,7 @@ Once all of the main window components have been set up, the central widget is created and installed by using code similar to the following: - \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 3 + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 3 The central widget can be any subclass of QWidget. @@ -217,17 +217,17 @@ constructed using the general QMenu class. Qt 3: - \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 4 + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 4 Qt 4: - \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 5 + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 5 Toolbars follow the same pattern as menus, with the new, more consistent behavior: Qt 3: - \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 6 + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 6 Qt 4: - \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 7 + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 7 The behavior of dock widgets is now configured through the member functions of QDockWidget. For example, compare the old and new ways @@ -235,7 +235,7 @@ main window. In Qt 3: - \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 8 + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 8 In Qt 4: - \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 9 + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 9 */ diff --git a/doc/src/porting/qt4-sql.qdoc b/doc/src/porting/qt4-sql.qdoc index bafaacb..2a5a206 100644 --- a/doc/src/porting/qt4-sql.qdoc +++ b/doc/src/porting/qt4-sql.qdoc @@ -104,12 +104,12 @@ The simplest way to present data from a database is to simply combine a QSqlQueryModel with a QTableView: - \snippet doc/src/snippets/code/doc_src_qt4-sql.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qt4-sql.cpp 0 To present the contents of a single table, we can use QSqlTableModel instead: - \snippet doc/src/snippets/code/doc_src_qt4-sql.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qt4-sql.cpp 1 In practice, it's common that we need to customize the rendering of a field in the database. In that case, we can create our own diff --git a/doc/src/porting/qt4-styles.qdoc b/doc/src/porting/qt4-styles.qdoc index 76b0b1c..7422f06 100644 --- a/doc/src/porting/qt4-styles.qdoc +++ b/doc/src/porting/qt4-styles.qdoc @@ -90,7 +90,7 @@ pointer type is correct. If the object isn't of the right type, qstyleoption_cast() returns 0. For example: - \snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qt4-styles.cpp 0 For performance reasons, there are few member functions and the access to the variables is direct. This "low-level" feel makes @@ -108,7 +108,7 @@ The following code snippet illustrates how to use QStyle to draw the focus rectangle from a custom widget's paintEvent(): - \snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qt4-styles.cpp 1 The next example shows how to derive from an existing style to customize the look of a graphical element: @@ -130,11 +130,11 @@ For example, here's the signature of the QStyle::drawControl() function in Qt 3: - \snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 2 + \snippet doc/src/snippets/code/doc_src_qt4-styles.cpp 2 Here's the signature of the same function in Qt 4: - \snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 3 + \snippet doc/src/snippets/code/doc_src_qt4-styles.cpp 3 In Qt 3, some of the information required to draw a graphical element was stored in a QStyleOption parameter, while the rest diff --git a/doc/src/porting/qt4-tulip.qdoc b/doc/src/porting/qt4-tulip.qdoc index 161c373..c78ff96 100644 --- a/doc/src/porting/qt4-tulip.qdoc +++ b/doc/src/porting/qt4-tulip.qdoc @@ -80,16 +80,16 @@ addition to the C++ language that is implemented using the standard C++ preprocessor. The syntax is: - \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qt4-tulip.cpp 0 Example: - \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qt4-tulip.cpp 1 The iterator variable can also be defined outside the loop. For example: - \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 2 + \snippet doc/src/snippets/code/doc_src_qt4-tulip.cpp 2 Just like standard \c for loops, foreach supports braces, \c break, \c continue, and nested loops. Qt makes a copy of the @@ -124,25 +124,25 @@ Traversing a container using a Java-style iterator: - \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 3 + \snippet doc/src/snippets/code/doc_src_qt4-tulip.cpp 3 Modifying items using a Java-style iterator: - \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 4 + \snippet doc/src/snippets/code/doc_src_qt4-tulip.cpp 4 Removing items using a Java-style iterator: - \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 5 + \snippet doc/src/snippets/code/doc_src_qt4-tulip.cpp 5 Iterating over items with a particular value using STL-style vs. Java-style iterators: - \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 6 + \snippet doc/src/snippets/code/doc_src_qt4-tulip.cpp 6 Modifying and removing items using STL-style vs. Java-style iterators: - \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 7 + \snippet doc/src/snippets/code/doc_src_qt4-tulip.cpp 7 The next group of examples show the API of the container classes themselves. The API is similar to the QTL classes of Qt 3, but is nicer @@ -151,16 +151,16 @@ Iterating over a QList using an index (which is fast even for large lists, because QList is implemented as an array-list): - \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 8 + \snippet doc/src/snippets/code/doc_src_qt4-tulip.cpp 8 Retrieving a value from a map, using a default value if the key doesn't exist: - \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 9 + \snippet doc/src/snippets/code/doc_src_qt4-tulip.cpp 9 Getting all the values for a particular key in a QMultiMap or QMultiHash: - \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 10 + \snippet doc/src/snippets/code/doc_src_qt4-tulip.cpp 10 \section1 Comparison with Qt 3 diff --git a/doc/src/qt-webpages.qdoc b/doc/src/qt-webpages.qdoc index 5a3bfc9..e915267 100644 --- a/doc/src/qt-webpages.qdoc +++ b/doc/src/qt-webpages.qdoc @@ -246,6 +246,21 @@ */ /*! + \externalpage http://doc.qt.nokia.com/qtcreator-snapshot/index.html + \title Qt Creator Manual +*/ + +/*! + \externalpage http://doc.qt.nokia.com/qtcreator-snapshot/creator-qml-application.html + \title Developing Qt Quick Applications with Creator +*/ + +/*! \externalpage http://qt.gitorious.org/qt/pages/QtCodingStyle \title Qt Coding Style */ + +/*! + \externalpage http://qt.nokia.com/developer/learning/online/training/training-day-at-developer-days-2009/ + \title Training Day at Qt Developer Days 2009 +*/ diff --git a/doc/src/qt4-intro.qdoc b/doc/src/qt4-intro.qdoc index 3cabb1c..41848e9 100644 --- a/doc/src/qt4-intro.qdoc +++ b/doc/src/qt4-intro.qdoc @@ -241,7 +241,9 @@ \section1 Build System Unlike previous Qt releases, Qt 4 is a collection of smaller - libraries: + libraries. A complete list of libraries in the current release + of Qt can be found on the \l{All Modules} page. The following + table describes the initial set of libraries released with Qt 4. \table \header \o Library \o Description @@ -276,11 +278,11 @@ link your application against QtCore and QtGui. To remove the dependency upon QtGui, add the line - \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qt4-intro.pro 0 to your .pro file. To enable the other libraries, add the line - \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qt4-intro.pro 1 Another change to the build system is that moc now understands preprocessor directives. qmake automatically passes the defines set @@ -290,21 +292,21 @@ 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 + \snippet doc/src/snippets/code/doc_src_qt4-intro.pro 2 \section1 Include Syntax The syntax for including Qt class definitions has become - \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 3 + \snippet doc/src/snippets/code/doc_src_qt4-intro.cpp 3 For example: - \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 4 + \snippet doc/src/snippets/code/doc_src_qt4-intro.cpp 4 This is guaranteed to work for any public Qt class. The old syntax, - \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 5 + \snippet doc/src/snippets/code/doc_src_qt4-intro.cpp 5 still works, but we encourage you to switch to the new syntax. @@ -318,7 +320,7 @@ To include the definitions for all the classes in a library, simply specify the name of that library. For example: - \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 6 + \snippet doc/src/snippets/code/doc_src_qt4-intro.cpp 6 \section1 Namespaces @@ -330,7 +332,7 @@ to access a constant that is part of the Qt namespace, prefix it with \c{Qt::} (e.g., \c{Qt::yellow}), or add the directive - \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 7 + \snippet doc/src/snippets/code/doc_src_qt4-intro.cpp 7 at the top of your source files, after your \c #include directives. If you use the \c{using namespace} syntax you don't @@ -360,7 +362,7 @@ \list \o Code that used it looked confusing, for example: - \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 8 + \snippet doc/src/snippets/code/doc_src_qt4-intro.cpp 8 \c label1 is a QLabel that displays the text "Hello"; \c label2 is a QLabel with no text, with the object name @@ -370,7 +372,7 @@ they blindly followed Qt's convention and provided a "const char *name" in their subclasses's constructors. For example: - \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 9 + \snippet doc/src/snippets/code/doc_src_qt4-intro.cpp 9 \o The name parameter was in Qt since version 1, and it always was documented as: "It is not very useful in the current @@ -405,12 +407,12 @@ Here's the Qt 3 idiom to cast a type to a subtype: - \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 10 + \snippet doc/src/snippets/code/doc_src_qt4-intro.cpp 10 The Qt 4 idiom is both cleaner and safer, because typos will always result in compiler errors: - \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 11 + \snippet doc/src/snippets/code/doc_src_qt4-intro.cpp 11 \section1 QPointer<T> @@ -421,7 +423,7 @@ Example: - \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 12 + \snippet doc/src/snippets/code/doc_src_qt4-intro.cpp 12 QPointer<T> is more or less the same as the old QGuardedPtr<T> class, except that it is now implemented in a much more lightweight manner @@ -461,7 +463,7 @@ To enable the Qt 3 support classes and functions, add the line - \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 13 + \snippet doc/src/snippets/code/doc_src_qt4-intro.pro 13 to your \c .pro file. @@ -469,18 +471,18 @@ in a compiler warning (e.g., "'find' is deprecated"). If you want to turn off that warning, add the line - \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 14 + \snippet doc/src/snippets/code/doc_src_qt4-intro.pro 14 to your \c .pro file. If you want to use compatibility functions but don't want to link against the Qt3Support library, add the line - \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 15 + \snippet doc/src/snippets/code/doc_src_qt4-intro.pro 15 or - \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 16 + \snippet doc/src/snippets/code/doc_src_qt4-intro.pro 16 to your \c .pro file, depending on whether you want compatibility function calls to generate compiler warnings or not. diff --git a/doc/src/scripting/qtscriptextensions.qdoc b/doc/src/scripting/qtscriptextensions.qdoc index 888cf73..431adb0 100644 --- a/doc/src/scripting/qtscriptextensions.qdoc +++ b/doc/src/scripting/qtscriptextensions.qdoc @@ -68,7 +68,7 @@ An example of a simple \c{__init__.js}: - \snippet doc/src/snippets/code/doc_src_qtscriptextensions.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qtscriptextensions.js 0 QScriptEngine will look for a QScriptExtensionPlugin that provides the relevant extension by querying each plugin for its keys() diff --git a/doc/src/scripting/scripting.qdoc b/doc/src/scripting/scripting.qdoc index 79fed97..f882da0 100644 --- a/doc/src/scripting/scripting.qdoc +++ b/doc/src/scripting/scripting.qdoc @@ -144,7 +144,7 @@ script function. In the following example a script signal handler is defined that will handle the QLineEdit::textChanged() signal: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 47 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 47 The first two arguments to qScriptConnect() are the same as you would pass to QObject::connect() to establish a normal C++ @@ -155,7 +155,7 @@ ("slot") itself. The following example shows how the \c this argument can be put to use: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 48 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 48 We create two QLineEdit objects and define a single signal handler function. The connections use the same handler function, but the @@ -179,13 +179,13 @@ In this form of connection, the argument to \c{connect()} is the function to connect to the signal. - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 2 + \snippet doc/src/snippets/code/doc_src_qtscript.js 2 The argument can be a Qt Script function, as in the above example, or it can be a QObject slot, as in the following example: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 3 + \snippet doc/src/snippets/code/doc_src_qtscript.js 3 When the argument is a QObject slot, the argument types of the signal and slot do not necessarily have to be compatible; @@ -196,7 +196,7 @@ \c{disconnect()} function, passing the function to disconnect as argument: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 4 + \snippet doc/src/snippets/code/doc_src_qtscript.js 4 When a script function is invoked in response to a signal, the \c this object will be the Global Object. @@ -214,11 +214,11 @@ \c{clicked} signal; passing the form as the \c this object makes sense in such a case. - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 5 + \snippet doc/src/snippets/code/doc_src_qtscript.js 5 To disconnect from the signal, pass the same arguments to \c{disconnect()}: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 6 + \snippet doc/src/snippets/code/doc_src_qtscript.js 6 \section3 Signal to Named Member Function Connections @@ -234,11 +234,11 @@ Note that the function is resolved when the connection is made, not when the signal is emitted. - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 7 + \snippet doc/src/snippets/code/doc_src_qtscript.js 7 To disconnect from the signal, pass the same arguments to \c{disconnect()}: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 8 + \snippet doc/src/snippets/code/doc_src_qtscript.js 8 \section3 Error Handling @@ -247,14 +247,14 @@ You can obtain an error message from the resulting \c{Error} object. Example: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 9 + \snippet doc/src/snippets/code/doc_src_qtscript.js 9 \section3 Emitting Signals from Scripts To emit a signal from script code, you simply invoke the signal function, passing the relevant arguments: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 10 + \snippet doc/src/snippets/code/doc_src_qtscript.js 10 It is currently not possible to define a new signal in a script; i.e., all signals must be defined by C++ classes. @@ -267,13 +267,13 @@ \c{myOverloadedSlot(int)} and \c{myOverloadedSlot(QString)}, the following script code will behave reasonably: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 11 + \snippet doc/src/snippets/code/doc_src_qtscript.js 11 You can specify a particular overload by using array-style property access with the \l{QMetaObject::normalizedSignature()}{normalized signature} of the C++ function as the property name: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 12 + \snippet doc/src/snippets/code/doc_src_qtscript.js 12 If the overloads have different number of arguments, QtScript will pick the overload with the argument count that best matches the @@ -291,11 +291,11 @@ property will automatically be invoked. For example, if your C++ class has a property declared as follows: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 13 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 13 then script code can do things like the following: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 14 + \snippet doc/src/snippets/code/doc_src_qtscript.js 14 \section2 Accessing Child QObjects @@ -306,12 +306,12 @@ \c{"okButton"}, you can access this object in script code through the expression - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 15 + \snippet doc/src/snippets/code/doc_src_qtscript.js 15 Since \c{objectName} is itself a Q_PROPERTY, you can manipulate the name in script code to, for example, rename an object: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 16 + \snippet doc/src/snippets/code/doc_src_qtscript.js 16 You can also use the functions \c{findChild()} and \c{findChildren()} to find children. These two functions behave identically to @@ -320,7 +320,7 @@ For example, we can use these functions to find objects using strings and regular expressions: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 17 + \snippet doc/src/snippets/code/doc_src_qtscript.js 17 You typically want to use \c{findChild()} when manipulating a form that uses nested layouts; that way the script is isolated from the @@ -367,7 +367,7 @@ For example, a constructor function that constructs QObjects only to be used in the script environment is a good candidate: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 18 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 18 \section3 Auto-Ownership @@ -638,7 +638,7 @@ For example, the following class definition enables scripting only for certain functions: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 19 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 19 In the example above, aNonScriptableFunction() is not declared as a slot, so it will not be available in QtScript. The other three @@ -649,7 +649,7 @@ It is possible to make any function script-invokable by specifying the \c{Q_INVOKABLE} modifier when declaring the function: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 20 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 20 Once declared with \c{Q_INVOKABLE}, the method can be invoked from QtScript code just as if it were a slot. Although such a method is @@ -657,19 +657,25 @@ call to \c{connect()} in script code; \c{connect()} accepts both native and non-native functions as targets. + As discussed in \l{Default Conversion from Qt Script to C++}, Qt + Script handles conversion for many C++ types. If your function takes + arguments for which Qt Script does not handle conversion, you need + to supply conversion functions. This is done using the + qScriptRegisterMetaType() function. + \section2 Making C++ Class Properties Available in QtScript In the previous example, if we wanted to get or set a property using QtScript we would have to write code like the following: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 21 + \snippet doc/src/snippets/code/doc_src_qtscript.js 21 Scripting languages often provide a property syntax to modify and retrieve properties (in our case the enabled state) of an object. Many script programmers would want to write the above code like this: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 22 + \snippet doc/src/snippets/code/doc_src_qtscript.js 22 To make this possible, you must define properties in the C++ QObject subclass. For example, the following \c MyObject class declaration @@ -677,7 +683,7 @@ \c{setEnabled(bool)} as its setter function and \c{isEnabled()} as its getter function: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 23 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 23 The only difference from the original code is the use of the macro \c{Q_PROPERTY}, which takes the type and name of the property, and @@ -688,7 +694,7 @@ declaring the property; by default, the \c{SCRIPTABLE} attribute is \c true. For example: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 24 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 24 \section2 Reacting to C++ Objects Signals in Scripts @@ -703,14 +709,14 @@ regardless of whether the signal will be connected to a slot in C++ or in QtScript. - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 25 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 25 The only change we have made to the code in the previous section is to declare a signals section with the relevant signal. Now, the script writer can define a function and connect to the object like this: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 26 + \snippet doc/src/snippets/code/doc_src_qtscript.js 26 \section2 Design of Application Objects @@ -752,7 +758,7 @@ still allowing pointers to your custom objects to flow seamlessly between C++ and scripts. Example: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 43 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 43 \section1 Function Objects and Native Functions @@ -778,23 +784,23 @@ result. The following script defines a Qt Script object that has a toKelvin() function: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 90 + \snippet doc/src/snippets/code/doc_src_qtscript.js 90 The toKelvin() function takes a temperature in Kelvin as argument, and returns the temperature converted to Celsius. The following snippet shows how the toKelvin() function might be obtained and called from C++: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 91 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 91 If a script defines a global function, you can access the function as a property of QScriptEngine::globalObject(). For example, the following script defines a global function add(): - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 56 + \snippet doc/src/snippets/code/doc_src_qtscript.js 56 C++ code might call the add() function as follows: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 92 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 92 As already mentioned, functions are just values in Qt Script; a function by itself is not "tied to" a particular object. This is why you have to specify @@ -816,7 +822,7 @@ is invoked determines the \c this object when the function body is executed, as the following script example illustrates: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 49 + \snippet doc/src/snippets/code/doc_src_qtscript.js 49 An important thing to note is that in Qt Script, unlike C++ and Java, the \c this object is not part of the execution scope. This means that @@ -824,14 +830,14 @@ use the \c this keyword to access the object's properties. For example, the following script probably doesn't do what you want: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 50 + \snippet doc/src/snippets/code/doc_src_qtscript.js 50 You will get a reference error saying that 'a is not defined' or, worse, two totally unrelated global variables \c a and \c b will be used to perform the computation, if they exist. Instead, the script should look like this: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 51 + \snippet doc/src/snippets/code/doc_src_qtscript.js 51 Accidentally omitting the \c this keyword is a typical source of error for programmers who are used to the scoping rules of C++ and Java. @@ -844,7 +850,7 @@ your function as if it were a "normal" script function. Here is how the previous \c{getProperty()} function can be written in C++: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 52 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 52 Call QScriptEngine::newFunction() to wrap the function. This will produce a special type of function object that carries a pointer to @@ -905,7 +911,7 @@ script would normally define an \c{add()} function that takes two arguments, adds them together and returns the result: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 56 + \snippet doc/src/snippets/code/doc_src_qtscript.js 56 When a script function is defined with formal parameters, their names can be viewed as mere aliases of properties of the \c @@ -914,12 +920,12 @@ variable. This means that the \c{add()} function can equivalently be written like this: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 57 + \snippet doc/src/snippets/code/doc_src_qtscript.js 57 This latter form closely matches what a native implementation typically looks like: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 58 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 58 \section3 Checking the Number of Arguments @@ -930,13 +936,13 @@ really needs two arguments in order to do something useful. This can be expressed by the script definition as follows: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 59 + \snippet doc/src/snippets/code/doc_src_qtscript.js 59 This would result in an error being thrown if a script invokes \c{add()} with anything other than two arguments. The native function can be modified to perform the same check: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 62 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 62 \section3 Checking the Types of Arguments @@ -954,7 +960,7 @@ stricter semantics (namely, that it should only add numeric operands), the argument types can be tested: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 60 + \snippet doc/src/snippets/code/doc_src_qtscript.js 60 Then an invocation like \c{add("foo", new Array())} will cause an error to be thrown. @@ -962,12 +968,12 @@ The C++ version can call QScriptValue::isNumber() to perform similar tests: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 63 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 63 A less strict script implementation might settle for performing an explicit to-number conversion before applying the \c{+} operator: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 61 + \snippet doc/src/snippets/code/doc_src_qtscript.js 61 In a native implementation, this is equivalent to calling QScriptValue::toNumber() without performing any type test first, @@ -1000,21 +1006,21 @@ \c{concat("Qt", " ", "Script ", 101)} would return "Qt Script 101". A script definition of \c{concat()} might look like this: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 64 + \snippet doc/src/snippets/code/doc_src_qtscript.js 64 Here is an equivalent native implementation: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 65 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 65 A second use case for a variable number of arguments is to implement optional arguments. Here's how a script definition typically does it: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 66 + \snippet doc/src/snippets/code/doc_src_qtscript.js 66 And here's the native equivalent: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 67 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 67 A third use case for a variable number of arguments is to simulate C++ overloads. This involves checking the number of arguments and/or @@ -1043,7 +1049,7 @@ call to another function. In script code, this is what it typically looks like: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 68 + \snippet doc/src/snippets/code/doc_src_qtscript.js 68 For example, \c{foo(10, 20, 30)} would result in the \c{foo()} function executing the equivalent of \c{bar(10, 20, 30)}. This is useful if @@ -1054,7 +1060,7 @@ function that has the exact same "signature". In C++, the forwarding function might look like this: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 69 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 69 \o The arguments object can serve as input to a QScriptValueIterator, providing a generic way to iterate over the arguments. A debugger @@ -1072,7 +1078,7 @@ Some script functions are constructors; they are expected to initialize new objects. The following snippet is a small example: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 75 + \snippet doc/src/snippets/code/doc_src_qtscript.js 75 There is nothing special about constructor functions. In fact, any script function can act as a constructor function (i.e., any function @@ -1118,7 +1124,7 @@ The following example implements a constructor function that always creates and initializes a new object: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 76 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 76 Given this constructor, scripts would be able to use either the expression \c{new Person("Bob")} or \c{Person("Bob")} to create a @@ -1154,7 +1160,7 @@ returns the function object being invoked. The following example shows how this might be used: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 55 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 55 \section2 Native Functions as Arguments to Functions @@ -1163,13 +1169,13 @@ naturally. As an example, here's a native comparison function that compares its two arguments numerically: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 53 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 53 The above function can be passed as argument to the standard \c{Array.prototype.sort} function to sort an array numerically, as the following C++ code illustrates: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 54 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 54 Note that, in this case, we are truly treating the native function object as a value \mdash i.e., we don't store it as a property of the @@ -1204,7 +1210,7 @@ itself. This technique is typically used in conjunction with QScriptEngine::pushContext(), as in the following example: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 77 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 77 We create a temporary execution context, create a local variable for it, evaluate the script, and finally restore the old context. @@ -1227,7 +1233,7 @@ define a native combined getter/setter that transforms the value slightly: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 78 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 78 The example uses the internal data of the object to store and retrieve the transformed value. Alternatively, the property @@ -1240,12 +1246,12 @@ The following C++ code shows how an object property can be defined in terms of the native getter/setter: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 79 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 79 When the property is accessed, like in the following script, the getter/setter does its job behind the scenes: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 80 + \snippet doc/src/snippets/code/doc_src_qtscript.js 80 \note It is important that the setter function, not just the getter, returns the value of the property; i.e., the setter should \e{not} @@ -1266,7 +1272,7 @@ Property getters and setters can be defined and installed by script code as well, as in the following example: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 81 + \snippet doc/src/snippets/code/doc_src_qtscript.js 81 Getters and setters can only be used to implement "a priori properties"; i.e., the technique can't be used to react to an access @@ -1342,7 +1348,7 @@ including the \c{hasOwnProperty()} function and \c{toString()} function: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 27 + \snippet doc/src/snippets/code/doc_src_qtscript.js 27 The \c{toString()} function itself is not defined in \c{o} (since we did not assign anything to \c{o.toString}), so instead the @@ -1382,7 +1388,7 @@ The following code defines a simple constructor function for a class called \c{Person}: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 28 + \snippet doc/src/snippets/code/doc_src_qtscript.js 28 Next, you want to set up \c{Person.prototype} as your prototype object; i.e., define the interface that should be common to all @@ -1397,19 +1403,19 @@ \c{Object.prototype}, to give your \c{Person} objects a more appropriate string representation: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 29 + \snippet doc/src/snippets/code/doc_src_qtscript.js 29 This resembles the process of reimplementing a virtual function in C++. Henceforth, when the property named \c{toString} is looked up in a \c{Person} object, it will be resolved in \c{Person.prototype}, not in \c{Object.prototype} as before: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 30 + \snippet doc/src/snippets/code/doc_src_qtscript.js 30 There are also some other interesting things we can learn about a \c{Person} object: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 31 + \snippet doc/src/snippets/code/doc_src_qtscript.js 31 The \c{hasOwnProperty()} function is not inherited from \c{Person.prototype}, but rather from \c{Object.prototype}, which is @@ -1426,13 +1432,13 @@ following example shows how one can create a subclass of \c{Person} called \c{Employee}: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 32 + \snippet doc/src/snippets/code/doc_src_qtscript.js 32 Again, you can use the \c{instanceof} to verify that the class relationship between \c{Employee} and \c{Person} has been correctly established: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 33 + \snippet doc/src/snippets/code/doc_src_qtscript.js 33 This shows that the prototype chain of \c{Employee} objects is the same as that of \c{Person} objects, but with \c{Employee.prototype} @@ -1477,25 +1483,25 @@ preceding section can be implemented in terms of the Qt Script API. We begin with the native constructor function: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 34 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 34 Here's the native equivalent of the \c{Person.prototype.toString} function we saw before: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 35 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 35 The \c{Person} class can then be initialized as follows: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 36 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 36 The implementation of the \c{Employee} subclass is similar. We use QScriptValue::call() to call the super-class (Person) constructor: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 37 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 37 The \c{Employee} class can then be initialized as follows: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 38 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 38 When implementing the prototype object of a class, you may want to use the QScriptable class, as it enables you to define the API of your @@ -1521,7 +1527,7 @@ modify the underlying C++ value, lets you modify the actual value contained in the script value (and not a copy of it). - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 39 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 39 \section2 Implementing Constructors for Value-based Types @@ -1529,7 +1535,7 @@ by wrapping a native factory function. For example, the following function implements a simple constructor for QPoint: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 44 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 44 In the above code we simplified things a bit, e.g. we didn't check the argument count to decide which QPoint C++ constructor to use. @@ -1564,16 +1570,16 @@ The following snippet shows a constructor function that constructs QXmlStreamReader objects that are stored using QSharedPointer: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 93 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 93 Prototype functions can use qscriptvalue_cast() to cast the \c this object to the proper type: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 94 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 94 The prototype and constructor objects are set up in the usual way: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 95 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 95 Scripts can now construct QXmlStreamReader objects by calling the \c XmlStreamReader constructor, and when the Qt Script object is @@ -1643,12 +1649,12 @@ somewhere else. The following code shows a custom print() that adds text to a QPlainTextEdit. - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 45 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 45 The following code shows how the custom print() function may be initialized and used. - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 46 + \snippet doc/src/snippets/code/doc_src_qtscript.cpp 46 A pointer to the QPlainTextEdit is stored as an internal property of the script function itself, so that it can be retrieved when @@ -1680,7 +1686,7 @@ function. Essentially all that is necessary to achieve this is to use the qsTr() script function. Example: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 82 + \snippet doc/src/snippets/code/doc_src_qtscript.js 82 This accounts for 99% of the user-visible strings you're likely to write. @@ -1689,7 +1695,7 @@ unique in your project, you should use the qsTranslate() function and pass a suitable context as the first argument. Example: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 83 + \snippet doc/src/snippets/code/doc_src_qtscript.js 83 If you need to have translatable text completely outside a function, there are two functions to help: QT_TR_NOOP() and QT_TRANSLATE_NOOP(). They merely @@ -1698,18 +1704,18 @@ Example of QT_TR_NOOP(): - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 84 + \snippet doc/src/snippets/code/doc_src_qtscript.js 84 Example of QT_TRANSLATE_NOOP(): - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 85 + \snippet doc/src/snippets/code/doc_src_qtscript.js 85 \section2 Use String.prototype.arg() for Dynamic Text The String.prototype.arg() function (which is modeled after QString::arg()) offers a simple means for substituting arguments: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 86 + \snippet doc/src/snippets/code/doc_src_qtscript.js 86 \section2 Produce Translations @@ -1804,7 +1810,7 @@ This property has the QScriptValue::Undeletable flag set. For example: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 40 + \snippet doc/src/snippets/code/doc_src_qtscript.js 40 \i \c{Object.prototype.__defineGetter__} \br This function installs a @@ -1814,7 +1820,7 @@ \c this object will be the object whose property is accessed. For example: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 41 + \snippet doc/src/snippets/code/doc_src_qtscript.js 41 \i \c{Object.prototype.__defineSetter__} \br This function installs a @@ -1824,7 +1830,7 @@ \c this object will be the object whose property is accessed. For example: - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 42 + \snippet doc/src/snippets/code/doc_src_qtscript.js 42 \i \c{Function.prototype.connect} \br This function connects diff --git a/doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc b/doc/src/snippets/code/doc_src_activeqt-dumpcpp.cpp index 0c29b1c..0c29b1c 100644 --- a/doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc +++ b/doc/src/snippets/code/doc_src_activeqt-dumpcpp.cpp diff --git a/doc/src/snippets/code/doc_src_appicon.pro b/doc/src/snippets/code/doc_src_appicon.pro new file mode 100644 index 0000000..176b458 --- /dev/null +++ b/doc/src/snippets/code/doc_src_appicon.pro @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [1] +RC_FILE = myapp.rc +#! [1] + + +#! [2] +ICON = myapp.icns +#! [2] + + +#! [5] +ICON = myapp.svg +#! [5] diff --git a/doc/src/snippets/code/doc_src_appicon.qdoc b/doc/src/snippets/code/doc_src_appicon.qdoc index 06bf861..8dd30a4 100644 --- a/doc/src/snippets/code/doc_src_appicon.qdoc +++ b/doc/src/snippets/code/doc_src_appicon.qdoc @@ -43,16 +43,6 @@ IDI_ICON1 ICON DISCARDABLE "myappico.ico" //! [0] -//! [1] -RC_FILE = myapp.rc -//! [1] - - -//! [2] -ICON = myapp.icns -//! [2] - - //! [3] kde-config --path icon //! [3] @@ -61,7 +51,3 @@ kde-config --path icon //! [4] gnome-config --datadir //! [4] - -//! [5] -ICON = myapp.svg -//! [5] diff --git a/doc/src/snippets/code/doc_src_containers.qdoc b/doc/src/snippets/code/doc_src_containers.cpp index fa300f9..fa300f9 100644 --- a/doc/src/snippets/code/doc_src_containers.qdoc +++ b/doc/src/snippets/code/doc_src_containers.cpp diff --git a/doc/src/snippets/code/doc_src_coordsys.qdoc b/doc/src/snippets/code/doc_src_coordsys.cpp index 1ebb215..1ebb215 100644 --- a/doc/src/snippets/code/doc_src_coordsys.qdoc +++ b/doc/src/snippets/code/doc_src_coordsys.cpp diff --git a/doc/src/snippets/code/doc_src_debug.qdoc b/doc/src/snippets/code/doc_src_debug.cpp index 40a5ac2..40a5ac2 100644 --- a/doc/src/snippets/code/doc_src_debug.qdoc +++ b/doc/src/snippets/code/doc_src_debug.cpp diff --git a/doc/src/snippets/code/doc_src_deployment.cpp b/doc/src/snippets/code/doc_src_deployment.cpp new file mode 100644 index 0000000..e7f7511 --- /dev/null +++ b/doc/src/snippets/code/doc_src_deployment.cpp @@ -0,0 +1,56 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [9] +qApp->addLibraryPath("/some/other/path"); +//! [9] + + +//! [19] +qApp->addLibraryPath("C:\some\other\path"); +//! [19] + + +//! [49] +QDir dir(QApplication::applicationDirPath()); +dir.cdUp(); +dir.cd("plugins"); +QApplication::setLibraryPaths(QStringList(dir.absolutePath())); +//! [49] diff --git a/doc/src/snippets/code/doc_src_deployment.pro b/doc/src/snippets/code/doc_src_deployment.pro new file mode 100644 index 0000000..b9fdd54 --- /dev/null +++ b/doc/src/snippets/code/doc_src_deployment.pro @@ -0,0 +1,87 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [8] +DESTDIR = /path/to/Qt/plugandpaint/plugins +#! [8] + + +#! [21] +CONFIG += embed_manifest_exe +#! [21] + + +#! [23] +CONFIG-=embed_manifest_dll +#! [23] + + +#! [26] +CONFIG-=app_bundle +#! [26] + + +#! [51] +QMAKE_MACOSX_DEPLOYMENT_TARGET = 10.3 +#! [51] + +#! [53] +QMAKE_MAC_SDK=/Developer/SDKs/MacOSX10.4u.sdk +CONFIG+=x86 ppc +#! [53] + +#! [56] +vendorinfo = \ + "%{\"Example Localized Vendor\"}" \ + ":\"Example Vendor\"" + +my_deployment.pkg_prerules = vendorinfo +DEPLOYMENT += my_deployment +#! [56] + +#! [57] +supported_platforms = \ + "; This demo only supports S60 5.0" \ + "[0x1028315F],0,0,0,{\"S60ProductID\"}" + +default_deployment.pkg_prerules -= pkg_platform_dependencies +my_deployment.pkg_prerules += supported_platforms +DEPLOYMENT += my_deployment +#! [57] diff --git a/doc/src/snippets/code/doc_src_deployment.qdoc b/doc/src/snippets/code/doc_src_deployment.qdoc index c5f4644..760bd8f 100644 --- a/doc/src/snippets/code/doc_src_deployment.qdoc +++ b/doc/src/snippets/code/doc_src_deployment.qdoc @@ -96,20 +96,10 @@ dirname=$PWD/$dirname fi LD_LIBRARY_PATH=$dirname export LD_LIBRARY_PATH -$dirname/$appname $* +$dirname/$appname "$@" //! [7] -//! [8] -DESTDIR = /path/to/Qt/plugandpaint/plugins -//! [8] - - -//! [9] -qApp->addLibraryPath("/some/other/path"); -//! [9] - - //! [10] ldd ./application //! [10] @@ -164,11 +154,6 @@ plugins\pnp_extrafilters.dll //! [18] -//! [19] -qApp->addLibraryPath("C:\some\other\path"); -//! [19] - - //! [20] embed_manifest_dll embed_manifest_exe @@ -411,14 +396,6 @@ install_name_tool -change /path/to/Qt/lib/QtCore.framework/Versions/4.0/QtCore //! [48] -//! [49] -QDir dir(QApplication::applicationDirPath()); -dir.cdUp(); -dir.cd("plugins"); -QApplication::setLibraryPaths(QStringList(dir.absolutePath())); -//! [49] - - //! [50] otool -L MyApp.app/Contents/MacOS/MyApp //! [50] @@ -483,4 +460,4 @@ make release-gcce //! [59] make installer_sis -//! [59]
\ No newline at end of file +//! [59] diff --git a/doc/src/snippets/code/doc_src_designer-manual.qdoc b/doc/src/snippets/code/doc_src_designer-manual.cpp index 90e34a4..a261818 100644 --- a/doc/src/snippets/code/doc_src_designer-manual.qdoc +++ b/doc/src/snippets/code/doc_src_designer-manual.cpp @@ -38,11 +38,6 @@ ** ****************************************************************************/ -//! [0] -CONFIG += uitools -//! [0] - - //! [1] #include <QtUiTools> //! [1] @@ -53,27 +48,6 @@ void on_<object name>_<signal name>(<signal parameters>); //! [2] -//! [3] -CONFIG += release -//! [3] - - -//! [4] -target.path = $$[QT_INSTALL_PLUGINS]/designer -INSTALLS += target -//! [4] - - -//! [5] -QT += script -//! [5] - - -//! [6] -widget.text = 'Hi - I was built ' + new Date().toString(); -//! [6] - - //! [7] class MyExtension: public QObject, public QdesignerContainerExtension diff --git a/doc/src/snippets/code/doc_src_designer-manual.js b/doc/src/snippets/code/doc_src_designer-manual.js new file mode 100644 index 0000000..074b47e --- /dev/null +++ b/doc/src/snippets/code/doc_src_designer-manual.js @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [6] +widget.text = 'Hi - I was built ' + new Date().toString(); +//! [6] diff --git a/doc/src/snippets/code/doc_src_designer-manual.pro b/doc/src/snippets/code/doc_src_designer-manual.pro new file mode 100644 index 0000000..4b14a14 --- /dev/null +++ b/doc/src/snippets/code/doc_src_designer-manual.pro @@ -0,0 +1,59 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [0] +CONFIG += uitools +#! [0] + + +#! [3] +CONFIG += release +#! [3] + + +#! [4] +target.path = $$[QT_INSTALL_PLUGINS]/designer +INSTALLS += target +#! [4] + + +#! [5] +QT += script +#! [5] diff --git a/doc/src/snippets/code/doc_src_dnd.qdoc b/doc/src/snippets/code/doc_src_dnd.cpp index d5dc721..d5dc721 100644 --- a/doc/src/snippets/code/doc_src_dnd.qdoc +++ b/doc/src/snippets/code/doc_src_dnd.cpp diff --git a/doc/src/snippets/code/doc_src_emb-performance.cpp b/doc/src/snippets/code/doc_src_emb-performance.cpp new file mode 100644 index 0000000..5a465a9 --- /dev/null +++ b/doc/src/snippets/code/doc_src_emb-performance.cpp @@ -0,0 +1,71 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [1] +void *operator new[](size_t size) +{ + return malloc(size); +} + +void *operator new(size_t size) +{ + return malloc(size); +} + +void operator delete[](void *ptr) +{ + free(ptr); +} + +void operator delete[](void *ptr, size_t) +{ + free(ptr); +} + +void operator delete(void *ptr) +{ + free(ptr); +} + +void operator delete(void *ptr, size_t) +{ + free(ptr); +} +//! [1] diff --git a/doc/src/snippets/code/doc_src_emb-performance.qdoc b/doc/src/snippets/code/doc_src_emb-performance.qdoc index 8c129fd..9abf8d1 100644 --- a/doc/src/snippets/code/doc_src_emb-performance.qdoc +++ b/doc/src/snippets/code/doc_src_emb-performance.qdoc @@ -41,36 +41,3 @@ //! [0] ./configure -static //! [0] - - -//! [1] -void *operator new[](size_t size) -{ - return malloc(size); -} - -void *operator new(size_t size) -{ - return malloc(size); -} - -void operator delete[](void *ptr) -{ - free(ptr); -} - -void operator delete[](void *ptr, size_t) -{ - free(ptr); -} - -void operator delete(void *ptr) -{ - free(ptr); -} - -void operator delete(void *ptr, size_t) -{ - free(ptr); -} -//! [1] diff --git a/doc/src/snippets/code/doc_src_emb-pointer.pro b/doc/src/snippets/code/doc_src_emb-pointer.pro new file mode 100644 index 0000000..fed7d79 --- /dev/null +++ b/doc/src/snippets/code/doc_src_emb-pointer.pro @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [7] +.... +QMAKE_CFLAGS += -I<path to tslib headers> +QMAKE_LFLAGS += -L<path to tslib library> -Wl,-rpath-link=<path to tslib library> +.... +#! [7] diff --git a/doc/src/snippets/code/doc_src_emb-pointer.qdoc b/doc/src/snippets/code/doc_src_emb-pointer.qdoc index 4ec1335..1fb6d8f 100644 --- a/doc/src/snippets/code/doc_src_emb-pointer.qdoc +++ b/doc/src/snippets/code/doc_src_emb-pointer.qdoc @@ -75,14 +75,6 @@ export QWS_MOUSE_PROTO="Vr41xx:press=500:/dev/misc/ts" //! [6] -//! [7] -.... -QMAKE_CFLAGS += -I<path to tslib headers> -QMAKE_LFLAGS += -L<path to tslib library> -Wl,-rpath-link=<path to tslib library> -.... -//! [7] - - //! [8] module_raw input module linear @@ -111,5 +103,3 @@ ls -l /dev/input/mouse0 //! [12] chmod a+rw /dev/input/mouse0 //! [12] - - diff --git a/doc/src/snippets/code/doc_src_examples_arrowpad.cpp b/doc/src/snippets/code/doc_src_examples_arrowpad.cpp new file mode 100644 index 0000000..c834b9f --- /dev/null +++ b/doc/src/snippets/code/doc_src_examples_arrowpad.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +qApp->translate("ArrowPad", x) +//! [0] diff --git a/doc/src/snippets/code/doc_src_examples_arrowpad.qdoc b/doc/src/snippets/code/doc_src_examples_arrowpad.qdoc index 933f419..ee3c367 100644 --- a/doc/src/snippets/code/doc_src_examples_arrowpad.qdoc +++ b/doc/src/snippets/code/doc_src_examples_arrowpad.qdoc @@ -38,11 +38,6 @@ ** ****************************************************************************/ -//! [0] -qApp->translate("ArrowPad", x) -//! [0] - - //! [1] lrelease arrowpad.pro //! [1] diff --git a/doc/src/snippets/code/doc_src_examples_taskmenuextension.qdoc b/doc/src/snippets/code/doc_src_examples_containerextension.pro index 7fe0394..cd86693 100644 --- a/doc/src/snippets/code/doc_src_examples_taskmenuextension.qdoc +++ b/doc/src/snippets/code/doc_src_examples_containerextension.pro @@ -38,7 +38,7 @@ ** ****************************************************************************/ -//! [0] +#! [0] target.path = $$[QT_INSTALL_PLUGINS]/designer INSTALLS += target -//! [0] +#! [0] diff --git a/doc/src/snippets/code/doc_src_examples_worldtimeclockplugin.qdoc b/doc/src/snippets/code/doc_src_examples_customwidgetplugin.pro index 7fe0394..cd86693 100644 --- a/doc/src/snippets/code/doc_src_examples_worldtimeclockplugin.qdoc +++ b/doc/src/snippets/code/doc_src_examples_customwidgetplugin.pro @@ -38,7 +38,7 @@ ** ****************************************************************************/ -//! [0] +#! [0] target.path = $$[QT_INSTALL_PLUGINS]/designer INSTALLS += target -//! [0] +#! [0] diff --git a/doc/src/snippets/code/doc_src_examples_editabletreemodel.qdoc b/doc/src/snippets/code/doc_src_examples_editabletreemodel.cpp index a69a7bf..a69a7bf 100644 --- a/doc/src/snippets/code/doc_src_examples_editabletreemodel.qdoc +++ b/doc/src/snippets/code/doc_src_examples_editabletreemodel.cpp diff --git a/doc/src/snippets/code/doc_src_examples_icons.cpp b/doc/src/snippets/code/doc_src_examples_icons.cpp new file mode 100644 index 0000000..411c49f --- /dev/null +++ b/doc/src/snippets/code/doc_src_examples_icons.cpp @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +if (!condition) + qFatal("ASSERT: "condition" in file ..."); +//! [0] diff --git a/doc/src/snippets/code/doc_src_examples_icons.qdoc b/doc/src/snippets/code/doc_src_examples_icons.qdoc index 7684224..8ca5751 100644 --- a/doc/src/snippets/code/doc_src_examples_icons.qdoc +++ b/doc/src/snippets/code/doc_src_examples_icons.qdoc @@ -38,12 +38,6 @@ ** ****************************************************************************/ -//! [0] -if (!condition) - qFatal("ASSERT: "condition" in file ..."); -//! [0] - - //! [1] qmake "CONFIG += debug" icons.pro //! [1] diff --git a/doc/src/snippets/code/doc_src_examples_imageviewer.cpp b/doc/src/snippets/code/doc_src_examples_imageviewer.cpp new file mode 100644 index 0000000..c86f8ac --- /dev/null +++ b/doc/src/snippets/code/doc_src_examples_imageviewer.cpp @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +imageLabel->resize(imageLabel->pixmap()->size()); +//! [0] + + +//! [1] +if (!imageLabel->pixmap()) + qFatal("ASSERT: "imageLabel->pixmap()" in file ..."); +//! [1] + + +//! [4] +scrollBar->setValue(int(factor * scrollBar->value())); +//! [4] diff --git a/doc/src/snippets/code/doc_src_examples_imageviewer.qdoc b/doc/src/snippets/code/doc_src_examples_imageviewer.qdoc index 84f822f..1870385 100644 --- a/doc/src/snippets/code/doc_src_examples_imageviewer.qdoc +++ b/doc/src/snippets/code/doc_src_examples_imageviewer.qdoc @@ -38,17 +38,6 @@ ** ****************************************************************************/ -//! [0] -imageLabel->resize(imageLabel->pixmap()->size()); -//! [0] - - -//! [1] -if (!imageLabel->pixmap()) - qFatal("ASSERT: "imageLabel->pixmap()" in file ..."); -//! [1] - - //! [2] qmake "CONFIG += debug" foo.pro //! [2] @@ -57,8 +46,3 @@ qmake "CONFIG += debug" foo.pro //! [3] qmake "CONFIG += release" foo.pro //! [3] - - -//! [4] -scrollBar->setValue(int(factor * scrollBar->value())); -//! [4] diff --git a/doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.qdoc b/doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.cpp index b62236c..b62236c 100644 --- a/doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.qdoc +++ b/doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.cpp diff --git a/doc/src/snippets/code/doc_src_examples_simpledommodel.qdoc b/doc/src/snippets/code/doc_src_examples_simpledommodel.cpp index 1abcdc2..1abcdc2 100644 --- a/doc/src/snippets/code/doc_src_examples_simpledommodel.qdoc +++ b/doc/src/snippets/code/doc_src_examples_simpledommodel.cpp diff --git a/doc/src/snippets/code/doc_src_examples_customwidgetplugin.qdoc b/doc/src/snippets/code/doc_src_examples_taskmenuextension.pro index 7fe0394..cd86693 100644 --- a/doc/src/snippets/code/doc_src_examples_customwidgetplugin.qdoc +++ b/doc/src/snippets/code/doc_src_examples_taskmenuextension.pro @@ -38,7 +38,7 @@ ** ****************************************************************************/ -//! [0] +#! [0] target.path = $$[QT_INSTALL_PLUGINS]/designer INSTALLS += target -//! [0] +#! [0] diff --git a/doc/src/snippets/code/doc_src_examples_textfinder.qdoc b/doc/src/snippets/code/doc_src_examples_textfinder.pro index d99f8ce..cdc2366 100644 --- a/doc/src/snippets/code/doc_src_examples_textfinder.qdoc +++ b/doc/src/snippets/code/doc_src_examples_textfinder.pro @@ -38,9 +38,9 @@ ** ****************************************************************************/ -//! [0] +#! [0] CONFIG += uitools HEADERS = textfinder.h RESOURCES = textfinder.qrc SOURCES = textfinder.cpp main.cpp -//! [0] +#! [0] diff --git a/doc/src/snippets/code/doc_src_examples_trollprint.qdoc b/doc/src/snippets/code/doc_src_examples_trollprint.cpp index 4b508e9..f7b8f48 100644 --- a/doc/src/snippets/code/doc_src_examples_trollprint.qdoc +++ b/doc/src/snippets/code/doc_src_examples_trollprint.cpp @@ -59,6 +59,7 @@ colorsDisabledRadio = new QRadioButton(tr("Disabled", "colors"), colors); belonging to MainWindow. ... +*/ //! [2] @@ -72,4 +73,5 @@ colorsDisabledRadio = new QRadioButton(tr("Disabled", "colors"), colors); checkbox and then click the Start Processing button. You should now see a pop up window with the text "Error: Name too long!". This window is a ZClientErrorDialog. +*/ //! [3] diff --git a/doc/src/snippets/code/doc_src_examples_containerextension.qdoc b/doc/src/snippets/code/doc_src_examples_worldtimeclockplugin.pro index 7fe0394..cd86693 100644 --- a/doc/src/snippets/code/doc_src_examples_containerextension.qdoc +++ b/doc/src/snippets/code/doc_src_examples_worldtimeclockplugin.pro @@ -38,7 +38,7 @@ ** ****************************************************************************/ -//! [0] +#! [0] target.path = $$[QT_INSTALL_PLUGINS]/designer INSTALLS += target -//! [0] +#! [0] diff --git a/doc/src/snippets/code/doc_src_graphicsview.qdoc b/doc/src/snippets/code/doc_src_graphicsview.cpp index 00ebab3..00ebab3 100644 --- a/doc/src/snippets/code/doc_src_graphicsview.qdoc +++ b/doc/src/snippets/code/doc_src_graphicsview.cpp diff --git a/doc/src/snippets/code/doc_src_groups.qdoc b/doc/src/snippets/code/doc_src_groups.cpp index 2d5fd97..2d5fd97 100644 --- a/doc/src/snippets/code/doc_src_groups.qdoc +++ b/doc/src/snippets/code/doc_src_groups.cpp diff --git a/doc/src/snippets/code/doc_src_i18n.cpp b/doc/src/snippets/code/doc_src_i18n.cpp new file mode 100644 index 0000000..cc85bd8 --- /dev/null +++ b/doc/src/snippets/code/doc_src_i18n.cpp @@ -0,0 +1,175 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +LoginWidget::LoginWidget() +{ + QLabel *label = new QLabel(tr("Password:")); + ... +} +//! [0] + + +//! [1] +void some_global_function(LoginWidget *logwid) +{ + QLabel *label = new QLabel( + LoginWidget::tr("Password:"), logwid); +} + +void same_global_function(LoginWidget *logwid) +{ + QLabel *label = new QLabel( + qApp->translate("LoginWidget", "Password:"), logwid); +} +//! [1] + + +//! [2] +QString FriendlyConversation::greeting(int type) +{ + static const char *greeting_strings[] = { + QT_TR_NOOP("Hello"), + QT_TR_NOOP("Goodbye") + }; + return tr(greeting_strings[type]); +} +//! [2] + + +//! [3] +static const char *greeting_strings[] = { + QT_TRANSLATE_NOOP("FriendlyConversation", "Hello"), + QT_TRANSLATE_NOOP("FriendlyConversation", "Goodbye") +}; + +QString FriendlyConversation::greeting(int type) +{ + return tr(greeting_strings[type]); +} + +QString global_greeting(int type) +{ + return qApp->translate("FriendlyConversation", + greeting_strings[type]); +} +//! [3] + + +//! [4] +void FileCopier::showProgress(int done, int total, + const QString ¤tFile) +{ + label.setText(tr("%1 of %2 files copied.\nCopying: %3") + .arg(done) + .arg(total) + .arg(currentFile)); +} +//! [4] + + +//! [5] +QString s1 = "%1 of %2 files copied. Copying: %3"; +QString s2 = "Kopierer nu %3. Av totalt %2 filer er %1 kopiert."; + +qDebug() << s1.arg(5).arg(10).arg("somefile.txt"); +qDebug() << s2.arg(5).arg(10).arg("somefile.txt"); +//! [5] + + +//! [8] +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + + QTranslator qtTranslator; + qtTranslator.load("qt_" + QLocale::system().name(), + QLibraryInfo::location(QLibraryInfo::TranslationsPath)); + app.installTranslator(&qtTranslator); + + QTranslator myappTranslator; + myappTranslator.load("myapp_" + QLocale::system().name()); + app.installTranslator(&myappTranslator); + + ... + return app.exec(); +} +//! [8] + + +//! [9] +QString string = ...; // some Unicode text + +QTextCodec *codec = QTextCodec::codecForName("ISO 8859-5"); +QByteArray encodedString = codec->fromUnicode(string); +//! [9] + + +//! [10] +QByteArray encodedString = ...; // some ISO 8859-5 encoded text + +QTextCodec *codec = QTextCodec::codecForName("ISO 8859-5"); +QString string = codec->toUnicode(encodedString); +//! [10] + + +//! [11] +void Clock::setTime(const QTime &time) +{ + if (tr("AMPM") == "AMPM") { + // 12-hour clock + } else { + // 24-hour clock + } +} +//! [11] + + +//! [12] +void MyWidget::changeEvent(QEvent *event) +{ + if (e->type() == QEvent::LanguageChange) { + titleLabel->setText(tr("Document Title")); + ... + okPushButton->setText(tr("&OK")); + } else + QWidget::changeEvent(event); +} +//! [12] diff --git a/doc/src/snippets/code/doc_src_i18n.qdoc b/doc/src/snippets/code/doc_src_i18n.qdoc index f54ce37..f8f8f02 100644 --- a/doc/src/snippets/code/doc_src_i18n.qdoc +++ b/doc/src/snippets/code/doc_src_i18n.qdoc @@ -38,82 +38,6 @@ ** ****************************************************************************/ -//! [0] -LoginWidget::LoginWidget() -{ - QLabel *label = new QLabel(tr("Password:")); - ... -} -//! [0] - - -//! [1] -void some_global_function(LoginWidget *logwid) -{ - QLabel *label = new QLabel( - LoginWidget::tr("Password:"), logwid); -} - -void same_global_function(LoginWidget *logwid) -{ - QLabel *label = new QLabel( - qApp->translate("LoginWidget", "Password:"), logwid); -} -//! [1] - - -//! [2] -QString FriendlyConversation::greeting(int type) -{ - static const char *greeting_strings[] = { - QT_TR_NOOP("Hello"), - QT_TR_NOOP("Goodbye") - }; - return tr(greeting_strings[type]); -} -//! [2] - - -//! [3] -static const char *greeting_strings[] = { - QT_TRANSLATE_NOOP("FriendlyConversation", "Hello"), - QT_TRANSLATE_NOOP("FriendlyConversation", "Goodbye") -}; - -QString FriendlyConversation::greeting(int type) -{ - return tr(greeting_strings[type]); -} - -QString global_greeting(int type) -{ - return qApp->translate("FriendlyConversation", - greeting_strings[type]); -} -//! [3] - - -//! [4] -void FileCopier::showProgress(int done, int total, - const QString ¤tFile) -{ - label.setText(tr("%1 of %2 files copied.\nCopying: %3") - .arg(done) - .arg(total) - .arg(currentFile)); -} -//! [4] - - -//! [5] -QString s1 = "%1 of %2 files copied. Copying: %3"; -QString s2 = "Kopierer nu %3. Av totalt %2 filer er %1 kopiert."; - -qDebug() << s1.arg(5).arg(10).arg("somefile.txt"); -qDebug() << s2.arg(5).arg(10).arg("somefile.txt"); -//! [5] - - //! [6] 5 of 10 files copied. Copying: somefile.txt Kopierer nu somefile.txt. Av totalt 10 filer er 5 kopiert. @@ -132,64 +56,3 @@ TRANSLATIONS = superapp_dk.ts \ superapp_no.ts \ superapp_se.ts //! [7] - - -//! [8] -int main(int argc, char *argv[]) -{ - QApplication app(argc, argv); - - QTranslator qtTranslator; - qtTranslator.load("qt_" + QLocale::system().name(), - QLibraryInfo::location(QLibraryInfo::TranslationsPath)); - app.installTranslator(&qtTranslator); - - QTranslator myappTranslator; - myappTranslator.load("myapp_" + QLocale::system().name()); - app.installTranslator(&myappTranslator); - - ... - return app.exec(); -} -//! [8] - - -//! [9] -QString string = ...; // some Unicode text - -QTextCodec *codec = QTextCodec::codecForName("ISO 8859-5"); -QByteArray encodedString = codec->fromUnicode(string); -//! [9] - - -//! [10] -QByteArray encodedString = ...; // some ISO 8859-5 encoded text - -QTextCodec *codec = QTextCodec::codecForName("ISO 8859-5"); -QString string = codec->toUnicode(encodedString); -//! [10] - - -//! [11] -void Clock::setTime(const QTime &time) -{ - if (tr("AMPM") == "AMPM") { - // 12-hour clock - } else { - // 24-hour clock - } -} -//! [11] - - -//! [12] -void MyWidget::changeEvent(QEvent *event) -{ - if (e->type() == QEvent::LanguageChange) { - titleLabel->setText(tr("Document Title")); - ... - okPushButton->setText(tr("&OK")); - } else - QWidget::changeEvent(event); -} -//! [12] diff --git a/doc/src/snippets/code/doc_src_layout.qdoc b/doc/src/snippets/code/doc_src_layout.cpp index 47db36b..47db36b 100644 --- a/doc/src/snippets/code/doc_src_layout.qdoc +++ b/doc/src/snippets/code/doc_src_layout.cpp diff --git a/doc/src/snippets/code/doc_src_linguist-manual.cpp b/doc/src/snippets/code/doc_src_linguist-manual.cpp new file mode 100644 index 0000000..7cb5b1e --- /dev/null +++ b/doc/src/snippets/code/doc_src_linguist-manual.cpp @@ -0,0 +1,157 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [3] +label->setText(tr("F\374r \310lise")); +//! [3] + + +void wrapInFunction() +{ +//! [6] +button = new QPushButton("&Quit", this); +//! [6] + + +//! [7] +button = new QPushButton(tr("&Quit"), this); +//! [7] + + +//! [8] +QPushButton::tr("&Quit") +//! [8] + + +//! [9] +QObject::tr("&Quit") +//! [9] + + +//! [10] +rbc = new QRadioButton(tr("Enabled", "Color frame"), this); +//! [10] + + +//! [11] +rbh = new QRadioButton(tr("Enabled", "Hue frame"), this); +//! [11] +} + + +//! [12] +/* + TRANSLATOR FindDialog + + Choose Edit|Find from the menu bar or press Ctrl+F to pop up the + Find dialog. + + ... +*/ +//! [12] + +//! [13] +/* + TRANSLATOR MyNamespace::MyClass + + Necessary for lupdate. + + ... +*/ +//! [13] + +//! [14] +void some_global_function(LoginWidget *logwid) +{ + QLabel *label = new QLabel( + LoginWidget::tr("Password:"), logwid); +} + +void same_global_function(LoginWidget *logwid) +{ + QLabel *label = new QLabel( + qApp->translate("LoginWidget", "Password:"), + logwid); +} +//! [14] + + +//! [15] +QString FriendlyConversation::greeting(int greet_type) +{ + static const char* greeting_strings[] = { + QT_TR_NOOP("Hello"), + QT_TR_NOOP("Goodbye") + }; + return tr(greeting_strings[greet_type]); +} +//! [15] + + +//! [16] +static const char* greeting_strings[] = { + QT_TRANSLATE_NOOP("FriendlyConversation", "Hello"), + QT_TRANSLATE_NOOP("FriendlyConversation", "Goodbye") +}; + +QString FriendlyConversation::greeting(int greet_type) +{ + return tr(greeting_strings[greet_type]); +} + +QString global_greeting(int greet_type) +{ + return qApp->translate("FriendlyConversation", + greeting_strings[greet_type]); +} +//! [16] + +void wrapInFunction() +{ + +//! [17] +QString tr(const char *text, const char *comment, int n); +//! [17] + +//! [18] +tr("%n item(s) replaced", "", count); +//! [18] + +} diff --git a/doc/src/snippets/code/doc_src_linguist-manual.pro b/doc/src/snippets/code/doc_src_linguist-manual.pro new file mode 100644 index 0000000..3b19ba7 --- /dev/null +++ b/doc/src/snippets/code/doc_src_linguist-manual.pro @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [0] +HEADERS = main-dlg.h \ + options-dlg.h +SOURCES = main-dlg.cpp \ + options-dlg.cpp \ + main.cpp +FORMS = search-dlg.ui +TRANSLATIONS = superapp_dk.ts \ + superapp_fi.ts \ + superapp_no.ts \ + superapp_se.ts +#! [0] + + +#! [1] +CODECFORTR = ISO-8859-5 +#! [1] + + +#! [2] +CODECFORSRC = UTF-8 +#! [2] diff --git a/doc/src/snippets/code/doc_src_linguist-manual.qdoc b/doc/src/snippets/code/doc_src_linguist-manual.qdoc index 5975c9a..34b5dcc 100644 --- a/doc/src/snippets/code/doc_src_linguist-manual.qdoc +++ b/doc/src/snippets/code/doc_src_linguist-manual.qdoc @@ -38,35 +38,6 @@ ** ****************************************************************************/ -//! [0] -HEADERS = main-dlg.h \ - options-dlg.h -SOURCES = main-dlg.cpp \ - options-dlg.cpp \ - main.cpp -FORMS = search-dlg.ui -TRANSLATIONS = superapp_dk.ts \ - superapp_fi.ts \ - superapp_no.ts \ - superapp_se.ts -//! [0] - - -//! [1] -CODECFORTR = ISO-8859-5 -//! [1] - - -//! [2] -CODECFORSRC = UTF-8 -//! [2] - - -//! [3] -label->setText(tr("F\374r \310lise")); -//! [3] - - //! [4] Usage: lupdate [options] [project-file] @@ -116,118 +87,3 @@ Options: -version Display the version of lrelease and exit //! [5] - - -void wrapInFunction() -{ -//! [6] -button = new QPushButton("&Quit", this); -//! [6] - - -//! [7] -button = new QPushButton(tr("&Quit"), this); -//! [7] - - -//! [8] -QPushButton::tr("&Quit") -//! [8] - - -//! [9] -QObject::tr("&Quit") -//! [9] - - -//! [10] -rbc = new QRadioButton(tr("Enabled", "Color frame"), this); -//! [10] - - -//! [11] -rbh = new QRadioButton(tr("Enabled", "Hue frame"), this); -//! [11] -} - - -//! [12] -/* - TRANSLATOR FindDialog - - Choose Edit|Find from the menu bar or press Ctrl+F to pop up the - Find dialog. - - ... -*/ -//! [12] - -//! [13] -/* - TRANSLATOR MyNamespace::MyClass - - Necessary for lupdate. - - ... -*/ -//! [13] - -//! [14] -void some_global_function(LoginWidget *logwid) -{ - QLabel *label = new QLabel( - LoginWidget::tr("Password:"), logwid); -} - -void same_global_function(LoginWidget *logwid) -{ - QLabel *label = new QLabel( - qApp->translate("LoginWidget", "Password:"), - logwid); -} -//! [14] - - -//! [15] -QString FriendlyConversation::greeting(int greet_type) -{ - static const char* greeting_strings[] = { - QT_TR_NOOP("Hello"), - QT_TR_NOOP("Goodbye") - }; - return tr(greeting_strings[greet_type]); -} -//! [15] - - -//! [16] -static const char* greeting_strings[] = { - QT_TRANSLATE_NOOP("FriendlyConversation", "Hello"), - QT_TRANSLATE_NOOP("FriendlyConversation", "Goodbye") -}; - -QString FriendlyConversation::greeting(int greet_type) -{ - return tr(greeting_strings[greet_type]); -} - -QString global_greeting(int greet_type) -{ - return qApp->translate("FriendlyConversation", - greeting_strings[greet_type]); -} -//! [16] - -void wrapInFunction() -{ - -//! [17] -QString tr(const char *text, const char *comment, int n); -//! [17] - -//! [18] -tr("%n item(s) replaced", "", count); -//! [18] - -} - diff --git a/doc/src/snippets/code/doc_src_mac-differences.cpp b/doc/src/snippets/code/doc_src_mac-differences.cpp new file mode 100644 index 0000000..f261083 --- /dev/null +++ b/doc/src/snippets/code/doc_src_mac-differences.cpp @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [1] +#ifdef Q_WS_MAC + CFURLRef appUrlRef = CFBundleCopyBundleURL(CFBundleGetMainBundle()); + CFStringRef macPath = CFURLCopyFileSystemPath(appUrlRef, + kCFURLPOSIXPathStyle); + const char *pathPtr = CFStringGetCStringPtr(macPath, + CFStringGetSystemEncoding()); + qDebug("Path = %s", pathPtr); + CFRelease(appUrlRef); + CFRelease(macPath); +#endif +//! [1] diff --git a/doc/src/snippets/code/doc_src_mac-differences.pro b/doc/src/snippets/code/doc_src_mac-differences.pro new file mode 100644 index 0000000..3490bfe --- /dev/null +++ b/doc/src/snippets/code/doc_src_mac-differences.pro @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [0] +QMAKE_LFLAGS_SONAME = -Wl,-install_name,@executable_path/../Frameworks/ +#! [0] diff --git a/doc/src/snippets/code/doc_src_moc.cpp b/doc/src/snippets/code/doc_src_moc.cpp new file mode 100644 index 0000000..ec756e1 --- /dev/null +++ b/doc/src/snippets/code/doc_src_moc.cpp @@ -0,0 +1,144 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [3] +#include "foo.moc" +//! [3] + + +//! [4] +#ifndef Q_MOC_RUN + ... +#endif +//! [4] + + +//! [5] +class SomeTemplate<int> : public QFrame +{ + Q_OBJECT + ... + +signals: + void mySignal(int); +}; +//! [5] + + +//! [6] +// correct +class SomeClass : public QObject, public OtherClass +{ + ... +}; +//! [6] + + +//! [7] +class SomeClass : public QObject +{ + Q_OBJECT + +public slots: + void apply(void (*apply)(List *, void *), char *); // WRONG +}; +//! [7] + + +//! [8] +typedef void (*ApplyFunction)(List *, void *); + +class SomeClass : public QObject +{ + Q_OBJECT + +public slots: + void apply(ApplyFunction, char *); +}; +//! [8] + + +//! [9] +class MyClass : public QObject +{ + Q_OBJECT + + enum Error { + ConnectionRefused, + RemoteHostClosed, + UnknownError + }; + +signals: + void stateChanged(MyClass::Error error); +}; +//! [9] + + +//! [10] +#ifdef ultrix +#define SIGNEDNESS(a) unsigned a +#else +#define SIGNEDNESS(a) a +#endif + +class Whatever : public QObject +{ + Q_OBJECT + +signals: + void someSignal(SIGNEDNESS(int)); +}; +//! [10] + + +//! [11] +class A +{ +public: + class B + { + Q_OBJECT + + public slots: // WRONG + void b(); + }; +}; +//! [11] diff --git a/doc/src/snippets/code/doc_src_moc.qdoc b/doc/src/snippets/code/doc_src_moc.qdoc index ef85b1b..74ab365 100644 --- a/doc/src/snippets/code/doc_src_moc.qdoc +++ b/doc/src/snippets/code/doc_src_moc.qdoc @@ -56,109 +56,3 @@ foo.o: foo.moc foo.moc: foo.cpp moc $(DEFINES) $(INCPATH) -i $< -o $@ //! [2] - - -//! [3] -#include "foo.moc" -//! [3] - - -//! [4] -#ifndef Q_MOC_RUN - ... -#endif -//! [4] - - -//! [5] -class SomeTemplate<int> : public QFrame -{ - Q_OBJECT - ... - -signals: - void mySignal(int); -}; -//! [5] - - -//! [6] -// correct -class SomeClass : public QObject, public OtherClass -{ - ... -}; -//! [6] - - -//! [7] -class SomeClass : public QObject -{ - Q_OBJECT - -public slots: - void apply(void (*apply)(List *, void *), char *); // WRONG -}; -//! [7] - - -//! [8] -typedef void (*ApplyFunction)(List *, void *); - -class SomeClass : public QObject -{ - Q_OBJECT - -public slots: - void apply(ApplyFunction, char *); -}; -//! [8] - - -//! [9] -class MyClass : public QObject -{ - Q_OBJECT - - enum Error { - ConnectionRefused, - RemoteHostClosed, - UnknownError - }; - -signals: - void stateChanged(MyClass::Error error); -}; -//! [9] - - -//! [10] -#ifdef ultrix -#define SIGNEDNESS(a) unsigned a -#else -#define SIGNEDNESS(a) a -#endif - -class Whatever : public QObject -{ - Q_OBJECT - -signals: - void someSignal(SIGNEDNESS(int)); -}; -//! [10] - - -//! [11] -class A -{ -public: - class B - { - Q_OBJECT - - public slots: // WRONG - void b(); - }; -}; -//! [11] diff --git a/doc/src/snippets/code/doc_src_model-view-programming.qdoc b/doc/src/snippets/code/doc_src_model-view-programming.cpp index 05c2e1d..05c2e1d 100644 --- a/doc/src/snippets/code/doc_src_model-view-programming.qdoc +++ b/doc/src/snippets/code/doc_src_model-view-programming.cpp diff --git a/doc/src/snippets/code/doc_src_modules.qdoc b/doc/src/snippets/code/doc_src_modules.pro index 643a94d..5871540 100644 --- a/doc/src/snippets/code/doc_src_modules.qdoc +++ b/doc/src/snippets/code/doc_src_modules.pro @@ -38,6 +38,6 @@ ** ****************************************************************************/ -//! [0] +#! [0] QT -= gui -//! [0] +#! [0] diff --git a/doc/src/snippets/code/doc_src_objecttrees.qdoc b/doc/src/snippets/code/doc_src_objecttrees.cpp index cd92a49..cd92a49 100644 --- a/doc/src/snippets/code/doc_src_objecttrees.qdoc +++ b/doc/src/snippets/code/doc_src_objecttrees.cpp diff --git a/doc/src/snippets/code/doc_src_phonon-api.qdoc b/doc/src/snippets/code/doc_src_phonon-api.cpp index d7a989b..d7a989b 100644 --- a/doc/src/snippets/code/doc_src_phonon-api.qdoc +++ b/doc/src/snippets/code/doc_src_phonon-api.cpp diff --git a/doc/src/snippets/code/doc_src_phonon.pro b/doc/src/snippets/code/doc_src_phonon.pro new file mode 100644 index 0000000..24cc7bd --- /dev/null +++ b/doc/src/snippets/code/doc_src_phonon.pro @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [0] +QT += phonon +#! [0] diff --git a/doc/src/snippets/code/doc_src_plugins-howto.cpp b/doc/src/snippets/code/doc_src_plugins-howto.cpp new file mode 100644 index 0000000..06bf903 --- /dev/null +++ b/doc/src/snippets/code/doc_src_plugins-howto.cpp @@ -0,0 +1,89 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +class MyStylePlugin : public QStylePlugin +{ +public: + QStringList keys() const; + QStyle *create(const QString &key); +}; +//! [0] + + +//! [1] +#include "mystyleplugin.h" + +QStringList MyStylePlugin::keys() const +{ + return QStringList() << "MyStyle"; +} + +QStyle *MyStylePlugin::create(const QString &key) +{ + if (key.toLower() == "mystyle") + return new MyStyle; + return 0; +} + +Q_EXPORT_PLUGIN2(pnp_mystyleplugin, MyStylePlugin) +//! [1] + + +//! [2] +QApplication::setStyle(QStyleFactory::create("MyStyle")); +//! [2] + + +//! [4] +#include <QApplication> +#include <QtPlugin> + +Q_IMPORT_PLUGIN(qjpeg) +Q_IMPORT_PLUGIN(qgif) +Q_IMPORT_PLUGIN(qkrcodecs) + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + ... + return app.exec(); +} +//! [4] diff --git a/doc/src/snippets/code/doc_src_plugins-howto.pro b/doc/src/snippets/code/doc_src_plugins-howto.pro new file mode 100644 index 0000000..eb0ec28 --- /dev/null +++ b/doc/src/snippets/code/doc_src_plugins-howto.pro @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [3] +CONFIG += release +#! [3] + + +#! [5] +QTPLUGIN += qjpeg \ + qgif \ + qkrcodecs +#! [5] diff --git a/doc/src/snippets/code/doc_src_plugins-howto.qdoc b/doc/src/snippets/code/doc_src_plugins-howto.qdoc index e80faee..b03dfed 100644 --- a/doc/src/snippets/code/doc_src_plugins-howto.qdoc +++ b/doc/src/snippets/code/doc_src_plugins-howto.qdoc @@ -38,69 +38,6 @@ ** ****************************************************************************/ -//! [0] -class MyStylePlugin : public QStylePlugin -{ -public: - QStringList keys() const; - QStyle *create(const QString &key); -}; -//! [0] - - -//! [1] -#include "mystyleplugin.h" - -QStringList MyStylePlugin::keys() const -{ - return QStringList() << "MyStyle"; -} - -QStyle *MyStylePlugin::create(const QString &key) -{ - if (key.toLower() == "mystyle") - return new MyStyle; - return 0; -} - -Q_EXPORT_PLUGIN2(pnp_mystyleplugin, MyStylePlugin) -//! [1] - - -//! [2] -QApplication::setStyle(QStyleFactory::create("MyStyle")); -//! [2] - - -//! [3] -CONFIG += release -//! [3] - - -//! [4] -#include <QApplication> -#include <QtPlugin> - -Q_IMPORT_PLUGIN(qjpeg) -Q_IMPORT_PLUGIN(qgif) -Q_IMPORT_PLUGIN(qkrcodecs) - -int main(int argc, char *argv[]) -{ - QApplication app(argc, argv); - ... - return app.exec(); -} -//! [4] - - -//! [5] -QTPLUGIN += qjpeg \ - qgif \ - qkrcodecs -//! [5] - - //! [6] HKEY_CURRENT_USER\Software\Trolltech\OrganizationDefaults\Qt Plugin Cache 4.2.debug HKEY_CURRENT_USER\Software\Trolltech\OrganizationDefaults\Qt Plugin Cache 4.2.false diff --git a/doc/src/snippets/code/doc_src_porting-qsa.cpp b/doc/src/snippets/code/doc_src_porting-qsa.cpp new file mode 100644 index 0000000..f9b9c6b --- /dev/null +++ b/doc/src/snippets/code/doc_src_porting-qsa.cpp @@ -0,0 +1,89 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [16] +QPushButton *button = new QPushButton(); +button->setObjectName("button"); +interpreter->addTransientObject(button); +//! [16] + + +//! [17] +QPushButton *button = new QPushButton(); +QScriptValue scriptButton = engine.newQObject(button); +engine.globalObject().setProperty("button", scriptButton); +//! [17] + + +//! [18] +ModuleFactory::ModuleFactory() +{ + registerClass( "ImageSource", &ImgSource::staticMetaObject); + ... +} + +QObject *ModuleFactory::create( const QString &type, + const QVariantList &, + QObject * ) +{ + if ( type == "ImageSource" ) + return new ImgSource(); + ... +} + +... + +interpreter.addObjectFactory(new ModuleFactory()); +//! [18] + + +//! [19] +QScriptValue construct_QPushButton(QScriptContext *, QScriptEngine *engine) { + return engine->newQObject(new QPushButton()); +} + +... + +QScriptValue constructor = engine.newFunction(construct_QPushButton); +QScriptValue value = + engine.newQMetaObject(&QPushButton::staticMetaObject, + constructor); +engine.globalObject().setProperty("QPushButton", value); +//! [19] diff --git a/doc/src/snippets/code/doc_src_porting-qsa.js b/doc/src/snippets/code/doc_src_porting-qsa.js new file mode 100644 index 0000000..e58f5b7 --- /dev/null +++ b/doc/src/snippets/code/doc_src_porting-qsa.js @@ -0,0 +1,117 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +point = new Object(); +point.x = 12; +point.y = 35; +//! [0] + + +//! [1] +function manhattanLength(point) { + return point.x + point.y; +} +//! [1] + + +//! [2] +manhattanLength = function(point) { + return point.x + point.y; +} +//! [2] + + +//! [3] +point.manhattanLength = function() { + return this.x + this.y; +} +print(point.manhattanLength()); // prints 47 +//! [3] + + +//! [5] +point.manhattanLength = function() { + return this.x + this.y; +} +print(point.manhattanLength()); // prints 47 +//! [5] + + +//! [8] +var car = new Object(); +car.constructor = function(regnr) { + // ... +} +car.constructor(); +//! [8] + + +//! [10] +function Car(regnr) { + this.regNumber = regnr; + this.toString = function() { return this.regNumber; } +} +//! [10] + + +//! [11] +function Car(regnr) { + this.regNumber = regnr; +} +Car.prototype.toString = function() { return this.regNumber; } +//! [11] + + +//! [13] +function GasolineCar(regnr) { + Car(regnr); +} +GasolineCar.prototype = new Car(); +GasolineCar.prototype.toString = function() { + return "GasolineCar(" + this.regNumber + ")"; +} +//! [13] + + +//! [15] +Car.globalCount = 0; +print(Car.globalCount); +//! [15] diff --git a/doc/src/snippets/code/doc_src_porting-qsa.qdoc b/doc/src/snippets/code/doc_src_porting-qsa.qdoc index bb0b7fd..1846640 100644 --- a/doc/src/snippets/code/doc_src_porting-qsa.qdoc +++ b/doc/src/snippets/code/doc_src_porting-qsa.qdoc @@ -38,35 +38,6 @@ ** ****************************************************************************/ -//! [0] -point = new Object(); -point.x = 12; -point.y = 35; -//! [0] - - -//! [1] -function manhattanLength(point) { - return point.x + point.y; -} -//! [1] - - -//! [2] -manhattanLength = function(point) { - return point.x + point.y; -} -//! [2] - - -//! [3] -point.manhattanLength = function() { - return this.x + this.y; -} -print(point.manhattanLength()); // prints 47 -//! [3] - - //! [4] class Point() { var x; @@ -76,14 +47,6 @@ class Point() { //! [4] -//! [5] -point.manhattanLength = function() { - return this.x + this.y; -} -print(point.manhattanLength()); // prints 47 -//! [5] - - //! [6] class Car { var regNumber; @@ -103,13 +66,6 @@ var car = new Car("ABC 123"); //! [7] -//! [8] -var car = new Object(); -car.constructor = function(regnr) { ... } -car.constructor(); -//! [8] - - //! [9] class Car { var regNumber; @@ -123,22 +79,6 @@ class Car { //! [9] -//! [10] -function Car(regnr) { - this.regNumber = regnr; - this.toString = function() { return this.regNumber; } -} -//! [10] - - -//! [11] -function Car(regnr) { - this.regNumber = regnr; -} -Car.prototype.toString = function() { return this.regNumber; } -//! [11] - - //! [12] class GasolineCar extends Car { function GasolineCar(regnr) { @@ -151,77 +91,9 @@ class GasolineCar extends Car { //! [12] -//! [13] -function GasolineCar(regnr) { - Car(regnr); -} -GasolineCar.prototype = new Car(); -GasolineCar.prototype.toString = function() { - return "GasolineCar(" + this.regNumber + ")"; -} -//! [13] - - //! [14] class Car { static var globalCount = 0; } print(Car.globalCount); //! [14] - - -//! [15] -Car.globalCount = 0; -print(Car.globalCount); -//! [15] - - -//! [16] -QPushButton *button = new QPushButton(); -button->setObjectName("button"); -interpreter->addTransientObject(button); -//! [16] - - -//! [17] -QPushButton *button = new QPushButton(); -QScriptValue scriptButton = engine.newQObject(button); -engine.globalObject().setProperty("button", scriptButton); -//! [17] - - -//! [18] -ModuleFactory::ModuleFactory() -{ - registerClass( "ImageSource", &ImgSource::staticMetaObject); - ... -} - -QObject *ModuleFactory::create( const QString &type, - const QVariantList &, - QObject * ) -{ - if ( type == "ImageSource" ) - return new ImgSource(); - ... -} - -... - -interpreter.addObjectFactory(new ModuleFactory()); -//! [18] - - -//! [19] -QScriptValue construct_QPushButton(QScriptContext *, QScriptEngine *engine) { - return engine->newQObject(new QPushButton()); -} - -... - -QScriptValue constructor = engine.newFunction(construct_QPushButton); -QScriptValue value = - engine.newQMetaObject(&QPushButton::staticMetaObject, - constructor); -engine.globalObject().setProperty("QPushButton", value); -//! [19] diff --git a/doc/src/snippets/code/doc_src_porting4-canvas.qdoc b/doc/src/snippets/code/doc_src_porting4-canvas.cpp index 8004163..8004163 100644 --- a/doc/src/snippets/code/doc_src_porting4-canvas.qdoc +++ b/doc/src/snippets/code/doc_src_porting4-canvas.cpp diff --git a/doc/src/snippets/code/doc_src_porting4-designer.cpp b/doc/src/snippets/code/doc_src_porting4-designer.cpp new file mode 100644 index 0000000..1d73aae --- /dev/null +++ b/doc/src/snippets/code/doc_src_porting4-designer.cpp @@ -0,0 +1,173 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +namespace Ui { + +class HelloWorld +{ +public: + QVBoxLayout *vboxLayout; + QPushButton *pushButton; + + void setupUi(QWidget *HelloWorld) + { + HelloWorld->setObjectName(QString::fromUtf8("HelloWorld")); + + vboxLayout = new QVBoxLayout(HelloWorld); + vboxLayout->setObjectName(QString::fromUtf8("vboxLayout")); + + pushButton = new QPushButton(HelloWorld); + pushButton->setObjectName(QString::fromUtf8("pushButton")); + + vboxLayout->addWidget(pushButton); + + retranslateUi(HelloWorld); + } +}; + +} +//! [0] + + +//! [1] +#include <QApplication> +#include <QWidget> + +#include "ui_helloworld.h" // defines Ui::HelloWorld + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + + QWidget w; + Ui::HelloWorld ui; + ui.setupUi(&w); + + w.show(); + return app.exec(); +} +//! [1] + + +//! [2] +#include <QApplication> +#include <QWidget> + +#include "ui_helloworld.h" // defines Ui::HelloWorld + +class HelloWorldWidget : public QWidget, public Ui::HelloWorld +{ + Q_OBJECT + +public: + HelloWorldWidget(QWidget *parent = 0) + : QWidget(parent) + { setupUi(this); } +}; + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + HelloWorldWidget w; + w.show(); + return app.exec(); +} +//! [2] + + +//! [5] +class HelloWorldWidget : public QWidget, public Ui::HelloWorld +{ + Q_OBJECT + +public: + HelloWorldWidget(QWidget *parent = 0); + +public slots: + void mySlot(); +}; + +HelloWorldWidget::HelloWorldWidget(QWidget *parent) + : QWidget(parent) +{ + setupUi(this); + + QObject::connect(pushButton, SIGNAL(clicked()), + this, SLOT(mySlot())); +} + +void HelloWorldWidget::mySlot() +{ + ... +} +//! [5] + + +//! [6] +class HelloWorldWidget : public QWidget, public Ui::HelloWorld +{ + Q_OBJECT + +public: + HelloWorldWidget(QWidget *parent = 0); + +public slots: + void on_pushButton_clicked(); +}; + +HelloWorldWidget::HelloWorldWidget(QWidget *parent) + : QWidget(parent) +{ + setupUi(this); +} + +void HelloWorldWidget::on_pushButton_clicked() +{ + ... +} +//! [6] + + +//! [9] +QFile file(":/icons/yes.png"); +QIcon icon(":/icons/no.png"); +QPixmap pixmap(":/icons/no.png"); +//! [9] diff --git a/doc/src/snippets/code/doc_src_porting4-designer.pro b/doc/src/snippets/code/doc_src_porting4-designer.pro new file mode 100644 index 0000000..673e593 --- /dev/null +++ b/doc/src/snippets/code/doc_src_porting4-designer.pro @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [8] +RESOURCES += icons.qrc +#! [8] diff --git a/doc/src/snippets/code/doc_src_porting4-designer.qdoc b/doc/src/snippets/code/doc_src_porting4-designer.qdoc index 2c043f5..b5c686b 100644 --- a/doc/src/snippets/code/doc_src_porting4-designer.qdoc +++ b/doc/src/snippets/code/doc_src_porting4-designer.qdoc @@ -38,81 +38,6 @@ ** ****************************************************************************/ -//! [0] -namespace Ui { - -class HelloWorld -{ -public: - QVBoxLayout *vboxLayout; - QPushButton *pushButton; - - void setupUi(QWidget *HelloWorld) - { - HelloWorld->setObjectName(QString::fromUtf8("HelloWorld")); - - vboxLayout = new QVBoxLayout(HelloWorld); - vboxLayout->setObjectName(QString::fromUtf8("vboxLayout")); - - pushButton = new QPushButton(HelloWorld); - pushButton->setObjectName(QString::fromUtf8("pushButton")); - - vboxLayout->addWidget(pushButton); - - retranslateUi(HelloWorld); - } -}; - -} -//! [0] - - -//! [1] -#include <QApplication> -#include <QWidget> - -#include "ui_helloworld.h" // defines Ui::HelloWorld - -int main(int argc, char *argv[]) -{ - QApplication app(argc, argv); - - QWidget w; - Ui::HelloWorld ui; - ui.setupUi(&w); - - w.show(); - return app.exec(); -} -//! [1] - - -//! [2] -#include <QApplication> -#include <QWidget> - -#include "ui_helloworld.h" // defines Ui::HelloWorld - -class HelloWorldWidget : public QWidget, public Ui::HelloWorld -{ - Q_OBJECT - -public: - HelloWorldWidget(QWidget *parent = 0) - : QWidget(parent) - { setupUi(this); } -}; - -int main(int argc, char *argv[]) -{ - QApplication app(argc, argv); - HelloWorldWidget w; - w.show(); - return app.exec(); -} -//! [2] - - //! [3] uic3 myform.ui > myform.h uic3 -impl myform.h myform.ui > myform.cpp @@ -124,59 +49,6 @@ uic3 -convert myform3.ui > myform4.ui //! [4] -//! [5] -class HelloWorldWidget : public QWidget, public Ui::HelloWorld -{ - Q_OBJECT - -public: - HelloWorldWidget(QWidget *parent = 0); - -public slots: - void mySlot(); -}; - -HelloWorldWidget::HelloWorldWidget(QWidget *parent) - : QWidget(parent) -{ - setupUi(this); - - QObject::connect(pushButton, SIGNAL(clicked()), - this, SLOT(mySlot())); -} - -void HelloWorldWidget::mySlot() -{ - ... -} -//! [5] - - -//! [6] -class HelloWorldWidget : public QWidget, public Ui::HelloWorld -{ - Q_OBJECT - -public: - HelloWorldWidget(QWidget *parent = 0); - -public slots: - void on_pushButton_clicked(); -}; - -HelloWorldWidget::HelloWorldWidget(QWidget *parent) - : QWidget(parent) -{ - setupUi(this); -} - -void HelloWorldWidget::on_pushButton_clicked() -{ - ... -} -//! [6] - - //! [7] <RCC version="1.0"> <qresource prefix="/icons"> @@ -185,15 +57,3 @@ void HelloWorldWidget::on_pushButton_clicked() </qresource> </RCC> //! [7] - - -//! [8] -RESOURCES += icons.qrc -//! [8] - - -//! [9] -QFile file(":/icons/yes.png"); -QIcon icon(":/icons/no.png"); -QPixmap pixmap(":/icons/no.png"); -//! [9] diff --git a/doc/src/snippets/code/doc_src_porting4.qdoc b/doc/src/snippets/code/doc_src_porting4.cpp index 14c708a..14c708a 100644 --- a/doc/src/snippets/code/doc_src_porting4.qdoc +++ b/doc/src/snippets/code/doc_src_porting4.cpp diff --git a/doc/src/snippets/code/doc_src_properties.qdoc b/doc/src/snippets/code/doc_src_properties.cpp index 1238bc5..b5a103d 100644 --- a/doc/src/snippets/code/doc_src_properties.qdoc +++ b/doc/src/snippets/code/doc_src_properties.cpp @@ -44,6 +44,7 @@ Q_PROPERTY(type name [WRITE setFunction] [RESET resetFunction] [NOTIFY notifySignal] + [REVISION int] [DESIGNABLE bool] [SCRIPTABLE bool] [STORED bool] diff --git a/doc/src/snippets/code/doc_src_q3asciidict.qdoc b/doc/src/snippets/code/doc_src_q3asciidict.cpp index 4b32817..4b32817 100644 --- a/doc/src/snippets/code/doc_src_q3asciidict.qdoc +++ b/doc/src/snippets/code/doc_src_q3asciidict.cpp diff --git a/doc/src/snippets/code/doc_src_q3dict.qdoc b/doc/src/snippets/code/doc_src_q3dict.cpp index 9c51cae..9c51cae 100644 --- a/doc/src/snippets/code/doc_src_q3dict.qdoc +++ b/doc/src/snippets/code/doc_src_q3dict.cpp diff --git a/doc/src/snippets/code/doc_src_q3intdict.qdoc b/doc/src/snippets/code/doc_src_q3intdict.cpp index 0f15b6f..0f15b6f 100644 --- a/doc/src/snippets/code/doc_src_q3intdict.qdoc +++ b/doc/src/snippets/code/doc_src_q3intdict.cpp diff --git a/doc/src/snippets/code/doc_src_q3memarray.cpp b/doc/src/snippets/code/doc_src_q3memarray.cpp new file mode 100644 index 0000000..2c91050 --- /dev/null +++ b/doc/src/snippets/code/doc_src_q3memarray.cpp @@ -0,0 +1,108 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +#include <q3memarray.h> +#include <stdio.h> + +Q3MemArray<int> fib( int num ) // returns fibonacci array +{ + Q_ASSERT( num > 2 ); + Q3MemArray<int> f( num ); // array of ints + + f[0] = f[1] = 1; + for ( int i = 2; i < num; i++ ) + f[i] = f[i-1] + f[i-2]; + + return f; +} + +int main() +{ + Q3MemArray<int> a = fib( 6 ); // get first 6 fibonaccis + for ( int i = 0; i < a.size(); i++ ) + qDebug( "%d: %d", i, a[i] ); + + qDebug( "1 is found %d times", a.contains(1) ); + qDebug( "5 is found at index %d", a.find(5) ); + + return 0; +} +//! [0] + + +//! [2] +// MyStruct may be padded to 4 or 8 bytes +struct MyStruct +{ + short i; // 2 bytes + char c; // 1 byte +}; + +Q3MemArray<MyStruct> a(1); +a[0].i = 5; +a[0].c = 't'; + +MyStruct x; +x.i = '5'; +x.c = 't'; +int i = a.find( x ); // may return -1 if the pad bytes differ +//! [2] + + +//! [3] +static char bindata[] = { 231, 1, 44, ... }; +QByteArray a; +a.setRawData( bindata, sizeof(bindata) ); // a points to bindata +QDataStream s( a, IO_ReadOnly ); // open on a's data +s >> <something>; // read raw bindata +a.resetRawData( bindata, sizeof(bindata) ); // finished +//! [3] + + +//! [4] +static char bindata[] = { 231, 1, 44, ... }; +QByteArray a, b; +a.setRawData( bindata, sizeof(bindata) ); // a points to bindata +a.resize( 8 ); // will crash +b = a; // will crash +a[2] = 123; // might crash +// forget to resetRawData: will crash +//! [4] diff --git a/doc/src/snippets/code/doc_src_q3memarray.qdoc b/doc/src/snippets/code/doc_src_q3memarray.qdoc index 8e5e008..a966e50 100644 --- a/doc/src/snippets/code/doc_src_q3memarray.qdoc +++ b/doc/src/snippets/code/doc_src_q3memarray.qdoc @@ -38,36 +38,6 @@ ** ****************************************************************************/ -//! [0] -#include <q3memarray.h> -#include <stdio.h> - -Q3MemArray<int> fib( int num ) // returns fibonacci array -{ - Q_ASSERT( num > 2 ); - Q3MemArray<int> f( num ); // array of ints - - f[0] = f[1] = 1; - for ( int i = 2; i < num; i++ ) - f[i] = f[i-1] + f[i-2]; - - return f; -} - -int main() -{ - Q3MemArray<int> a = fib( 6 ); // get first 6 fibonaccis - for ( int i = 0; i < a.size(); i++ ) - qDebug( "%d: %d", i, a[i] ); - - qDebug( "1 is found %d times", a.contains(1) ); - qDebug( "5 is found at index %d", a.find(5) ); - - return 0; -} -//! [0] - - //! [1] 0: 1 1: 1 @@ -78,43 +48,3 @@ int main() 1 is found 2 times 5 is found at index 4 //! [1] - - -//! [2] -// MyStruct may be padded to 4 or 8 bytes -struct MyStruct -{ - short i; // 2 bytes - char c; // 1 byte -}; - -Q3MemArray<MyStruct> a(1); -a[0].i = 5; -a[0].c = 't'; - -MyStruct x; -x.i = '5'; -x.c = 't'; -int i = a.find( x ); // may return -1 if the pad bytes differ -//! [2] - - -//! [3] -static char bindata[] = { 231, 1, 44, ... }; -QByteArray a; -a.setRawData( bindata, sizeof(bindata) ); // a points to bindata -QDataStream s( a, IO_ReadOnly ); // open on a's data -s >> <something>; // read raw bindata -a.resetRawData( bindata, sizeof(bindata) ); // finished -//! [3] - - -//! [4] -static char bindata[] = { 231, 1, 44, ... }; -QByteArray a, b; -a.setRawData( bindata, sizeof(bindata) ); // a points to bindata -a.resize( 8 ); // will crash -b = a; // will crash -a[2] = 123; // might crash -// forget to resetRawData: will crash -//! [4] diff --git a/doc/src/snippets/code/doc_src_q3ptrdict.qdoc b/doc/src/snippets/code/doc_src_q3ptrdict.cpp index e64d874..e64d874 100644 --- a/doc/src/snippets/code/doc_src_q3ptrdict.qdoc +++ b/doc/src/snippets/code/doc_src_q3ptrdict.cpp diff --git a/doc/src/snippets/code/doc_src_q3ptrlist.qdoc b/doc/src/snippets/code/doc_src_q3ptrlist.cpp index 4f97c65..4f97c65 100644 --- a/doc/src/snippets/code/doc_src_q3ptrlist.qdoc +++ b/doc/src/snippets/code/doc_src_q3ptrlist.cpp diff --git a/doc/src/snippets/code/doc_src_q3valuelist.qdoc b/doc/src/snippets/code/doc_src_q3valuelist.cpp index 38ee9f6..38ee9f6 100644 --- a/doc/src/snippets/code/doc_src_q3valuelist.qdoc +++ b/doc/src/snippets/code/doc_src_q3valuelist.cpp diff --git a/doc/src/snippets/code/doc_src_q3valuestack.qdoc b/doc/src/snippets/code/doc_src_q3valuestack.cpp index 50827e6..50827e6 100644 --- a/doc/src/snippets/code/doc_src_q3valuestack.qdoc +++ b/doc/src/snippets/code/doc_src_q3valuestack.cpp diff --git a/doc/src/snippets/code/doc_src_q3valuevector.qdoc b/doc/src/snippets/code/doc_src_q3valuevector.cpp index 8af1568..8af1568 100644 --- a/doc/src/snippets/code/doc_src_q3valuevector.qdoc +++ b/doc/src/snippets/code/doc_src_q3valuevector.cpp diff --git a/doc/src/snippets/code/doc_src_qalgorithms.qdoc b/doc/src/snippets/code/doc_src_qalgorithms.cpp index 0438105..0438105 100644 --- a/doc/src/snippets/code/doc_src_qalgorithms.qdoc +++ b/doc/src/snippets/code/doc_src_qalgorithms.cpp diff --git a/doc/src/snippets/code/doc_src_qaxcontainer.qdoc b/doc/src/snippets/code/doc_src_qaxcontainer.pro index 93aa60b..ff39e67 100644 --- a/doc/src/snippets/code/doc_src_qaxcontainer.qdoc +++ b/doc/src/snippets/code/doc_src_qaxcontainer.pro @@ -38,11 +38,11 @@ ** ****************************************************************************/ -//! [0] +#! [0] CONFIG += qaxcontainer -//! [0] +#! [0] -//! [1] +#! [1] TYPELIBS = file.tlb -//! [1] +#! [1] diff --git a/doc/src/snippets/code/doc_src_qaxserver.cpp b/doc/src/snippets/code/doc_src_qaxserver.cpp new file mode 100644 index 0000000..dc16776 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qaxserver.cpp @@ -0,0 +1,218 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [3] +#include <QWidget> + +class MyActiveX : public QWidget +{ + Q_OBJECT +//! [3] + + +//! [4] +Q_CLASSINFO("ClassID", "{1D9928BD-4453-4bdd-903D-E525ED17FDE5}") +Q_CLASSINFO("InterfaceID", "{99F6860E-2C5A-42ec-87F2-43396F4BE389}") +Q_CLASSINFO("EventsID", "{0A3E9F27-E4F1-45bb-9E47-63099BCCD0E3}") +//! [4] + + +//! [5] +Q_PROPERTY(int value READ value WRITE setValue) +//! [5] + + +//! [6] +public: + MyActiveX(QWidget *parent = 0) + ... + + int value() const; + +public slots: + void setValue(int v); + ... + +signals: + void valueChange(int v); + ... + +}; +//! [6] + + +//! [7] +#include <QAxBindable> +#include <QWidget> + +class MyActiveX : public QWidget, public QAxBindable +{ + Q_OBJECT +//! [7] + + +//! [8] +QAXFACTORY_BEGIN("{ad90301a-849e-4e8b-9a91-0a6dc5f6461f}", + "{a8f21901-7ff7-4f6a-b939-789620c03d83}") + QAXCLASS(MyWidget) + QAXCLASS(MyWidget2) + QAXTYPE(MySubType) +QAXFACTORY_END() +//! [8] + + +//! [9] +#include <QApplication> +#include <QAxFactory> + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + if (!QAxFactory::isServer()) { + // create and show main window + } + return app.exec(); +} +//! [9] + + +//! [10] +MyFactory(const QUuid &, const QUuid &); +//! [10] + + +//! [11] +HMODULE dll = LoadLibrary("myserver.dll"); +typedef HRESULT(__stdcall *DllRegisterServerProc)(); +DllRegisterServerProc DllRegisterServer = + (DllRegisterServerProc)GetProcAddress(dll, "DllRegisterServer"); + +HRESULT res = E_FAIL; +if (DllRegisterServer) + res = DllRegisterServer(); +if (res != S_OK) + // error handling +//! [11] + + +//! [15] +class MyActiveX : public QWidget +{ + Q_OBJECT + Q_CLASSINFO("Version", "2.0") + Q_CLASSINFO("ClassID", "{7a4cffd8-cbcd-4ae9-ae7e-343e1e5710df}") + Q_CLASSINFO("InterfaceID", "{6fb035bf-8019-48d8-be51-ef05427d8994}") + Q_CLASSINFO("EventsID", "{c42fffdf-6557-47c9-817a-2da2228bc29c}") + Q_CLASSINFO("Insertable", "yes") + Q_CLASSINFO("ToSuperClass", "MyActiveX") + Q_PROPERTY(...) + +public: + MyActiveX(QWidget *parent = 0); + + ... +}; +//! [15] + + +//! [16] +class MyLicensedControl : public QWidget +{ + Q_OBJECT + Q_CLASSINFO("LicenseKey", "<key string>") + ... +}; +//! [16] + + +//! [17] +class AxImpl : public QAxAggregated, public ISomeCOMInterface +{ +public: + AxImpl() {} + + long queryInterface(const QUuid &iid, void **iface); + + // IUnknown + QAXAGG_IUNKNOWN + + // ISomeCOMInterface + ... +} +//! [17] + + +//! [18] +long AxImpl::queryInterface(const QUuid &iid, void **iface) +{ + *iface = 0; + if (iid == IID_ISomeCOMInterface) + *iface = (ISomeCOMInterface *)this; + else + return E_NOINTERFACE; + + AddRef(); + return S_OK; +} +//! [18] + + +//! [19] +HRESULT AxImpl::QueryInterface(REFIID iid, void **iface) +{ + return controllingUnknown()->QueryInterface(iid, iface); +} +//! [19] + + +//! [20] +class MyActiveX : public QWidget, public QAxBindable +{ + Q_OBJECT + +public: + MyActiveX(QWidget *parent); + + QAxAggregated *createAggregate() + { + return new AxImpl(); + } +}; +//! [20] diff --git a/doc/src/snippets/code/doc_src_qaxserver.pro b/doc/src/snippets/code/doc_src_qaxserver.pro new file mode 100644 index 0000000..18d66f3 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qaxserver.pro @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [0] +TEMPLATE = app +CONFIG += qaxserver + +RC_FILE = qaxserver.rc +... +#! [0] + + +#! [1] +TEMPLATE = lib +CONFIG += qaxserver dll + +DEF_FILE = qaxserver.def +RC_FILE = qaxserver.rc +... +#! [1] + + +#! [2] +TEMPLATE = lib +VERSION = 2.5 +... +#! [2] diff --git a/doc/src/snippets/code/doc_src_qaxserver.qdoc b/doc/src/snippets/code/doc_src_qaxserver.qdoc index c5906e9..2fd79e3 100644 --- a/doc/src/snippets/code/doc_src_qaxserver.qdoc +++ b/doc/src/snippets/code/doc_src_qaxserver.qdoc @@ -38,126 +38,6 @@ ** ****************************************************************************/ -//! [0] -TEMPLATE = app -CONFIG += qaxserver - -RC_FILE = qaxserver.rc -... -//! [0] - - -//! [1] -TEMPLATE = lib -CONFIG += qaxserver dll - -DEF_FILE = qaxserver.def -RC_FILE = qaxserver.rc -... -//! [1] - - -//! [2] -TEMPLATE = lib -VERSION = 2.5 -... -//! [2] - - -//! [3] -#include <QWidget> - -class MyActiveX : public QWidget -{ - Q_OBJECT -//! [3] - - -//! [4] -Q_CLASSINFO("ClassID", "{1D9928BD-4453-4bdd-903D-E525ED17FDE5}") -Q_CLASSINFO("InterfaceID", "{99F6860E-2C5A-42ec-87F2-43396F4BE389}") -Q_CLASSINFO("EventsID", "{0A3E9F27-E4F1-45bb-9E47-63099BCCD0E3}") -//! [4] - - -//! [5] -Q_PROPERTY(int value READ value WRITE setValue) -//! [5] - - -//! [6] -public: - MyActiveX(QWidget *parent = 0) - ... - - int value() const; - -public slots: - void setValue(int v); - ... - -signals: - void valueChange(int v); - ... - -}; -//! [6] - - -//! [7] -#include <QAxBindable> -#include <QWidget> - -class MyActiveX : public QWidget, public QAxBindable -{ - Q_OBJECT -//! [7] - - -//! [8] -QAXFACTORY_BEGIN("{ad90301a-849e-4e8b-9a91-0a6dc5f6461f}", - "{a8f21901-7ff7-4f6a-b939-789620c03d83}") - QAXCLASS(MyWidget) - QAXCLASS(MyWidget2) - QAXTYPE(MySubType) -QAXFACTORY_END() -//! [8] - - -//! [9] -#include <QApplication> -#include <QAxFactory> - -int main(int argc, char *argv[]) -{ - QApplication app(argc, argv); - if (!QAxFactory::isServer()) { - // create and show main window - } - return app.exec(); -} -//! [9] - - -//! [10] -MyFactory(const QUuid &, const QUuid &); -//! [10] - - -//! [11] -HMODULE dll = LoadLibrary("myserver.dll"); -typedef HRESULT(__stdcall *DllRegisterServerProc)(); -DllRegisterServerProc DllRegisterServer = - (DllRegisterServerProc)GetProcAddress(dll, "DllRegisterServer"); - -HRESULT res = E_FAIL; -if (DllRegisterServer) - res = DllRegisterServer(); -if (res != S_OK) - // error handling -//! [11] - - //! [12] cabarc N simpleax.cab simpleax.exe simple.inf //! [12] @@ -175,89 +55,3 @@ cabarc N simpleax.cab simpleax.exe simple.inf <param name="name" value="value"> <\object> //! [14] - - -//! [15] -class MyActiveX : public QWidget -{ - Q_OBJECT - Q_CLASSINFO("Version", "2.0") - Q_CLASSINFO("ClassID", "{7a4cffd8-cbcd-4ae9-ae7e-343e1e5710df}") - Q_CLASSINFO("InterfaceID", "{6fb035bf-8019-48d8-be51-ef05427d8994}") - Q_CLASSINFO("EventsID", "{c42fffdf-6557-47c9-817a-2da2228bc29c}") - Q_CLASSINFO("Insertable", "yes") - Q_CLASSINFO("ToSuperClass", "MyActiveX") - Q_PROPERTY(...) - -public: - MyActiveX(QWidget *parent = 0); - - ... -}; -//! [15] - - -//! [16] -class MyLicensedControl : public QWidget -{ - Q_OBJECT - Q_CLASSINFO("LicenseKey", "<key string>") - ... -}; -//! [16] - - -//! [17] -class AxImpl : public QAxAggregated, public ISomeCOMInterface -{ -public: - AxImpl() {} - - long queryInterface(const QUuid &iid, void **iface); - - // IUnknown - QAXAGG_IUNKNOWN - - // ISomeCOMInterface - ... -} -//! [17] - - -//! [18] -long AxImpl::queryInterface(const QUuid &iid, void **iface) -{ - *iface = 0; - if (iid == IID_ISomeCOMInterface) - *iface = (ISomeCOMInterface *)this; - else - return E_NOINTERFACE; - - AddRef(); - return S_OK; -} -//! [18] - - -//! [19] -HRESULT AxImpl::QueryInterface(REFIID iid, void **iface) -{ - return controllingUnknown()->QueryInterface(iid, iface); -} -//! [19] - - -//! [20] -class MyActiveX : public QWidget, public QAxBindable -{ - Q_OBJECT - -public: - MyActiveX(QWidget *parent); - - QAxAggregated *createAggregate() - { - return new AxImpl(); - } -}; -//! [20] diff --git a/doc/src/snippets/code/doc_src_qcache.qdoc b/doc/src/snippets/code/doc_src_qcache.cpp index 81fa3cf..81fa3cf 100644 --- a/doc/src/snippets/code/doc_src_qcache.qdoc +++ b/doc/src/snippets/code/doc_src_qcache.cpp diff --git a/doc/src/snippets/code/doc_src_qdbusadaptors.qdoc b/doc/src/snippets/code/doc_src_qdbusadaptors.cpp index abb31a1..749e64b 100644 --- a/doc/src/snippets/code/doc_src_qdbusadaptors.qdoc +++ b/doc/src/snippets/code/doc_src_qdbusadaptors.cpp @@ -39,82 +39,82 @@ ****************************************************************************/ //! [0] - class MainApplicationAdaptor: public QDBusAbstractAdaptor - { - Q_OBJECT - Q_CLASSINFO("D-Bus Interface", "org.kde.DBus.MainApplication") - Q_PROPERTY(QString caption READ caption WRITE setCaption) - Q_PROPERTY(QString organizationName READ organizationName) - Q_PROPERTY(QString organizationDomain READ organizationDomain) - - private: - QApplication *app; - - public: - MainApplicationAdaptor(QApplication *application) - : QDBusAbstractAdaptor(application), app(application) - { - connect(application, SIGNAL(aboutToQuit()), SIGNAL(aboutToQuit())); - connect(application, SIGNAL(focusChanged(QWidget*, QWidget*)), - SLOT(focusChangedSlot(QWidget*, QWidget*))); - } - - QString caption() - { - if (app->hasMainWindow()) - return app->mainWindow()->caption(); - return QString(""); // must not return a null QString - } - - void setCaption(const QString &newCaption) - { - if (app->hasMainWindow()) - app->mainWindow()->setCaption(newCaption); - } - - QString organizationName() - { - return app->organizationName(); - } - - QString organizationDomain() - { - return app->organizationDomain(); - } - - public slots: - Q_NOREPLY void quit() - { app->quit(); } - - void reparseConfiguration() - { app->reparseConfiguration(); } - - QString mainWindowObject() - { - if (app->hasMainWindow()) - return QString("/%1/mainwindow").arg(app->applicationName()); - return QString(); - } - - void setSessionManagement(bool enable) - { - if (enable) - app->enableSessionManagement(); - else - app->disableSessionManagement(); - } - - private slots: - void focusChangedSlot(QWidget *, QWidget *now) - { - if (now == app->mainWindow()) - emit mainWindowHasFocus(); - } - - signals: - void aboutToQuit(); - void mainWindowHasFocus(); - }; +class MainApplicationAdaptor: public QDBusAbstractAdaptor +{ + Q_OBJECT + Q_CLASSINFO("D-Bus Interface", "org.kde.DBus.MainApplication") + Q_PROPERTY(QString caption READ caption WRITE setCaption) + Q_PROPERTY(QString organizationName READ organizationName) + Q_PROPERTY(QString organizationDomain READ organizationDomain) + +private: + QApplication *app; + +public: + MainApplicationAdaptor(QApplication *application) + : QDBusAbstractAdaptor(application), app(application) + { + connect(application, SIGNAL(aboutToQuit()), SIGNAL(aboutToQuit())); + connect(application, SIGNAL(focusChanged(QWidget*, QWidget*)), + SLOT(focusChangedSlot(QWidget*, QWidget*))); + } + + QString caption() + { + if (app->hasMainWindow()) + return app->mainWindow()->caption(); + return QString(""); // must not return a null QString + } + + void setCaption(const QString &newCaption) + { + if (app->hasMainWindow()) + app->mainWindow()->setCaption(newCaption); + } + + QString organizationName() + { + return app->organizationName(); + } + + QString organizationDomain() + { + return app->organizationDomain(); + } + +public slots: + Q_NOREPLY void quit() + { app->quit(); } + + void reparseConfiguration() + { app->reparseConfiguration(); } + + QString mainWindowObject() + { + if (app->hasMainWindow()) + return QString("/%1/mainwindow").arg(app->applicationName()); + return QString(); + } + + void setSessionManagement(bool enable) + { + if (enable) + app->enableSessionManagement(); + else + app->disableSessionManagement(); + } + +private slots: + void focusChangedSlot(QWidget *, QWidget *now) + { + if (now == app->mainWindow()) + emit mainWindowHasFocus(); + } + +signals: + void aboutToQuit(); + void mainWindowHasFocus(); +}; //! [0] diff --git a/doc/src/snippets/code/doc_src_qiterator.qdoc b/doc/src/snippets/code/doc_src_qiterator.cpp index 82b1bd3..82b1bd3 100644 --- a/doc/src/snippets/code/doc_src_qiterator.qdoc +++ b/doc/src/snippets/code/doc_src_qiterator.cpp diff --git a/doc/src/snippets/code/doc_src_qmake-manual.cpp b/doc/src/snippets/code/doc_src_qmake-manual.cpp new file mode 100644 index 0000000..4f60e1d --- /dev/null +++ b/doc/src/snippets/code/doc_src_qmake-manual.cpp @@ -0,0 +1,58 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [104] +// Add C includes here + +#if defined __cplusplus +// Add C++ includes here +#include <stdlib> +#include <iostream> +#include <vector> +#include <QApplication> // Qt includes +#include <QPushButton> +#include <QLabel> +#include "thirdparty/include/libmain.h" +#include "my_stable_class.h" +... +#endif +//! [104] + + diff --git a/doc/src/snippets/code/doc_src_qmake-manual.qdoc b/doc/src/snippets/code/doc_src_qmake-manual.pro index a35a3d9..ee35b77 100644 --- a/doc/src/snippets/code/doc_src_qmake-manual.qdoc +++ b/doc/src/snippets/code/doc_src_qmake-manual.pro @@ -38,569 +38,569 @@ ** ****************************************************************************/ -//! [0] +#! [0] make all -//! [0] +#! [0] -//! [1] +#! [1] CONFIG += qt thread debug -//! [1] +#! [1] -//! [2] +#! [2] CONFIG += qt QT += network xml -//! [2] +#! [2] -//! [3] +#! [3] QT = network xml # This will omit the core and gui modules. -//! [3] +#! [3] -//! [4] +#! [4] QT -= gui # Only the core module is used. -//! [4] +#! [4] -//! [5] +#! [5] CONFIG += link_pkgconfig PKGCONFIG += ogg dbus-1 -//! [5] +#! [5] -//! [6] +#! [6] LIBS += -L/usr/local/lib -lmath -//! [6] +#! [6] -//! [7] +#! [7] INCLUDEPATH = c:/msdev/include d:/stl/include -//! [7] +#! [7] -//! [8] +#! [8] qmake [mode] [options] files -//! [8] +#! [8] -//! [9] +#! [9] qmake -makefile [options] files -//! [9] +#! [9] -//! [10] +#! [10] qmake -makefile -unix -o Makefile "CONFIG+=test" test.pro -//! [10] +#! [10] -//! [11] +#! [11] qmake "CONFIG+=test" test.pro -//! [11] +#! [11] -//! [12] +#! [12] qmake -project [options] files -//! [12] +#! [12] -//! [13] +#! [13] qmake -spec macx-g++ -//! [13] +#! [13] -//! [14] +#! [14] QMAKE_LFLAGS += -F/path/to/framework/directory/ -//! [14] +#! [14] -//! [15] +#! [15] LIBS += -framework TheFramework -//! [15] +#! [15] -//! [16] +#! [16] TEMPLATE = lib CONFIG += lib_bundle -//! [16] +#! [16] -//! [17] +#! [17] FRAMEWORK_HEADERS.version = Versions FRAMEWORK_HEADERS.files = path/to/header_one.h path/to/header_two.h FRAMEWORK_HEADERS.path = Headers QMAKE_BUNDLE_DATA += FRAMEWORK_HEADERS -//! [17] +#! [17] -//! [18] +#! [18] CONFIG += x86 ppc -//! [18] +#! [18] -//! [19] +#! [19] qmake -spec macx-xcode project.pro -//! [19] +#! [19] -//! [20] +#! [20] qmake -tp vc -//! [20] +#! [20] -//! [21] +#! [21] qmake -tp vc -r -//! [21] +#! [21] -//! [22] +#! [22] CONFIG -= embed_manifest_exe -//! [22] +#! [22] -//! [23] +#! [23] CONFIG -= embed_manifest_dll -//! [23] +#! [23] -//! [24] +#! [24] make all -//! [24] +#! [24] -//! [25] +#! [25] build_pass:CONFIG(debug, debug|release) { unix: TARGET = $$join(TARGET,,,_debug) else: TARGET = $$join(TARGET,,,d) } -//! [25] +#! [25] -//! [26] +#! [26] CONFIG += qt console newstuff ... newstuff { SOURCES += new.cpp HEADERS += new.h } -//! [26] +#! [26] -//! [27] +#! [27] DEFINES += USE_MY_STUFF QT_DLL -//! [27] +#! [27] -//! [28] +#! [28] myFiles.files = path\*.png DEPLOYMENT += myFiles -//! [28] +#! [28] -//! [29] +#! [29] myFiles.files = path\file1.ext1 path2\file2.ext1 path3\* myFiles.path = \some\path\on\device someother.files = C:\additional\files\* someother.path = \myFiles\path2 DEPLOYMENT += myFiles someother -//! [29] +#! [29] -//! [30] +#! [30] DESTDIR = ../../lib -//! [30] +#! [30] -//! [31] +#! [31] DISTFILES += ../program.txt -//! [31] +#! [31] -//! [32] +#! [32] FORMS = mydialog.ui \ mywidget.ui \ myconfig.ui -//! [32] +#! [32] -//! [33] +#! [33] FORMS3 = my_uic3_dialog.ui \ my_uic3_widget.ui \ my_uic3_config.ui -//! [33] +#! [33] -//! [34] +#! [34] HEADERS = myclass.h \ login.h \ mainwindow.h -//! [34] +#! [34] -//! [35] +#! [35] INCLUDEPATH = c:/msdev/include d:/stl/include -//! [35] +#! [35] -//! [36] +#! [36] target.path += $$[QT_INSTALL_PLUGINS]/imageformats INSTALLS += target -//! [36] +#! [36] -//! [37] +#! [37] LEXSOURCES = lexer.l -//! [37] +#! [37] -//! [38] +#! [38] unix:LIBS += -L/usr/local/lib -lmath win32:LIBS += c:/mylibs/math.lib -//! [38] +#! [38] -//! [39] +#! [39] CONFIG += no_lflags_merge -//! [39] +#! [39] -//! [40] +#! [40] unix:MOC_DIR = ../myproject/tmp win32:MOC_DIR = c:/myproject/tmp -//! [40] +#! [40] -//! [41] +#! [41] unix:OBJECTS_DIR = ../myproject/tmp win32:OBJECTS_DIR = c:/myproject/tmp -//! [41] +#! [41] -//! [42] +#! [42] app { # Conditional code for 'app' template here } -//! [42] +#! [42] -//! [43] +#! [43] FRAMEWORK_HEADERS.version = Versions FRAMEWORK_HEADERS.files = path/to/header_one.h path/to/header_two.h FRAMEWORK_HEADERS.path = Headers QMAKE_BUNDLE_DATA += FRAMEWORK_HEADERS -//! [43] +#! [43] -//! [44] +#! [44] QMAKE_BUNDLE_EXTENSION = .myframework -//! [44] +#! [44] -//! [45] +#! [45] QMAKE_RESOURCE_FLAGS += -threshold 0 -compress 9 -//! [45] +#! [45] -//! [46] +#! [46] QMAKE_UIC = uic -L /path/to/plugin -//! [46] +#! [46] -//! [47] +#! [47] QT -= gui # Only the core module is used. -//! [47] +#! [47] -//! [48] +#! [48] unix:RCC_DIR = ../myproject/resources win32:RCC_DIR = c:/myproject/resources -//! [48] +#! [48] -//! [49] +#! [49] SOURCES = myclass.cpp \ login.cpp \ mainwindow.cpp -//! [49] +#! [49] -//! [50] +#! [50] SUBDIRS = kernel \ tools -//! [50] +#! [50] -//! [51] +#! [51] CONFIG += ordered -//! [51] +#! [51] -//! [52] +#! [52] TEMPLATE = app TARGET = myapp SOURCES = main.cpp -//! [52] +#! [52] -//! [53] +#! [53] TEMPLATE = lib SOURCES = main.cpp TARGET = mylib -//! [53] +#! [53] -//! [54] +#! [54] unix:UI_DIR = ../myproject/ui win32:UI_DIR = c:/myproject/ui -//! [54] +#! [54] -//! [55] +#! [55] unix:UI_HEADERS_DIR = ../myproject/ui/include win32:UI_HEADERS_DIR = c:/myproject/ui/include -//! [55] +#! [55] -//! [56] +#! [56] unix:UI_SOURCES_DIR = ../myproject/ui/src win32:UI_SOURCES_DIR = c:/myproject/ui/src -//! [56] +#! [56] -//! [57] +#! [57] VERSION = 1.2.3 -//! [57] +#! [57] -//! [58] +#! [58] YACCSOURCES = moc.y -//! [58] +#! [58] -//! [59] +#! [59] FILE = /etc/passwd FILENAME = $$basename(FILE) #passwd -//! [59] +#! [59] -//! [60] +#! [60] CONFIG = debug CONFIG += release CONFIG(release, debug|release):message(Release build!) #will print CONFIG(debug, debug|release):message(Debug build!) #no print -//! [60] +#! [60] -//! [61] +#! [61] contains( drivers, network ) { # drivers contains 'network' message( "Configuring for network build..." ) HEADERS += network.h SOURCES += network.cpp } -//! [61] +#! [61] -//! [62] +#! [62] error(An error has occurred in the configuration process.) -//! [62] +#! [62] -//! [63] +#! [63] exists( $(QTDIR)/lib/libqt-mt* ) { message( "Configuring for multi-threaded Qt..." ) CONFIG += thread } -//! [63] +#! [63] -//! [64] +#! [64] MY_VAR = one two three four MY_VAR2 = $$join(MY_VAR, " -L", -L) -Lfive MY_VAR3 = $$member(MY_VAR, 2) $$find(MY_VAR, t.*) -//! [64] +#! [64] -//! [65] +#! [65] LIST = 1 2 3 for(a, LIST):exists(file.$${a}):message(I see a file.$${a}!) -//! [65] +#! [65] -//! [66] +#! [66] include( shared.pri ) OPTIONS = standard custom !include( options.pri ) { message( "No custom build options specified" ) OPTIONS -= custom } -//! [66] +#! [66] -//! [67] +#! [67] isEmpty( CONFIG ) { CONFIG += qt warn_on debug } -//! [67] +#! [67] -//! [68] +#! [68] message( "This is a message" ) -//! [68] +#! [68] -//! [69] +#! [69] !build_pass:message( "This is a message" ) -//! [69] +#! [69] -//! [70] +#! [70] This is a test. -//! [70] +#! [70] -//! [71] +#! [71] system(ls /bin):HAS_BIN=FALSE -//! [71] +#! [71] -//! [72] +#! [72] UNAME = $$system(uname -s) contains( UNAME, [lL]inux ):message( This looks like Linux ($$UNAME) to me ) -//! [72] +#! [72] -//! [73] +#! [73] ARGS = 1 2 3 2 5 1 ARGS = $$unique(ARGS) #1 2 3 5 -//! [73] +#! [73] -//! [74] +#! [74] qmake -set VARIABLE VALUE -//! [74] +#! [74] -//! [75] +#! [75] qmake -query VARIABLE qmake -query #queries all current VARIABLE/VALUE pairs.. -//! [75] +#! [75] -//! [76] +#! [76] qmake -query "1.06a/VARIABLE" -//! [76] +#! [76] -//! [77] +#! [77] qmake -query "QT_INSTALL_PREFIX" -//! [77] +#! [77] -//! [78] +#! [78] QMAKE_VERS = $$[QMAKE_VERSION] -//! [78] +#! [78] -//! [79] +#! [79] documentation.path = /usr/local/program/doc documentation.files = docs/* -//! [79] +#! [79] -//! [80] +#! [80] INSTALLS += documentation -//! [80] +#! [80] -//! [81] +#! [81] unix:documentation.extra = create_docs; mv master.doc toc.doc -//! [81] +#! [81] -//! [82] +#! [82] target.path = /usr/local/myprogram INSTALLS += target -//! [82] +#! [82] -//! [83] +#! [83] CONFIG += create_prl -//! [83] +#! [83] -//! [84] +#! [84] CONFIG += link_prl -//! [84] +#! [84] -//! [85] +#! [85] QMAKE_EXT_MOC = .mymoc -//! [85] +#! [85] -//! [86] +#! [86] mytarget.target = .buildfile mytarget.commands = touch $$mytarget.target mytarget.depends = mytarget2 mytarget2.commands = @echo Building $$mytarget.target -//! [86] +#! [86] -//! [87] +#! [87] QMAKE_EXTRA_TARGETS += mytarget mytarget2 -//! [87] +#! [87] -//! [88] +#! [88] new_moc.output = moc_${QMAKE_FILE_BASE}.cpp new_moc.commands = moc ${QMAKE_FILE_NAME} -o ${QMAKE_FILE_OUT} new_moc.depend_command = g++ -E -M ${QMAKE_FILE_NAME} | sed "s,^.*: ,," new_moc.input = NEW_HEADERS QMAKE_EXTRA_COMPILERS += new_moc -//! [88] +#! [88] -//! [89] +#! [89] TARGET = myapp -//! [89] +#! [89] -//! [90] +#! [90] DEFINES += QT_DLL -//! [90] +#! [90] -//! [91] +#! [91] DEFINES -= QT_DLL -//! [91] +#! [91] -//! [92] +#! [92] DEFINES *= QT_DLL -//! [92] +#! [92] -//! [93] +#! [93] DEFINES ~= s/QT_[DT].+/QT -//! [93] +#! [93] -//! [94] +#! [94] EVERYTHING = $$SOURCES $$HEADERS message("The project contains the following files:") message($$EVERYTHING) -//! [94] +#! [94] -//! [95] +#! [95] win32:DEFINES += QT_DLL -//! [95] +#! [95] -//! [96] +#! [96] win32:xml { message(Building for Windows) SOURCES += xmlhandler_win.cpp @@ -609,146 +609,128 @@ win32:xml { } else { message("Unknown configuration") } -//! [96] +#! [96] -//! [97] +#! [97] MY_VARIABLE = value -//! [97] +#! [97] -//! [98] +#! [98] MY_DEFINES = $$DEFINES -//! [98] +#! [98] -//! [99] +#! [99] MY_DEFINES = $${DEFINES} -//! [99] +#! [99] -//! [100] +#! [100] TARGET = myproject_$${TEMPLATE} -//! [100] +#! [100] -//! [101] +#! [101] target.path = $$[QT_INSTALL_PLUGINS]/designer INSTALLS += target -//! [101] +#! [101] -//! [102] +#! [102] defineReplace(functionName){ #function code } -//! [102] +#! [102] -//! [103] +#! [103] CONFIG += myfeatures -//! [103] - - -//! [104] -// Add C includes here - -#if defined __cplusplus -// Add C++ includes here -#include <stdlib> -#include <iostream> -#include <vector> -#include <QApplication> // Qt includes -#include <QPushButton> -#include <QLabel> -#include "thirdparty/include/libmain.h" -#include "my_stable_class.h" -... -#endif -//! [104] +#! [103] -//! [105] +#! [105] PRECOMPILED_HEADER = stable.h -//! [105] +#! [105] -//! [106] +#! [106] precompile_header:!isEmpty(PRECOMPILED_HEADER) { DEFINES += USING_PCH } -//! [106] +#! [106] -//! [107] +#! [107] PRECOMPILED_HEADER = window.h SOURCES = window.cpp -//! [107] +#! [107] -//! [108] +#! [108] SOURCES += hello.cpp -//! [108] +#! [108] -//! [109] +#! [109] SOURCES += hello.cpp SOURCES += main.cpp -//! [109] +#! [109] -//! [110] +#! [110] SOURCES = hello.cpp \ main.cpp -//! [110] +#! [110] -//! [111] +#! [111] HEADERS += hello.h SOURCES += hello.cpp SOURCES += main.cpp -//! [111] +#! [111] -//! [112] +#! [112] TARGET = helloworld -//! [112] +#! [112] -//! [113] +#! [113] CONFIG += qt HEADERS += hello.h SOURCES += hello.cpp SOURCES += main.cpp -//! [113] +#! [113] -//! [114] +#! [114] qmake -o Makefile hello.pro -//! [114] +#! [114] -//! [115] +#! [115] qmake -tp vc hello.pro -//! [115] +#! [115] -//! [116] +#! [116] CONFIG += qt debug HEADERS += hello.h SOURCES += hello.cpp SOURCES += main.cpp -//! [116] +#! [116] -//! [117] +#! [117] win32 { SOURCES += hellowin.cpp } -//! [117] +#! [117] -//! [118] +#! [118] CONFIG += qt debug HEADERS += hello.h SOURCES += hello.cpp @@ -759,17 +741,17 @@ win32 { unix { SOURCES += hellounix.cpp } -//! [118] +#! [118] -//! [119] +#! [119] !exists( main.cpp ) { error( "No main.cpp file found" ) } -//! [119] +#! [119] -//! [120] +#! [120] CONFIG += qt debug HEADERS += hello.h SOURCES += hello.cpp @@ -783,19 +765,19 @@ unix { !exists( main.cpp ) { error( "No main.cpp file found" ) } -//! [120] +#! [120] -//! [121] +#! [121] win32 { debug { CONFIG += console } } -//! [121] +#! [121] -//! [122] +#! [122] CONFIG += qt debug HEADERS += hello.h SOURCES += hello.cpp @@ -812,10 +794,10 @@ unix { win32:debug { CONFIG += console } -//! [122] +#! [122] -//! [123] +#! [123] TEMPLATE = app DESTDIR = c:/helloapp HEADERS += hello.h @@ -823,32 +805,32 @@ SOURCES += hello.cpp SOURCES += main.cpp DEFINES += QT_DLL CONFIG += qt warn_on release -//! [123] +#! [123] -//! [124] +#! [124] make all -//! [124] +#! [124] -//! [125] +#! [125] make -//! [125] +#! [125] -//! [126] +#! [126] make install -//! [126] +#! [126] -//! [127] +#! [127] CONFIG(debug, debug|release) { mac: TARGET = $$join(TARGET,,,_debug) win32: TARGET = $$join(TARGET,,d) } -//! [127] +#! [127] -//! [128] +#! [128] customplugin.files = customimageplugin.dll customplugin.files += c:\myplugins\othercustomimageplugin.dll customplugin.path = imageformats @@ -857,50 +839,50 @@ dynamiclibrary.path = \sys\bin globalplugin.files = someglobalimageplugin.dll globalplugin.path = \resource\qt\plugins\imageformats DEPLOYMENT += customplugin dynamiclibrary globalplugin -//! [128] +#! [128] -//! [129] +#! [129] TARGET.EPOCALLOWDLLDATA = 1 -//! [129] +#! [129] -//! [130] +#! [130] TARGET.EPOCHEAPSIZE = 10000 10000000 TARGET.EPOCSTACKSIZE = 0x8000 -//! [130] +#! [130] -//! [131] +#! [131] QMAKE_CXXFLAGS.CW += -O2 QMAKE_CXXFLAGS.ARMCC += -O0 -//! [131] +#! [131] -//! [132] +#! [132] TARGET.UID2 = 0x00000001 TARGET.UID3 = 0x00000002 TARGET.SID = 0x00000003 TARGET.VID = 0x00000004 -//! [132] +#! [132] -//! [133] +#! [133] TARGET.CAPABILITY += AllFiles -//! [133] +#! [133] -//! [134] +#! [134] TARGET.CAPABILITY = ALL -TCB -DRM -AllFiles -//! [134] +#! [134] -//! [135] +#! [135] TARGET.EPOCHEAPSIZE = 10000 10000000 -//! [135] +#! [135] -//! [136] +#! [136] TARGET.EPOCSTACKSIZE = 0x8000 -//! [136] +#! [136] -//! [137] +#! [137] MMP_RULES += "DEFFILE hello.def" -//! [137] +#! [137] -//! [138] +#! [138] myBlock = \ "START RESOURCE foo.rss" \ "TARGET bar" \ @@ -911,37 +893,37 @@ myBlock = \ "END" MMP_RULES += myBlock -//! [138] +#! [138] -//! [139] +#! [139] myIfdefBlock = \ "$${LITERAL_HASH}ifdef WINSCW" \ "DEFFILE hello_winscw.def" \ "$${LITERAL_HASH}endif" MMP_RULES += myIfdefBlock -//! [139] +#! [139] -//! [140] +#! [140] somelib.files = somelib.dll somelib.path = \sys\bin somelib.pkg_prerules = "(0x12345678), 2, 2, 0, {\"Some Package\"}" \ "(0x87654321), 1, *, * ~ 2, 2, 0, {\"Some Other Package\"}" justdep.pkg_prerules = "(0xAAAABBBB), 0, 2, 0, {\"My Framework\"}" DEPLOYMENT += somelib justdep -//! [140] +#! [140] -//! [141] +#! [141] default_deployment.pkg_prerules -= pkg_platform_dependencies my_deployment.pkg_prerules = "[0x11223344],0,0,0,{\"SomeSpecificDeviceID\"}" DEPLOYMENT += my_deployment -//! [141] +#! [141] -//! [142] +#! [142] DEPLOYMENT_PLUGIN += qjpeg -//! [142] +#! [142] -//! [143] +#! [143] myextension = \ "start extension myextension" \ "$${LITERAL_HASH}if defined(WINSCW)" \ @@ -950,28 +932,28 @@ myextension = \ "option MYOPTION bar" \ "end" BLD_INF_RULES.prj_extensions += myextension -//! [143] +#! [143] -//! [144] +#! [144] RSS_RULES += "hidden = KAppIsHidden;" -//! [144] +#! [144] -//! [145] +#! [145] myrssrules = \ "hidden = KAppIsHidden;" \ "launch = KAppLaunchInBackground;" \ RSS_RULES += myrssrules -//! [145] +#! [145] -//! [146] +#! [146] DEPLOYMENT.installer_header = 0x12345678 -//! [146] +#! [146] -//! [147] +#! [147] DEPLOYMENT.installer_header = "$${LITERAL_HASH}{\"My Application Installer\"},(0x12345678),1,0,0" -//! [147] +#! [147] -//! [148] +#! [148] # Set conditional libraries LIB.MARM = "LIBRARY myarm.lib" LIB.WINSCW = "LIBRARY mywinscw.lib" @@ -982,62 +964,62 @@ MYCONDITIONS = MARM WINSCW MYVARIABLES = LIB addMMPRules(MYCONDITIONS, MYVARIABLES) -//! [148] +#! [148] -//! [149] +#! [149] SUBDIRS += my_executable my_library my_executable.subdir = app my_executable.depends = my_library my_library.subdir = lib -//! [149] +#! [149] -//! [150] +#! [150] symbian { SUBDIRS += emulator_dll emulator_dll.condition = WINSCW } -//! [150] +#! [150] -//! [151] +#! [151] RSS_RULES.service_list += "uid = 0x12345678; datatype_list = \{\}; opaque_data = r_my_icon;" RSS_RULES.footer +="RESOURCE CAPTION_AND_ICON_INFO r_my_icon \{ icon_file =\"$$PWD/my_icon.svg\"; \}" -//! [151] +#! [151] -//! [152] +#! [152] my_exports = \ "foo.h /epoc32/include/mylib/foo.h" \ "bar.h /epoc32/include/mylib/bar.h" BLD_INF_RULES.prj_exports += my_exports -//! [152] +#! [152] -//! [153] +#! [153] my_note.pkg_postrules.installer = "\"myinstallnote.txt\" - \"\", FILETEXT, TEXTCONTINUE" DEPLOYMENT += my_note -//! [153] +#! [153] -//! [154] +#! [154] DEPLOYMENT -= default_bin_deployment default_resource_deployment default_reg_deployment -//! [154] +#! [154] -//! [155] +#! [155] default_bin_deployment.flags += FILERUN RUNINSTALL dep_note.files = install_note.txt dep_note.flags = FILETEXT TEXTEXIT DEPLOYMENT += dep_note -//! [155] +#! [155] -//! [156] +#! [156] DEPLOYMENT.display_name = My Qt App -//! [156] +#! [156] -//! [157] +#! [157] packagesExist(sqlite3 QtNetwork QtDeclarative) { DEFINES += USE_FANCY_UI } -//! [157] +#! [157] -//! [158] +#! [158] #ifdef USE_FANCY_UI // Use the fancy UI, as we have extra packages available #endif -//! [158] +#! [158] diff --git a/doc/src/snippets/code/doc_src_qnamespace.cpp b/doc/src/snippets/code/doc_src_qnamespace.cpp new file mode 100644 index 0000000..c512862 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qnamespace.cpp @@ -0,0 +1,59 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [1] +enum CustomEventPriority +{ + // An important event + ImportantEventPriority = Qt::HighEventPriority, + + // A more important event + MoreImportantEventPriority = ImportantEventPriority + 1, + + // A critical event + CriticalEventPriority = 100 * MoreImportantEventPriority, + + // Not that important + StatusEventPriority = Qt::LowEventPriority, + + // These are less important than Status events + IdleProcessingDoneEventPriority = StatusEventPriority - 1 +}; +//! [1] diff --git a/doc/src/snippets/code/doc_src_qnamespace.qdoc b/doc/src/snippets/code/doc_src_qnamespace.qdoc index a1bd0b7..6b5ce6a 100644 --- a/doc/src/snippets/code/doc_src_qnamespace.qdoc +++ b/doc/src/snippets/code/doc_src_qnamespace.qdoc @@ -41,24 +41,3 @@ //! [0] QObject::connect: Cannot queue arguments of type 'MyType' //! [0] - - -//! [1] -enum CustomEventPriority -{ - // An important event - ImportantEventPriority = Qt::HighEventPriority, - - // A more important event - MoreImportantEventPriority = ImportantEventPriority + 1, - - // A critical event - CriticalEventPriority = 100 * MoreImportantEventPriority, - - // Not that important - StatusEventPriority = Qt::LowEventPriority, - - // These are less important than Status events - IdleProcessingDoneEventPriority = StatusEventPriority - 1 -}; -//! [1] diff --git a/doc/src/snippets/code/doc_src_qpair.qdoc b/doc/src/snippets/code/doc_src_qpair.cpp index a9a061e..a9a061e 100644 --- a/doc/src/snippets/code/doc_src_qpair.qdoc +++ b/doc/src/snippets/code/doc_src_qpair.cpp diff --git a/doc/src/snippets/code/doc_src_qplugin.qdoc b/doc/src/snippets/code/doc_src_qplugin.cpp index fdacc08..fdacc08 100644 --- a/doc/src/snippets/code/doc_src_qplugin.qdoc +++ b/doc/src/snippets/code/doc_src_qplugin.cpp diff --git a/doc/src/snippets/code/doc_src_qplugin.pro b/doc/src/snippets/code/doc_src_qplugin.pro new file mode 100644 index 0000000..f3444e2 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qplugin.pro @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [3] +TEMPLATE = app +QTPLUGIN += qjpeg qgif qmng # image formats +#! [3] diff --git a/doc/src/snippets/code/doc_src_qset.qdoc b/doc/src/snippets/code/doc_src_qset.cpp index 4a4953d..4a4953d 100644 --- a/doc/src/snippets/code/doc_src_qset.qdoc +++ b/doc/src/snippets/code/doc_src_qset.cpp diff --git a/doc/src/snippets/code/doc_src_qsignalspy.qdoc b/doc/src/snippets/code/doc_src_qsignalspy.cpp index 12462e2..12462e2 100644 --- a/doc/src/snippets/code/doc_src_qsignalspy.qdoc +++ b/doc/src/snippets/code/doc_src_qsignalspy.cpp diff --git a/doc/src/snippets/code/doc_src_qt3support.qdoc b/doc/src/snippets/code/doc_src_qt3support.cpp index 9e0f682..196efd4 100644 --- a/doc/src/snippets/code/doc_src_qt3support.qdoc +++ b/doc/src/snippets/code/doc_src_qt3support.cpp @@ -41,8 +41,3 @@ //! [0] #include <Qt3Support> //! [0] - - -//! [1] -QT += qt3support -//! [1] diff --git a/doc/src/snippets/code/doc_src_qt3support.pro b/doc/src/snippets/code/doc_src_qt3support.pro new file mode 100644 index 0000000..20fcc14 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qt3support.pro @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [1] +QT += qt3support +#! [1] diff --git a/doc/src/snippets/code/doc_src_qt3to4.cpp b/doc/src/snippets/code/doc_src_qt3to4.cpp new file mode 100644 index 0000000..d8eb5b4 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qt3to4.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [2] +using namespace Qt; +//! [2] diff --git a/doc/src/snippets/code/doc_src_qt4-accessibility.qdoc b/doc/src/snippets/code/doc_src_qt4-accessibility.cpp index efbbc5a..efbbc5a 100644 --- a/doc/src/snippets/code/doc_src_qt4-accessibility.qdoc +++ b/doc/src/snippets/code/doc_src_qt4-accessibility.cpp diff --git a/doc/src/snippets/code/doc_src_qt4-arthur.qdoc b/doc/src/snippets/code/doc_src_qt4-arthur.cpp index 6268309..6268309 100644 --- a/doc/src/snippets/code/doc_src_qt4-arthur.qdoc +++ b/doc/src/snippets/code/doc_src_qt4-arthur.cpp diff --git a/doc/src/snippets/code/doc_src_qt4-intro.qdoc b/doc/src/snippets/code/doc_src_qt4-intro.cpp index 45da7d0..76ed4a5 100644 --- a/doc/src/snippets/code/doc_src_qt4-intro.qdoc +++ b/doc/src/snippets/code/doc_src_qt4-intro.cpp @@ -38,21 +38,6 @@ ** ****************************************************************************/ -//! [0] -QT -= gui -//! [0] - - -//! [1] -QT += network opengl sql qt3support -//! [1] - - -//! [2] -CONFIG += uic3 -//! [2] - - //! [3] #include <QClassName> //! [3] @@ -119,23 +104,3 @@ safeLabel->setText("Hello world!"); delete label; // safeLabel is now 0, whereas label is a dangling pointer //! [12] - - -//! [13] -QT += qt3support -//! [13] - - -//! [14] -DEFINES += QT3_SUPPORT -//! [14] - - -//! [15] -DEFINES += QT3_SUPPORT_WARNINGS -//! [15] - - -//! [16] -DEFINES += QT3_SUPPORT -//! [16] diff --git a/doc/src/snippets/code/doc_src_qt4-intro.pro b/doc/src/snippets/code/doc_src_qt4-intro.pro new file mode 100644 index 0000000..40853b3 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qt4-intro.pro @@ -0,0 +1,73 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [0] +QT -= gui +#! [0] + + +#! [1] +QT += network opengl sql qt3support +#! [1] + + +#! [2] +CONFIG += uic3 +#! [2] + + +#! [13] +QT += qt3support +#! [13] + + +#! [14] +DEFINES += QT3_SUPPORT +#! [14] + + +#! [15] +DEFINES += QT3_SUPPORT_WARNINGS +#! [15] + + +#! [16] +DEFINES += QT3_SUPPORT +#! [16] diff --git a/doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc b/doc/src/snippets/code/doc_src_qt4-mainwindow.cpp index d0c758e..d0c758e 100644 --- a/doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc +++ b/doc/src/snippets/code/doc_src_qt4-mainwindow.cpp diff --git a/doc/src/snippets/code/doc_src_qt4-sql.qdoc b/doc/src/snippets/code/doc_src_qt4-sql.cpp index cbcfb2d..cbcfb2d 100644 --- a/doc/src/snippets/code/doc_src_qt4-sql.qdoc +++ b/doc/src/snippets/code/doc_src_qt4-sql.cpp diff --git a/doc/src/snippets/code/doc_src_qt4-styles.qdoc b/doc/src/snippets/code/doc_src_qt4-styles.cpp index effe3cd..effe3cd 100644 --- a/doc/src/snippets/code/doc_src_qt4-styles.qdoc +++ b/doc/src/snippets/code/doc_src_qt4-styles.cpp diff --git a/doc/src/snippets/code/doc_src_qt4-tulip.qdoc b/doc/src/snippets/code/doc_src_qt4-tulip.cpp index 83b1210..83b1210 100644 --- a/doc/src/snippets/code/doc_src_qt4-tulip.qdoc +++ b/doc/src/snippets/code/doc_src_qt4-tulip.cpp diff --git a/doc/src/snippets/code/doc_src_qtcore.qdoc b/doc/src/snippets/code/doc_src_qtcore.cpp index 35916ea..35916ea 100644 --- a/doc/src/snippets/code/doc_src_qtcore.qdoc +++ b/doc/src/snippets/code/doc_src_qtcore.cpp diff --git a/doc/src/snippets/code/doc_src_qtdbus.qdoc b/doc/src/snippets/code/doc_src_qtdbus.cpp index 20ff513..2143b5b 100644 --- a/doc/src/snippets/code/doc_src_qtdbus.qdoc +++ b/doc/src/snippets/code/doc_src_qtdbus.cpp @@ -41,8 +41,3 @@ //! [0] #include <QtDBus> //! [0] - - -//! [1] -QT += dbus -//! [1] diff --git a/doc/src/snippets/code/doc_src_qtdbus.pro b/doc/src/snippets/code/doc_src_qtdbus.pro new file mode 100644 index 0000000..6607d7d --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtdbus.pro @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [1] +QT += dbus +#! [1] diff --git a/doc/src/snippets/code/doc_src_qtdesigner.qdoc b/doc/src/snippets/code/doc_src_qtdesigner.cpp index a37b77f..562002e 100644 --- a/doc/src/snippets/code/doc_src_qtdesigner.qdoc +++ b/doc/src/snippets/code/doc_src_qtdesigner.cpp @@ -43,11 +43,6 @@ //! [0] -//! [1] -CONFIG += designer -//! [1] - - //! [2] QDesignerMemberSheetExtension *memberSheet = 0; QExtensionManager manager = formEditor->extensionManager(); diff --git a/doc/src/snippets/code/doc_src_qtdesigner.pro b/doc/src/snippets/code/doc_src_qtdesigner.pro new file mode 100644 index 0000000..dc962ef --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtdesigner.pro @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [1] +CONFIG += designer +#! [1] diff --git a/doc/src/snippets/code/doc_src_qtestevent.qdoc b/doc/src/snippets/code/doc_src_qtestevent.cpp index fd1c819..fd1c819 100644 --- a/doc/src/snippets/code/doc_src_qtestevent.qdoc +++ b/doc/src/snippets/code/doc_src_qtestevent.cpp diff --git a/doc/src/snippets/code/doc_src_qtestlib.cpp b/doc/src/snippets/code/doc_src_qtestlib.cpp new file mode 100644 index 0000000..bd98807 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtestlib.cpp @@ -0,0 +1,88 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +class MyFirstTest: public QObject +{ + Q_OBJECT +private slots: + void initTestCase() + { qDebug("called before everything else"); } + void myFirstTest() + { QVERIFY(1 == 1); } + void mySecondTest() + { QVERIFY(1 != 2); } + void cleanupTestCase() + { qDebug("called after myFirstTest and mySecondTest"); } +}; +//! [0] + + +//! [8] +void TestQString::toUpper() +{ + QString str = "Hello"; + QVERIFY(str.toUpper() == "HELLO"); +} +//! [8] + + +//! [11] +QCOMPARE(QString("hello").toUpper(), QString("HELLO")); +QCOMPARE(QString("Hello").toUpper(), QString("HELLO")); +QCOMPARE(QString("HellO").toUpper(), QString("HELLO")); +QCOMPARE(QString("HELLO").toUpper(), QString("HELLO")); +//! [11] + +//! [12] +class MyFirstBenchmark: public QObject +{ + Q_OBJECT +private slots: + void myFirstBenchmark() + { + QString string1; + QString string2; + QBENCHMARK { + string1.localeAwareCompare(string2); + } + } +}; +//! [12] diff --git a/doc/src/snippets/code/doc_src_qtestlib.pro b/doc/src/snippets/code/doc_src_qtestlib.pro new file mode 100644 index 0000000..a8fc56a --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtestlib.pro @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [1] +QT += testlib +#! [1] diff --git a/doc/src/snippets/code/doc_src_qtestlib.qdoc b/doc/src/snippets/code/doc_src_qtestlib.qdoc index 80b7d92..92d528e 100644 --- a/doc/src/snippets/code/doc_src_qtestlib.qdoc +++ b/doc/src/snippets/code/doc_src_qtestlib.qdoc @@ -38,28 +38,6 @@ ** ****************************************************************************/ -//! [0] -class MyFirstTest: public QObject -{ - Q_OBJECT -private slots: - void initTestCase() - { qDebug("called before everything else"); } - void myFirstTest() - { QVERIFY(1 == 1); } - void mySecondTest() - { QVERIFY(1 != 2); } - void cleanupTestCase() - { qDebug("called after myFirstTest and mySecondTest"); } -}; -//! [0] - - -//! [1] -QT += testlib -//! [1] - - //! [2] testname [options] [testfunctions[:testdata]]... //! [2] @@ -91,15 +69,6 @@ set LIB=C:\Program Files\Windows CE Tools\wce500\Windows Mobile 5.0 Pocket PC SD //! [7] -//! [8] -void TestQString::toUpper() -{ - QString str = "Hello"; - QVERIFY(str.toUpper() == "HELLO"); -} -//! [8] - - //! [9] /myTestDirectory$ qmake -project "CONFIG += qtestlib" /myTestDirectory$ qmake @@ -116,27 +85,3 @@ PASS : TestQString::cleanupTestCase() Totals: 3 passed, 0 failed, 0 skipped ********* Finished testing of TestQString ********* //! [10] - - -//! [11] -QCOMPARE(QString("hello").toUpper(), QString("HELLO")); -QCOMPARE(QString("Hello").toUpper(), QString("HELLO")); -QCOMPARE(QString("HellO").toUpper(), QString("HELLO")); -QCOMPARE(QString("HELLO").toUpper(), QString("HELLO")); -//! [11] - -//! [12] -class MyFirstBenchmark: public QObject -{ - Q_OBJECT -private slots: - void myFirstBenchmark() - { - QString string1; - QString string2; - QBENCHMARK { - string1.localeAwareCompare(string2); - } - } -}; -//! [12] diff --git a/doc/src/snippets/code/doc_src_qtgui.qdoc b/doc/src/snippets/code/doc_src_qtgui.pro index 370529a..dd3405c 100644 --- a/doc/src/snippets/code/doc_src_qtgui.qdoc +++ b/doc/src/snippets/code/doc_src_qtgui.pro @@ -38,6 +38,6 @@ ** ****************************************************************************/ -//! [0] +#! [0] #include <QtGui> -//! [0] +#! [0] diff --git a/doc/src/snippets/code/doc_src_qthelp.cpp b/doc/src/snippets/code/doc_src_qthelp.cpp new file mode 100644 index 0000000..2825738 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qthelp.cpp @@ -0,0 +1,63 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +#include <QtHelp> +//! [0] + +//! [6] +QHelpEngineCore helpEngine("mycollection.qhc"); +... + +// get all file references for the identifier +QMap<QString, QUrl> links = + helpEngine.linksForIdentifier(QLatin1String("MyDialog::ChangeButton")); + +// If help is available for this keyword, get the help data +// of the first file reference. +if (links.count()) { + QByteArray helpData = helpEngine->fileData(links.constBegin().value()); + // show the documentation to the user + if (!helpData.isEmpty()) + displayHelp(helpData); +} +//! [6] + + diff --git a/doc/src/snippets/code/doc_src_qthelp.qdoc b/doc/src/snippets/code/doc_src_qthelp.qdoc index 4ad2100..ff25d19 100644 --- a/doc/src/snippets/code/doc_src_qthelp.qdoc +++ b/doc/src/snippets/code/doc_src_qthelp.qdoc @@ -38,11 +38,6 @@ ** ****************************************************************************/ -//! [0] -#include <QtHelp> -//! [0] - - //! [1] CONFIG += help //! [1] @@ -87,25 +82,6 @@ qcollectiongenerator mycollection.qhcp -o mycollection.qhc //! [5] -//! [6] -QHelpEngineCore helpEngine("mycollection.qhc"); -... - -// get all file references for the identifier -QMap<QString, QUrl> links = - helpEngine.linksForIdentifier(QLatin1String("MyDialog::ChangeButton")); - -// If help is available for this keyword, get the help data -// of the first file reference. -if (links.count()) { - QByteArray helpData = helpEngine->fileData(links.constBegin().value()); - // show the documentation to the user - if (!helpData.isEmpty()) - displayHelp(helpData); -} -//! [6] - - //! [7] <?xml version="1.0" encoding="UTF-8"?> <QtHelpProject version="1.0"> diff --git a/doc/src/snippets/code/doc_src_qtmultimedia.qdoc b/doc/src/snippets/code/doc_src_qtmultimedia.cpp index 76fb9cd..3f25c11 100644 --- a/doc/src/snippets/code/doc_src_qtmultimedia.qdoc +++ b/doc/src/snippets/code/doc_src_qtmultimedia.cpp @@ -38,11 +38,6 @@ ** ****************************************************************************/ -//! [0] -QT += multimedia -//! [0] - - //! [1] #include <QtMultimedia> //! [1] diff --git a/doc/src/snippets/code/doc_src_qtmultimedia.pro b/doc/src/snippets/code/doc_src_qtmultimedia.pro new file mode 100644 index 0000000..b23c994 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtmultimedia.pro @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [0] +QT += multimedia +#! [0] diff --git a/doc/src/snippets/code/doc_src_qtnetwork.qdoc b/doc/src/snippets/code/doc_src_qtnetwork.cpp index 42d1808..7100f1a 100644 --- a/doc/src/snippets/code/doc_src_qtnetwork.qdoc +++ b/doc/src/snippets/code/doc_src_qtnetwork.cpp @@ -38,11 +38,6 @@ ** ****************************************************************************/ -//! [0] -QT += network -//! [0] - - //! [1] #include <QtNetwork> //! [1] diff --git a/doc/src/snippets/code/doc_src_qtnetwork.pro b/doc/src/snippets/code/doc_src_qtnetwork.pro new file mode 100644 index 0000000..f6c3a5a --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtnetwork.pro @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [0] +QT += network +#! [0] diff --git a/doc/src/snippets/code/doc_src_qtopengl.qdoc b/doc/src/snippets/code/doc_src_qtopengl.cpp index 555d571..088b31b 100644 --- a/doc/src/snippets/code/doc_src_qtopengl.qdoc +++ b/doc/src/snippets/code/doc_src_qtopengl.cpp @@ -41,8 +41,3 @@ //! [0] #include <QtOpenGL> //! [0] - - -//! [1] -QT += opengl -//! [1] diff --git a/doc/src/snippets/code/doc_src_qtopengl.pro b/doc/src/snippets/code/doc_src_qtopengl.pro new file mode 100644 index 0000000..97fbf28 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtopengl.pro @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [1] +QT += opengl +#! [1] diff --git a/doc/src/snippets/code/doc_src_qtscript.cpp b/doc/src/snippets/code/doc_src_qtscript.cpp new file mode 100644 index 0000000..de82029 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtscript.cpp @@ -0,0 +1,568 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +#include <QtScript> +//! [0] + +//! [13] +Q_PROPERTY(bool enabled READ enabled WRITE setEnabled) +//! [13] + +//! [18] +QScriptValue myQObjectConstructor(QScriptContext *context, QScriptEngine *engine) +{ + // let the engine manage the new object's lifetime. + return engine->newQObject(new MyQObject(), QScriptEngine::ScriptOwnership); +} +//! [18] + + +//! [19] +class MyObject : public QObject +{ + Q_OBJECT + +public: + MyObject( ... ); + + void aNonScriptableFunction(); + +public slots: // these functions (slots) will be available in QtScript + void calculate( ... ); + void setEnabled( bool enabled ); + bool isEnabled() const; + +private: + .... + +}; +//! [19] + + +//! [20] +class MyObject : public QObject +{ + Q_OBJECT + + public: + Q_INVOKABLE void thisMethodIsInvokableInQtScript(); + void thisMethodIsNotInvokableInQtScript(); + + ... +}; +//! [20] + + +//! [23] +class MyObject : public QObject +{ + Q_OBJECT + // define the enabled property + Q_PROPERTY( bool enabled WRITE setEnabled READ isEnabled ) + +public: + MyObject( ... ); + + void aNonScriptableFunction(); + +public slots: // these functions (slots) will be available in QtScript + void calculate( ... ); + void setEnabled( bool enabled ); + bool isEnabled() const; + +private: + .... + +}; +//! [23] + + +//! [24] +Q_PROPERTY(int nonScriptableProperty READ foo WRITE bar SCRIPTABLE false) +//! [24] + + +//! [25] +class MyObject : public QObject +{ + Q_OBJECT + // define the enabled property + Q_PROPERTY( bool enabled WRITE setEnabled READ isEnabled ) + +public: + MyObject( ... ); + + void aNonScriptableFunction(); + +public slots: // these functions (slots) will be available in QtScript + void calculate( ... ); + void setEnabled( bool enabled ); + bool isEnabled() const; + +signals: // the signals + void enabledChanged( bool newState ); + +private: + .... + +}; +//! [25] + + +//! [34] +QScriptValue Person_ctor(QScriptContext *context, QScriptEngine *engine) +{ + QString name = context->argument(0).toString(); + context->thisObject().setProperty("name", name); + return engine->undefinedValue(); +} +//! [34] + + +//! [35] +QScriptValue Person_prototype_toString(QScriptContext *context, QScriptEngine *engine) +{ + QString name = context->thisObject().property("name").toString(); + QString result = QString::fromLatin1("Person(name: %0)").arg(name); + return result; +} +//! [35] + + +//! [36] +QScriptEngine engine; +QScriptValue ctor = engine.newFunction(Person_ctor); +ctor.property("prototype").setProperty("toString", engine.newFunction(Person_prototype_toString)); +QScriptValue global = engine.globalObject(); +global.setProperty("Person", ctor); +//! [36] + + +//! [37] +QScriptValue Employee_ctor(QScriptContext *context, QScriptEngine *engine) +{ + QScriptValue super = context->callee().property("prototype").property("constructor"); + super.call(context->thisObject(), QScriptValueList() << context->argument(0)); + context->thisObject().setProperty("salary", context->argument(1)); + return engine->undefinedValue(); +} +//! [37] + + +//! [38] +QScriptValue empCtor = engine.newFunction(Employee_ctor); +empCtor.setProperty("prototype", global.property("Person").construct()); +global.setProperty("Employee", empCtor); +//! [38] + + +//! [39] +Q_DECLARE_METATYPE(QPointF) +Q_DECLARE_METATYPE(QPointF*) + +QScriptValue QPointF_prototype_x(QScriptContext *context, QScriptEngine *engine) +{ + // Since the point is not to be modified, it's OK to cast to a value here + QPointF point = qscriptvalue_cast<QPointF>(context->thisObject()); + return point.x(); +} + +QScriptValue QPointF_prototype_setX(QScriptContext *context, QScriptEngine *engine) +{ + // Cast to a pointer to be able to modify the underlying C++ value + QPointF *point = qscriptvalue_cast<QPointF*>(context->thisObject()); + if (!point) + return context->throwError(QScriptContext::TypeError, "QPointF.prototype.setX: this object is not a QPointF"); + point->setX(context->argument(0).toNumber()); + return engine->undefinedValue(); +} +//! [39] + + +//! [43] +class MyObject : public QObject +{ + Q_OBJECT + ... +}; + +Q_DECLARE_METATYPE(MyObject*) + +QScriptValue myObjectToScriptValue(QScriptEngine *engine, MyObject* const &in) +{ return engine->newQObject(in); } + +void myObjectFromScriptValue(const QScriptValue &object, MyObject* &out) +{ out = qobject_cast<MyObject*>(object.toQObject()); } + +... + +qScriptRegisterMetaType(&engine, myObjectToScriptValue, myObjectFromScriptValue); +//! [43] + +//! [44] +QScriptValue QPoint_ctor(QScriptContext *context, QScriptEngine *engine) +{ + int x = context->argument(0).toInt32(); + int y = context->argument(1).toInt32(); + return engine->toScriptValue(QPoint(x, y)); +} + +... + +engine.globalObject().setProperty("QPoint", engine.newFunction(QPoint_ctor)); +//! [44] + +//! [45] +QScriptValue myPrintFunction(QScriptContext *context, QScriptEngine *engine) +{ + QString result; + for (int i = 0; i < context->argumentCount(); ++i) { + if (i > 0) + result.append(" "); + result.append(context->argument(i).toString()); + } + + QScriptValue calleeData = context->callee().data(); + QPlainTextEdit *edit = qobject_cast<QPlainTextEdit*>(calleeData.toQObject()); + edit->appendPlainText(result); + + return engine->undefinedValue(); +} +//! [45] + +//! [46] +int main(int argc, char **argv) +{ + QApplication app(argc, argv); + + QScriptEngine eng; + QPlainTextEdit edit; + + QScriptValue fun = eng.newFunction(myPrintFunction); + fun.setData(eng.newQObject(&edit)); + eng.globalObject().setProperty("print", fun); + + eng.evaluate("print('hello', 'world')"); + + edit.show(); + return app.exec(); +} +//! [46] + + +//! [47] +QScriptEngine eng; +QLineEdit *edit = new QLineEdit(...); +QScriptValue handler = eng.evaluate("(function(text) { print('text was changed to', text); })"); +qScriptConnect(edit, SIGNAL(textChanged(const QString &)), QScriptValue(), handler); +//! [47] + +//! [48] +QLineEdit *edit1 = new QLineEdit(...); +QLineEdit *edit2 = new QLineEdit(...); + +QScriptValue handler = eng.evaluate("(function() { print('I am', this.name); })"); +QScriptValue obj1 = eng.newObject(); +obj1.setProperty("name", "the walrus"); +QScriptValue obj2 = eng.newObject(); +obj2.setProperty("name", "Sam"); + +qScriptConnect(edit1, SIGNAL(returnPressed()), obj1, handler); +qScriptConnect(edit2, SIGNAL(returnPressed()), obj2, handler); +//! [48] + +//! [52] +QScriptValue getProperty(QScriptContext *ctx, QScriptEngine *eng) +{ + QString name = ctx->argument(0).toString(); + return ctx->thisObject().property(name); +} +//! [52] + +//! [53] +QScriptValue myCompare(QScriptContext *ctx, QScriptEngine *eng) +{ + double first = ctx->argument(0).toNumber(); + double second = ctx->argument(1).toNumber(); + int result; + if (first == second) + result = 0; + else if (first < second) + result = -1; + else + result = 1; + return result; +} +//! [53] + +//! [54] +QScriptEngine eng; +QScriptValue comparefn = eng.newFunction(myCompare); +QScriptValue array = eng.evaluate("new Array(10, 5, 20, 15, 30)"); +array.property("sort").call(array, QScriptValueList() << comparefn); + +// prints "5,10,15,20,30" +qDebug() << array.toString(); +//! [54] + +//! [55] +QScriptValue rectifier(QScriptContext *ctx, QScriptEngine *eng) +{ + QRectF magicRect = qscriptvalue_cast<QRectF>(ctx->callee().data()); + QRectF sourceRect = qscriptvalue_cast<QRectF>(ctx->argument(0)); + return eng->toScriptValue(sourceRect.intersected(magicRect)); +} + +... + +QScriptValue fun = eng.newFunction(rectifier); +QRectF magicRect = QRectF(10, 20, 30, 40); +fun.setData(eng.toScriptValue(magicRect)); +eng.globalObject().setProperty("rectifier", fun); +//! [55] + +//! [58] +QScriptValue add(QScriptContext *ctx, QScriptEngine *eng) +{ + double a = ctx->argument(0).toNumber(); + double b = ctx->argument(1).toNumber(); + return a + b; +} +//! [58] + +//! [62] +QScriptValue add(QScriptContext *ctx, QScriptEngine *eng) +{ + if (ctx->argumentCount() != 2) + return ctx->throwError("add() takes exactly two arguments"); + double a = ctx->argument(0).toNumber(); + double b = ctx->argument(1).toNumber(); + return a + b; +} +//! [62] + +//! [63] +QScriptValue add(QScriptContext *ctx, QScriptEngine *eng) +{ + if (ctx->argumentCount() != 2) + return ctx->throwError("add() takes exactly two arguments"); + if (!ctx->argument(0).isNumber()) + return ctx->throwError(QScriptContext::TypeError, "add(): first argument is not a number"); + if (!ctx->argument(1).isNumber()) + return ctx->throwError(QScriptContext::TypeError, "add(): second argument is not a number"); + double a = ctx->argument(0).toNumber(); + double b = ctx->argument(1).toNumber(); + return a + b; +} +//! [63] + +//! [65] +QScriptValue concat(QScriptContext *ctx, QScriptEngine *eng) +{ + QString result = ""; + for (int i = 0; i < ctx->argumentCount(); ++i) + result += ctx->argument(i).toString(); + return result; +} +//! [65] + +//! [67] +QScriptValue sort(QScriptContext *ctx, QScriptEngine *eng) +{ + QScriptValue comparefn = ctx->argument(0); + if (comparefn.isUndefined()) + comparefn = /* the built-in comparison function */; + else if (!comparefn.isFunction()) + return ctx->throwError(QScriptContext::TypeError, "sort(): argument is not a function"); + ... +} +//! [67] + +//! [69] +QScriptValue foo(QScriptContext *ctx, QScriptEngine *eng) +{ + QScriptValue bar = eng->globalObject().property("bar"); + QScriptValue arguments = ctx->argumentsObject(); + qDebug() << "calling bar() with" << arguments.property("length").toInt32() << "arguments"; + QScriptValue result = bar.apply(ctx->thisObject(), arguments); + qDebug() << "bar() returned" << result.toString(); + return result; +} +//! [69] + +//! [72] +QScriptValue counter(QScriptContext *ctx, QScriptEngine *eng) +{ + QScriptValue act = ctx->activationObject(); + act.setProperty("count", 0); + QScriptValue result = eng->newFunction(counter_inner); + result.setScope(act); + return result; +} +//! [72] + +//! [73] +QScriptValue counter_inner(QScriptContext *ctx, QScriptEngine *eng) +{ + QScriptValue outerAct = ctx->callee().scope(); + double count = outerAct.property("count").toNumber(); + outerAct.setProperty("count", count+1); + return count; +} +//! [73] + +//! [74] +QScriptValue counter_hybrid(QScriptContext *ctx, QScriptEngine *eng) +{ + QScriptValue act = ctx->activationObject(); + act.setProperty("count", 0); + return eng->evaluate("(function() { return count++; })"); +} +//! [74] + +//! [76] +QScriptValue Person_ctor(QScriptContext *ctx, QScriptEngine *eng) +{ + QScriptValue object; + if (ctx->isCalledAsConstructor()) { + object = ctx->thisObject(); + } else { + object = eng->newObject(); + object.setPrototype(ctx->callee().property("prototype")); + } + object.setProperty("name", ctx->argument(0)); + return object; +} +//! [76] + +//! [77] +QScriptContext *ctx = eng.pushContext(); +QScriptValue act = ctx->activationObject(); +act.setProperty("digit", 7); + +qDebug() << eng.evaluate("digit + 1").toNumber(); // 8 + +eng.popContext(); +//! [77] + +//! [78] +QScriptValue getSet(QScriptContext *ctx, QScriptEngine *eng) +{ + QScriptValue obj = ctx->thisObject(); + QScriptValue data = obj.data(); + if (!data.isValid()) { + data = eng->newObject(); + obj.setData(data); + } + QScriptValue result; + if (ctx->argumentCount() == 1) { + QString str = ctx->argument(0).toString(); + str.replace("Roberta", "Ken"); + result = str; + data.setProperty("x", result); + } else { + result = data.property("x"); + } + return result; +} +//! [78] + +//! [79] +QScriptEngine eng; +QScriptValue obj = eng.newObject(); +obj.setProperty("x", eng.newFunction(getSet), + QScriptValue::PropertyGetter|QScriptValue::PropertySetter); +//! [79] + +//! [91] +QScriptValue object = engine.evaluate("({ unitName: 'Celsius', toKelvin: function(x) { return x + 273; } })"); +QScriptValue toKelvin = object.property("toKelvin"); +QScriptValue result = toKelvin.call(object, QScriptValueList() << 100); +qDebug() << result.toNumber(); // 373 +//! [91] + +//! [92] +QScriptValue add = engine.globalObject().property("add"); +qDebug() << add.call(QScriptValue(), QScriptValueList() << 1 << 2).toNumber(); // 3 +//! [92] + +//! [93] +typedef QSharedPointer<QXmlStreamReader> XmlStreamReaderPointer; + +Q_DECLARE_METATYPE(XmlStreamReaderPointer) + +QScriptValue constructXmlStreamReader(QScriptContext *context, QScriptEngine *engine) +{ + if (!context->isCalledAsConstructor()) + return context->throwError(QScriptContext::SyntaxError, "please use the 'new' operator"); + + QIODevice *device = qobject_cast<QIODevice*>(context->argument(0).toQObject()); + if (!device) + return context->throwError(QScriptContext::TypeError, "please supply a QIODevice as first argument"); + + // Create the C++ object + QXmlStreamReader *reader = new QXmlStreamReader(device); + + XmlStreamReaderPointer pointer(reader); + + // store the shared pointer in the script object that we are constructing + return engine->newVariant(context->thisObject(), QVariant::fromValue(pointer)); +} +//! [93] + +//! [94] +QScriptValue xmlStreamReader_atEnd(QScriptContext *context, QScriptEngine *) +{ + XmlStreamReaderPointer reader = qscriptvalue_cast<XmlStreamReaderPointer>(context->thisObject()); + if (!reader) + return context->throwError(QScriptContext::TypeError, "this object is not an XmlStreamReader"); + return reader->atEnd(); +} +//! [94] + +//! [95] + QScriptEngine engine; + QScriptValue xmlStreamReaderProto = engine.newObject(); + xmlStreamReaderProto.setProperty("atEnd", engine.newFunction(xmlStreamReader_atEnd)); + + QScriptValue xmlStreamReaderCtor = engine.newFunction(constructXmlStreamReader, xmlStreamReaderProto); + engine.globalObject().setProperty("XmlStreamReader", xmlStreamReaderCtor); +//! [95] diff --git a/doc/src/snippets/code/doc_src_qtscript.js b/doc/src/snippets/code/doc_src_qtscript.js new file mode 100644 index 0000000..fe1f9b9 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtscript.js @@ -0,0 +1,444 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [2] +function myInterestingScriptFunction() { + // ... +} +// ... +myQObject.somethingChanged.connect(myInterestingScriptFunction); +//! [2] + + +//! [3] +myQObject.somethingChanged.connect(myOtherQObject.doSomething); +//! [3] + + +//! [4] +myQObject.somethingChanged.disconnect(myInterestingFunction); +myQObject.somethingChanged.disconnect(myOtherQObject.doSomething); +//! [4] + + +//! [5] +var obj = { x: 123 }; +var fun = function() { print(this.x); }; +myQObject.somethingChanged.connect(obj, fun); +//! [5] + + +//! [6] +myQObject.somethingChanged.disconnect(obj, fun); +//! [6] + + +//! [7] +var obj = { x: 123, fun: function() { print(this.x); } }; +myQObject.somethingChanged.connect(obj, "fun"); +//! [7] + + +//! [8] +myQObject.somethingChanged.disconnect(obj, "fun"); +//! [8] + + +//! [9] +try { + myQObject.somethingChanged.connect(myQObject, "slotThatDoesntExist"); +} catch (e) { + print(e); +} +//! [9] + + +//! [10] +myQObject.somethingChanged("hello"); +//! [10] + + +//! [11] +myQObject.myOverloadedSlot(10); // will call the int overload +myQObject.myOverloadedSlot("10"); // will call the QString overload +//! [11] + + +//! [12] +myQObject['myOverloadedSlot(int)']("10"); // call int overload; the argument is converted to an int +myQObject['myOverloadedSlot(QString)'](10); // call QString overload; the argument is converted to a string +//! [12] + + +//! [14] +myQObject.enabled = true; + +// ... + +myQObject.enabled = !myQObject.enabled; +//! [14] + + +//! [15] +myDialog.okButton +//! [15] + + +//! [16] +myDialog.okButton.objectName = "cancelButton"; +// from now on, myDialog.cancelButton references the button +//! [16] + + +//! [17] +var okButton = myDialog.findChild("okButton"); +if (okButton != null) { + // do something with the OK button +} + +var buttons = myDialog.findChildren(RegExp("button[0-9]+")); +for (var i = 0; i < buttons.length; ++i) { + // do something with buttons[i] +} +//! [17] + + +//! [21] +var obj = new MyObject; +obj.setEnabled( true ); +print( "obj is enabled: " + obj.isEnabled() ); +//! [21] + + +//! [22] +var obj = new MyObject; +obj.enabled = true; +print( "obj is enabled: " + obj.enabled ); +//! [22] + + +//! [26] +function enabledChangedHandler( b ) +{ + print( "state changed to: " + b ); +} + +function init() +{ + var obj = new MyObject(); + // connect a script function to the signal + obj["enabledChanged(bool)"].connect(enabledChangedHandler); + obj.enabled = true; + print( "obj is enabled: " + obj.enabled ); +} +//! [26] + + +//! [27] +var o = new Object(); +o.foo = 123; +print(o.hasOwnProperty('foo')); // true +print(o.hasOwnProperty('bar')); // false +print(o); // calls o.toString(), which returns "[object Object]" +//! [27] + + +//! [28] +function Person(name) +{ + this.name = name; +} +//! [28] + + +//! [29] +Person.prototype.toString = function() { return "Person(name: " + this.name + ")"; } +//! [29] + + +//! [30] +var p1 = new Person("John Doe"); +var p2 = new Person("G.I. Jane"); +print(p1); // "Person(name: John Doe)" +print(p2); // "Person(name: G.I. Jane)" +//! [30] + + +//! [31] +print(p1.hasOwnProperty('name')); // 'name' is an instance variable, so this returns true +print(p1.hasOwnProperty('toString')); // returns false; inherited from prototype +print(p1 instanceof Person); // true +print(p1 instanceof Object); // true +//! [31] + + +//! [32] +function Employee(name, salary) +{ + Person.call(this, name); // call base constructor + + this.salary = salary; +} + +// set the prototype to be an instance of the base class +Employee.prototype = new Person(); + +// initialize prototype +Employee.prototype.toString = function() { + // ... +} +//! [32] + + +//! [33] +var e = new Employee("Johnny Bravo", 5000000); +print(e instanceof Employee); // true +print(e instanceof Person); // true +print(e instanceof Object); // true +print(e instanceof Array); // false +//! [33] + + +//! [40] +var o = new Object(); +(o.__proto__ === Object.prototype); // this evaluates to true +//! [40] + + +//! [41] +var o = new Object(); +o.__defineGetter__("x", function() { return 123; }); +var y = o.x; // 123 +//! [41] + + +//! [42] +var o = new Object(); +o.__defineSetter__("x", function(v) { print("and the value is:", v); }); +o.x = 123; // will print "and the value is: 123" +//! [42] + + +//! [49] +var getProperty = function(name) { return this[name]; }; + +name = "Global Object"; // creates a global variable +print(getProperty("name")); // "Global Object" + +var myObject = { name: 'My Object' }; +print(getProperty.call(myObject, "name")); // "My Object" + +myObject.getProperty = getProperty; +print(myObject.getProperty("name")); // "My Object" + +getProperty.name = "The getProperty() function"; +getProperty.getProperty = getProperty; +getProperty.getProperty("name"); // "The getProperty() function" +//! [49] + +//! [50] +var o = { a: 1, b: 2, sum: function() { return a + b; } }; +print(o.sum()); // reference error, or sum of global variables a and b!! +//! [50] + +//! [51] +var o = { a: 1, b: 2, sum: function() { return this.a + this.b; } }; +print(o.sum()); // 3 +//! [51] + +//! [56] +function add(a, b) { + return a + b; +} +//! [56] + +//! [57] +function add() { + return arguments[0] + arguments[1]; +} +//! [57] + +//! [59] +function add() { + if (arguments.length != 2) + throw Error("add() takes exactly two arguments"); + return arguments[0] + arguments[1]; +} +//! [59] + +//! [60] +function add() { + if (arguments.length != 2) + throw Error("add() takes exactly two arguments"); + if (typeof arguments[0] != "number") + throw TypeError("add(): first argument is not a number"); + if (typeof arguments[1] != "number") + throw TypeError("add(): second argument is not a number"); + return arguments[0] + arguments[1]; +} +//! [60] + +//! [61] +function add() { + if (arguments.length != 2) + throw Error("add() takes exactly two arguments"); + return Number(arguments[0]) + Number(arguments[1]); +} +//! [61] + +//! [64] +function concat() { + var result = ""; + for (var i = 0; i < arguments.length; ++i) + result += String(arguments[i]); + return result; +} +//! [64] + +//! [66] +function sort(comparefn) { + if (comparefn == undefined) + comparefn = fn; /* replace fn with the built-in comparison function */ + else if (typeof comparefn != "function") + throw TypeError("sort(): argument must be a function"); + // ... +} +//! [66] + +//! [68] +function foo() { + // Let bar() take care of this. + print("calling bar() with " + arguments.length + "arguments"); + var result = bar.apply(this, arguments); + print("bar() returned" + result); + return result; +} +//! [68] + +//! [70] +function counter() { + var count = 0; + return function() { + return count++; + } +} +//! [70] + +//! [71] +var c1 = counter(); // create a new counter function +var c2 = counter(); // create a new counter function +print(c1()); // 0 +print(c1()); // 1 +print(c2()); // 0 +print(c2()); // 1 +//! [71] + +//! [75] +function Book(isbn) { + this.isbn = isbn; +} + +var coolBook1 = new Book("978-0131872493"); +var coolBook2 = new Book("978-1593271473"); +//! [75] + +//! [80] +obj.x = "Roberta sent me"; +print(obj.x); // "Ken sent me" +obj.x = "I sent the bill to Roberta"; +print(obj.x); // "I sent the bill to Ken" +//! [80] + +//! [81] +obj = {}; +obj.__defineGetter__("x", function() { return this._x; }); +obj.__defineSetter__("x", function(v) { print("setting x to", v); this._x = v; }); +obj.x = 123; +//! [81] + +//! [82] +myButton.text = qsTr("Hello world!"); +//! [82] + +//! [83] +myButton.text = qsTranslate("MyAwesomeScript", "Hello world!"); +//! [83] + +//! [84] +FriendlyConversation.prototype.greeting = function(type) +{ + if (FriendlyConversation['greeting_strings'] == undefined) { + FriendlyConversation['greeting_strings'] = [ + QT_TR_NOOP("Hello"), + QT_TR_NOOP("Goodbye") + ]; + } + return qsTr(FriendlyConversation.greeting_strings[type]); +} +//! [84] + +//! [85] +FriendlyConversation.prototype.greeting = function(type) +{ + if (FriendlyConversation['greeting_strings'] == undefined) { + FriendlyConversation['greeting_strings'] = [ + QT_TRANSLATE_NOOP("FriendlyConversation", "Hello"), + QT_TRANSLATE_NOOP("FriendlyConversation", "Goodbye") + ]; + } + return qsTranslate("FriendlyConversation", FriendlyConversation.greeting_strings[type]); +} +//! [85] + +//! [86] +FileCopier.prototype.showProgress = function(done, total, currentFileName) +{ + this.label.text = qsTr("%1 of %2 files copied.\nCopying: %3") + .arg(done) + .arg(total) + .arg(currentFileName); +} +//! [86] + +//! [90] +({ unitName: "Celsius", + toKelvin: function(x) { return x + 273; } + }) +//! [90] diff --git a/doc/src/snippets/code/doc_src_qtscript.pro b/doc/src/snippets/code/doc_src_qtscript.pro new file mode 100644 index 0000000..ce687d7 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtscript.pro @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [1] +QT += script +#! [1] diff --git a/doc/src/snippets/code/doc_src_qtscript.qdoc b/doc/src/snippets/code/doc_src_qtscript.qdoc index 1ba097a..b65311f 100644 --- a/doc/src/snippets/code/doc_src_qtscript.qdoc +++ b/doc/src/snippets/code/doc_src_qtscript.qdoc @@ -38,882 +38,6 @@ ** ****************************************************************************/ -//! [0] -#include <QtScript> -//! [0] - - -//! [1] -QT += script -//! [1] - - -//! [2] -function myInterestingScriptFunction() { ... } -... -myQObject.somethingChanged.connect(myInterestingScriptFunction); -//! [2] - - -//! [3] -myQObject.somethingChanged.connect(myOtherQObject.doSomething); -//! [3] - - -//! [4] -myQObject.somethingChanged.disconnect(myInterestingFunction); -myQObject.somethingChanged.disconnect(myOtherQObject.doSomething); -//! [4] - - -//! [5] -var obj = { x: 123 }; -var fun = function() { print(this.x); }; -myQObject.somethingChanged.connect(obj, fun); -//! [5] - - -//! [6] -myQObject.somethingChanged.disconnect(obj, fun); -//! [6] - - -//! [7] -var obj = { x: 123, fun: function() { print(this.x); } }; -myQObject.somethingChanged.connect(obj, "fun"); -//! [7] - - -//! [8] -myQObject.somethingChanged.disconnect(obj, "fun"); -//! [8] - - -//! [9] -try { - myQObject.somethingChanged.connect(myQObject, "slotThatDoesntExist"); -} catch (e) { - print(e); -} -//! [9] - - -//! [10] -myQObject.somethingChanged("hello"); -//! [10] - - -//! [11] -myQObject.myOverloadedSlot(10); // will call the int overload -myQObject.myOverloadedSlot("10"); // will call the QString overload -//! [11] - - -//! [12] -myQObject['myOverloadedSlot(int)']("10"); // call int overload; the argument is converted to an int -myQObject['myOverloadedSlot(QString)'](10); // call QString overload; the argument is converted to a string -//! [12] - - -//! [13] -Q_PROPERTY(bool enabled READ enabled WRITE setEnabled) -//! [13] - - -//! [14] -myQObject.enabled = true; - -... - -myQObject.enabled = !myQObject.enabled; -//! [14] - - -//! [15] -myDialog.okButton -//! [15] - - -//! [16] -myDialog.okButton.objectName = "cancelButton"; -// from now on, myDialog.cancelButton references the button -//! [16] - - -//! [17] -var okButton = myDialog.findChild("okButton"); -if (okButton != null) { - // do something with the OK button -} - -var buttons = myDialog.findChildren(RegExp("button[0-9]+")); -for (var i = 0; i < buttons.length; ++i) { - // do something with buttons[i] -} -//! [17] - - -//! [18] -QScriptValue myQObjectConstructor(QScriptContext *context, QScriptEngine *engine) -{ - // let the engine manage the new object's lifetime. - return engine->newQObject(new MyQObject(), QScriptEngine::ScriptOwnership); -} -//! [18] - - -//! [19] -class MyObject : public QObject -{ - Q_OBJECT - -public: - MyObject( ... ); - - void aNonScriptableFunction(); - -public slots: // these functions (slots) will be available in QtScript - void calculate( ... ); - void setEnabled( bool enabled ); - bool isEnabled() const; - -private: - .... - -}; -//! [19] - - -//! [20] -class MyObject : public QObject -{ - Q_OBJECT - - public: - Q_INVOKABLE void thisMethodIsInvokableInQtScript(); - void thisMethodIsNotInvokableInQtScript(); - - ... -}; -//! [20] - - -//! [21] -var obj = new MyObject; -obj.setEnabled( true ); -print( "obj is enabled: " + obj.isEnabled() ); -//! [21] - - -//! [22] -var obj = new MyObject; -obj.enabled = true; -print( "obj is enabled: " + obj.enabled ); -//! [22] - - -//! [23] -class MyObject : public QObject -{ - Q_OBJECT - // define the enabled property - Q_PROPERTY( bool enabled WRITE setEnabled READ isEnabled ) - -public: - MyObject( ... ); - - void aNonScriptableFunction(); - -public slots: // these functions (slots) will be available in QtScript - void calculate( ... ); - void setEnabled( bool enabled ); - bool isEnabled() const; - -private: - .... - -}; -//! [23] - - -//! [24] -Q_PROPERTY(int nonScriptableProperty READ foo WRITE bar SCRIPTABLE false) -//! [24] - - -//! [25] -class MyObject : public QObject -{ - Q_OBJECT - // define the enabled property - Q_PROPERTY( bool enabled WRITE setEnabled READ isEnabled ) - -public: - MyObject( ... ); - - void aNonScriptableFunction(); - -public slots: // these functions (slots) will be available in QtScript - void calculate( ... ); - void setEnabled( bool enabled ); - bool isEnabled() const; - -signals: // the signals - void enabledChanged( bool newState ); - -private: - .... - -}; -//! [25] - - -//! [26] -function enabledChangedHandler( b ) -{ - print( "state changed to: " + b ); -} - -function init() -{ - var obj = new MyObject(); - // connect a script function to the signal - obj["enabledChanged(bool)"].connect(enabledChangedHandler); - obj.enabled = true; - print( "obj is enabled: " + obj.enabled ); -} -//! [26] - - -//! [27] -var o = new Object(); -o.foo = 123; -print(o.hasOwnProperty('foo')); // true -print(o.hasOwnProperty('bar')); // false -print(o); // calls o.toString(), which returns "[object Object]" -//! [27] - - -//! [28] -function Person(name) -{ - this.name = name; -} -//! [28] - - -//! [29] -Person.prototype.toString = function() { return "Person(name: " + this.name + ")"; } -//! [29] - - -//! [30] -var p1 = new Person("John Doe"); -var p2 = new Person("G.I. Jane"); -print(p1); // "Person(name: John Doe)" -print(p2); // "Person(name: G.I. Jane)" -//! [30] - - -//! [31] -print(p1.hasOwnProperty('name')); // 'name' is an instance variable, so this returns true -print(p1.hasOwnProperty('toString')); // returns false; inherited from prototype -print(p1 instanceof Person); // true -print(p1 instanceof Object); // true -//! [31] - - -//! [32] -function Employee(name, salary) -{ - Person.call(this, name); // call base constructor - - this.salary = salary; -} - -// set the prototype to be an instance of the base class -Employee.prototype = new Person(); - -// initialize prototype -Employee.prototype.toString = function() { ... } -//! [32] - - -//! [33] -var e = new Employee("Johnny Bravo", 5000000); -print(e instanceof Employee); // true -print(e instanceof Person); // true -print(e instanceof Object); // true -print(e instanceof Array); // false -//! [33] - - -//! [34] -QScriptValue Person_ctor(QScriptContext *context, QScriptEngine *engine) -{ - QString name = context->argument(0).toString(); - context->thisObject().setProperty("name", name); - return engine->undefinedValue(); -} -//! [34] - - -//! [35] -QScriptValue Person_prototype_toString(QScriptContext *context, QScriptEngine *engine) -{ - QString name = context->thisObject().property("name").toString(); - QString result = QString::fromLatin1("Person(name: %0)").arg(name); - return result; -} -//! [35] - - -//! [36] -QScriptEngine engine; -QScriptValue ctor = engine.newFunction(Person_ctor); -ctor.property("prototype").setProperty("toString", engine.newFunction(Person_prototype_toString)); -QScriptValue global = engine.globalObject(); -global.setProperty("Person", ctor); -//! [36] - - -//! [37] -QScriptValue Employee_ctor(QScriptContext *context, QScriptEngine *engine) -{ - QScriptValue super = context->callee().property("prototype").property("constructor"); - super.call(context->thisObject(), QScriptValueList() << context->argument(0)); - context->thisObject().setProperty("salary", context->argument(1)); - return engine->undefinedValue(); -} -//! [37] - - -//! [38] -QScriptValue empCtor = engine.newFunction(Employee_ctor); -empCtor.setProperty("prototype", global.property("Person").construct()); -global.setProperty("Employee", empCtor); -//! [38] - - -//! [39] -Q_DECLARE_METATYPE(QPointF) -Q_DECLARE_METATYPE(QPointF*) - -QScriptValue QPointF_prototype_x(QScriptContext *context, QScriptEngine *engine) -{ - // Since the point is not to be modified, it's OK to cast to a value here - QPointF point = qscriptvalue_cast<QPointF>(context->thisObject()); - return point.x(); -} - -QScriptValue QPointF_prototype_setX(QScriptContext *context, QScriptEngine *engine) -{ - // Cast to a pointer to be able to modify the underlying C++ value - QPointF *point = qscriptvalue_cast<QPointF*>(context->thisObject()); - if (!point) - return context->throwError(QScriptContext::TypeError, "QPointF.prototype.setX: this object is not a QPointF"); - point->setX(context->argument(0).toNumber()); - return engine->undefinedValue(); -} -//! [39] - - -//! [40] -var o = new Object(); -(o.__proto__ === Object.prototype); // this evaluates to true -//! [40] - - -//! [41] -var o = new Object(); -o.__defineGetter__("x", function() { return 123; }); -var y = o.x; // 123 -//! [41] - - -//! [42] -var o = new Object(); -o.__defineSetter__("x", function(v) { print("and the value is:", v); }); -o.x = 123; // will print "and the value is: 123" -//! [42] - - -//! [43] -class MyObject : public QObject -{ - Q_OBJECT - ... -}; - -Q_DECLARE_METATYPE(MyObject*) - -QScriptValue myObjectToScriptValue(QScriptEngine *engine, MyObject* const &in) -{ return engine->newQObject(in); } - -void myObjectFromScriptValue(const QScriptValue &object, MyObject* &out) -{ out = qobject_cast<MyObject*>(object.toQObject()); } - -... - -qScriptRegisterMetaType(&engine, myObjectToScriptValue, myObjectFromScriptValue); -//! [43] - -//! [44] -QScriptValue QPoint_ctor(QScriptContext *context, QScriptEngine *engine) -{ - int x = context->argument(0).toInt32(); - int y = context->argument(1).toInt32(); - return engine->toScriptValue(QPoint(x, y)); -} - -... - -engine.globalObject().setProperty("QPoint", engine.newFunction(QPoint_ctor)); -//! [44] - -//! [45] -QScriptValue myPrintFunction(QScriptContext *context, QScriptEngine *engine) -{ - QString result; - for (int i = 0; i < context->argumentCount(); ++i) { - if (i > 0) - result.append(" "); - result.append(context->argument(i).toString()); - } - - QScriptValue calleeData = context->callee().data(); - QPlainTextEdit *edit = qobject_cast<QPlainTextEdit*>(calleeData.toQObject()); - edit->appendPlainText(result); - - return engine->undefinedValue(); -} -//! [45] - -//! [46] -int main(int argc, char **argv) -{ - QApplication app(argc, argv); - - QScriptEngine eng; - QPlainTextEdit edit; - - QScriptValue fun = eng.newFunction(myPrintFunction); - fun.setData(eng.newQObject(&edit)); - eng.globalObject().setProperty("print", fun); - - eng.evaluate("print('hello', 'world')"); - - edit.show(); - return app.exec(); -} -//! [46] - - -//! [47] -QScriptEngine eng; -QLineEdit *edit = new QLineEdit(...); -QScriptValue handler = eng.evaluate("(function(text) { print('text was changed to', text); })"); -qScriptConnect(edit, SIGNAL(textChanged(const QString &)), QScriptValue(), handler); -//! [47] - -//! [48] -QLineEdit *edit1 = new QLineEdit(...); -QLineEdit *edit2 = new QLineEdit(...); - -QScriptValue handler = eng.evaluate("(function() { print('I am', this.name); })"); -QScriptValue obj1 = eng.newObject(); -obj1.setProperty("name", "the walrus"); -QScriptValue obj2 = eng.newObject(); -obj2.setProperty("name", "Sam"); - -qScriptConnect(edit1, SIGNAL(returnPressed()), obj1, handler); -qScriptConnect(edit2, SIGNAL(returnPressed()), obj2, handler); -//! [48] - -//! [49] -var getProperty = function(name) { return this[name]; }; - -name = "Global Object"; // creates a global variable -print(getProperty("name")); // "Global Object" - -var myObject = { name: 'My Object' }; -print(getProperty.call(myObject, "name")); // "My Object" - -myObject.getProperty = getProperty; -print(myObject.getProperty("name")); // "My Object" - -getProperty.name = "The getProperty() function"; -getProperty.getProperty = getProperty; -getProperty.getProperty("name"); // "The getProperty() function" -//! [49] - -//! [50] -var o = { a: 1, b: 2, sum: function() { return a + b; } }; -print(o.sum()); // reference error, or sum of global variables a and b!! -//! [50] - -//! [51] -var o = { a: 1, b: 2, sum: function() { return this.a + this.b; } }; -print(o.sum()); // 3 -//! [51] - -//! [52] -QScriptValue getProperty(QScriptContext *ctx, QScriptEngine *eng) -{ - QString name = ctx->argument(0).toString(); - return ctx->thisObject().property(name); -} -//! [52] - -//! [53] -QScriptValue myCompare(QScriptContext *ctx, QScriptEngine *eng) -{ - double first = ctx->argument(0).toNumber(); - double second = ctx->argument(1).toNumber(); - int result; - if (first == second) - result = 0; - else if (first < second) - result = -1; - else - result = 1; - return result; -} -//! [53] - -//! [54] -QScriptEngine eng; -QScriptValue comparefn = eng.newFunction(myCompare); -QScriptValue array = eng.evaluate("new Array(10, 5, 20, 15, 30)"); -array.property("sort").call(array, QScriptValueList() << comparefn); - -// prints "5,10,15,20,30" -qDebug() << array.toString(); -//! [54] - -//! [55] -QScriptValue rectifier(QScriptContext *ctx, QScriptEngine *eng) -{ - QRectF magicRect = qscriptvalue_cast<QRectF>(ctx->callee().data()); - QRectF sourceRect = qscriptvalue_cast<QRectF>(ctx->argument(0)); - return eng->toScriptValue(sourceRect.intersected(magicRect)); -} - -... - -QScriptValue fun = eng.newFunction(rectifier); -QRectF magicRect = QRectF(10, 20, 30, 40); -fun.setData(eng.toScriptValue(magicRect)); -eng.globalObject().setProperty("rectifier", fun); -//! [55] - -//! [56] -function add(a, b) { - return a + b; -} -//! [56] - -//! [57] -function add() { - return arguments[0] + arguments[1]; -} -//! [57] - -//! [58] -QScriptValue add(QScriptContext *ctx, QScriptEngine *eng) -{ - double a = ctx->argument(0).toNumber(); - double b = ctx->argument(1).toNumber(); - return a + b; -} -//! [58] - -//! [59] -function add() { - if (arguments.length != 2) - throw Error("add() takes exactly two arguments"); - return arguments[0] + arguments[1]; -} -//! [59] - -//! [60] -function add() { - if (arguments.length != 2) - throw Error("add() takes exactly two arguments"); - if (typeof arguments[0] != "number") - throw TypeError("add(): first argument is not a number"); - if (typeof arguments[1] != "number") - throw TypeError("add(): second argument is not a number"); - return arguments[0] + arguments[1]; -} -//! [60] - -//! [61] -function add() { - if (arguments.length != 2) - throw Error("add() takes exactly two arguments"); - return Number(arguments[0]) + Number(arguments[1]); -} -//! [61] - -//! [62] -QScriptValue add(QScriptContext *ctx, QScriptEngine *eng) -{ - if (ctx->argumentCount() != 2) - return ctx->throwError("add() takes exactly two arguments"); - double a = ctx->argument(0).toNumber(); - double b = ctx->argument(1).toNumber(); - return a + b; -} -//! [62] - -//! [63] -QScriptValue add(QScriptContext *ctx, QScriptEngine *eng) -{ - if (ctx->argumentCount() != 2) - return ctx->throwError("add() takes exactly two arguments"); - if (!ctx->argument(0).isNumber()) - return ctx->throwError(QScriptContext::TypeError, "add(): first argument is not a number"); - if (!ctx->argument(1).isNumber()) - return ctx->throwError(QScriptContext::TypeError, "add(): second argument is not a number"); - double a = ctx->argument(0).toNumber(); - double b = ctx->argument(1).toNumber(); - return a + b; -} -//! [63] - -//! [64] -function concat() { - var result = ""; - for (var i = 0; i < arguments.length; ++i) - result += String(arguments[i]); - return result; -} -//! [64] - -//! [65] -QScriptValue concat(QScriptContext *ctx, QScriptEngine *eng) -{ - QString result = ""; - for (int i = 0; i < ctx->argumentCount(); ++i) - result += ctx->argument(i).toString(); - return result; -} -//! [65] - -//! [66] -function sort(comparefn) { - if (comparefn == undefined) - comparefn = /* the built-in comparison function */; - else if (typeof comparefn != "function") - throw TypeError("sort(): argument must be a function"); - ... -} -//! [66] - -//! [67] -QScriptValue sort(QScriptContext *ctx, QScriptEngine *eng) -{ - QScriptValue comparefn = ctx->argument(0); - if (comparefn.isUndefined()) - comparefn = /* the built-in comparison function */; - else if (!comparefn.isFunction()) - return ctx->throwError(QScriptContext::TypeError, "sort(): argument is not a function"); - ... -} -//! [67] - -//! [68] -function foo() { - // Let bar() take care of this. - print("calling bar() with " + arguments.length + "arguments"); - var result = return bar.apply(this, arguments); - print("bar() returned" + result); - return result; -} -//! [68] - -//! [69] -QScriptValue foo(QScriptContext *ctx, QScriptEngine *eng) -{ - QScriptValue bar = eng->globalObject().property("bar"); - QScriptValue arguments = ctx->argumentsObject(); - qDebug() << "calling bar() with" << arguments.property("length").toInt32() << "arguments"; - QScriptValue result = bar.apply(ctx->thisObject(), arguments); - qDebug() << "bar() returned" << result.toString(); - return result; -} -//! [69] - -//! [70] -function counter() { - var count = 0; - return function() { - return count++; - } -} -//! [70] - -//! [71] -var c1 = counter(); // create a new counter function -var c2 = counter(); // create a new counter function -print(c1()); // 0 -print(c1()); // 1 -print(c2()); // 0 -print(c2()); // 1 -//! [71] - -//! [72] -QScriptValue counter(QScriptContext *ctx, QScriptEngine *eng) -{ - QScriptValue act = ctx->activationObject(); - act.setProperty("count", 0); - QScriptValue result = eng->newFunction(counter_inner); - result.setScope(act); - return result; -} -//! [72] - -//! [73] -QScriptValue counter_inner(QScriptContext *ctx, QScriptEngine *eng) -{ - QScriptValue outerAct = ctx->callee().scope(); - double count = outerAct.property("count").toNumber(); - outerAct.setProperty("count", count+1); - return count; -} -//! [73] - -//! [74] -QScriptValue counter_hybrid(QScriptContext *ctx, QScriptEngine *eng) -{ - QScriptValue act = ctx->activationObject(); - act.setProperty("count", 0); - return eng->evaluate("(function() { return count++; })"); -} -//! [74] - -//! [75] -function Book(isbn) { - this.isbn = isbn; -} - -var coolBook1 = new Book("978-0131872493"); -var coolBook2 = new Book("978-1593271473"); -//! [75] - -//! [76] -QScriptValue Person_ctor(QScriptContext *ctx, QScriptEngine *eng) -{ - QScriptValue object; - if (ctx->isCalledAsConstructor()) { - object = ctx->thisObject(); - } else { - object = eng->newObject(); - object.setPrototype(ctx->callee().property("prototype")); - } - object.setProperty("name", ctx->argument(0)); - return object; -} -//! [76] - -//! [77] -QScriptContext *ctx = eng.pushContext(); -QScriptValue act = ctx->activationObject(); -act.setProperty("digit", 7); - -qDebug() << eng.evaluate("digit + 1").toNumber(); // 8 - -eng.popContext(); -//! [77] - -//! [78] -QScriptValue getSet(QScriptContext *ctx, QScriptEngine *eng) -{ - QScriptValue obj = ctx->thisObject(); - QScriptValue data = obj.data(); - if (!data.isValid()) { - data = eng->newObject(); - obj.setData(data); - } - QScriptValue result; - if (ctx->argumentCount() == 1) { - QString str = ctx->argument(0).toString(); - str.replace("Roberta", "Ken"); - result = str; - data.setProperty("x", result); - } else { - result = data.property("x"); - } - return result; -} -//! [78] - -//! [79] -QScriptEngine eng; -QScriptValue obj = eng.newObject(); -obj.setProperty("x", eng.newFunction(getSet), - QScriptValue::PropertyGetter|QScriptValue::PropertySetter); -//! [79] - -//! [80] -obj.x = "Roberta sent me"; -print(obj.x); // "Ken sent me" -obj.x = "I sent the bill to Roberta"; -print(obj.x); // "I sent the bill to Ken" -//! [80] - -//! [81] -obj = {}; -obj.__defineGetter__("x", function() { return this._x; }); -obj.__defineSetter__("x", function(v) { print("setting x to", v); this._x = v; }); -obj.x = 123; -//! [81] - -//! [82] -myButton.text = qsTr("Hello world!"); -//! [82] - -//! [83] -myButton.text = qsTranslate("MyAwesomeScript", "Hello world!"); -//! [83] - -//! [84] -FriendlyConversation.prototype.greeting = function(type) -{ - if (FriendlyConversation['greeting_strings'] == undefined) { - FriendlyConversation['greeting_strings'] = [ - QT_TR_NOOP("Hello"), - QT_TR_NOOP("Goodbye") - ]; - } - return qsTr(FriendlyConversation.greeting_strings[type]); -} -//! [84] - -//! [85] -FriendlyConversation.prototype.greeting = function(type) -{ - if (FriendlyConversation['greeting_strings'] == undefined) { - FriendlyConversation['greeting_strings'] = [ - QT_TRANSLATE_NOOP("FriendlyConversation", "Hello"), - QT_TRANSLATE_NOOP("FriendlyConversation", "Goodbye") - ]; - } - return qsTranslate("FriendlyConversation", FriendlyConversation.greeting_strings[type]); -} -//! [85] - -//! [86] -FileCopier.prototype.showProgress = function(done, total, currentFileName) -{ - this.label.text = qsTr("%1 of %2 files copied.\nCopying: %3") - .arg(done) - .arg(total) - .arg(currentFileName)); -} -//! [86] - //! [87] lupdate myscript.qs -ts myscript_la.ts //! [87] @@ -925,64 +49,3 @@ lupdate -extensions qs scripts/ -ts scripts_la.ts //! [89] lrelease myscript_la.ts //! [89] - -//! [90] -({ unitName: "Celsius", - toKelvin: function(x) { return x + 273; } - }) -//! [90] - -//! [91] -QScriptValue object = engine.evaluate("({ unitName: 'Celsius', toKelvin: function(x) { return x + 273; } })"); -QScriptValue toKelvin = object.property("toKelvin"); -QScriptValue result = toKelvin.call(object, QScriptValueList() << 100); -qDebug() << result.toNumber(); // 373 -//! [91] - -//! [92] -QScriptValue add = engine.globalObject().property("add"); -qDebug() << add.call(QScriptValue(), QScriptValueList() << 1 << 2).toNumber(); // 3 -//! [92] - -//! [93] -typedef QSharedPointer<QXmlStreamReader> XmlStreamReaderPointer; - -Q_DECLARE_METATYPE(XmlStreamReaderPointer) - -QScriptValue constructXmlStreamReader(QScriptContext *context, QScriptEngine *engine) -{ - if (!context->isCalledAsConstructor()) - return context->throwError(QScriptContext::SyntaxError, "please use the 'new' operator"); - - QIODevice *device = qobject_cast<QIODevice*>(context->argument(0).toQObject()); - if (!device) - return context->throwError(QScriptContext::TypeError, "please supply a QIODevice as first argument"); - - // Create the C++ object - QXmlStreamReader *reader = new QXmlStreamReader(device); - - XmlStreamReaderPointer pointer(reader); - - // store the shared pointer in the script object that we are constructing - return engine->newVariant(context->thisObject(), QVariant::fromValue(pointer)); -} -//! [93] - -//! [94] -QScriptValue xmlStreamReader_atEnd(QScriptContext *context, QScriptEngine *) -{ - XmlStreamReaderPointer reader = qscriptvalue_cast<XmlStreamReaderPointer>(context->thisObject()); - if (!reader) - return context->throwError(QScriptContext::TypeError, "this object is not an XmlStreamReader"); - return reader->atEnd(); -} -//! [94] - -//! [95] - QScriptEngine engine; - QScriptValue xmlStreamReaderProto = engine.newObject(); - xmlStreamReaderProto.setProperty("atEnd", engine.newFunction(xmlStreamReader_atEnd)); - - QScriptValue xmlStreamReaderCtor = engine.newFunction(constructXmlStreamReader, xmlStreamReaderProto); - engine.globalObject().setProperty("XmlStreamReader", xmlStreamReaderCtor); -//! [95] diff --git a/doc/src/snippets/code/doc_src_qtscriptextensions.qdoc b/doc/src/snippets/code/doc_src_qtscriptextensions.js index 456077d..456077d 100644 --- a/doc/src/snippets/code/doc_src_qtscriptextensions.qdoc +++ b/doc/src/snippets/code/doc_src_qtscriptextensions.js diff --git a/doc/src/snippets/code/doc_src_qtscripttools.cpp b/doc/src/snippets/code/doc_src_qtscripttools.cpp new file mode 100644 index 0000000..258c7df --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtscripttools.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +#include <QtScriptTools> +//! [0] diff --git a/doc/src/snippets/code/doc_src_qtscripttools.pro b/doc/src/snippets/code/doc_src_qtscripttools.pro new file mode 100644 index 0000000..e87644d --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtscripttools.pro @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [1] +QT += scripttools +#! [1] diff --git a/doc/src/snippets/code/doc_src_qtsql.qdoc b/doc/src/snippets/code/doc_src_qtsql.cpp index 1bc7518..9c0c16e 100644 --- a/doc/src/snippets/code/doc_src_qtsql.qdoc +++ b/doc/src/snippets/code/doc_src_qtsql.cpp @@ -41,8 +41,3 @@ //! [0] #include <QtSql> //! [0] - - -//! [1] -QT += sql -//! [1] diff --git a/doc/src/snippets/code/doc_src_qtsql.pro b/doc/src/snippets/code/doc_src_qtsql.pro new file mode 100644 index 0000000..4e31846 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtsql.pro @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [1] +QT += sql +#! [1] diff --git a/doc/src/snippets/code/doc_src_qtsvg.qdoc b/doc/src/snippets/code/doc_src_qtsvg.cpp index 57db6de..c66b4da 100644 --- a/doc/src/snippets/code/doc_src_qtsvg.qdoc +++ b/doc/src/snippets/code/doc_src_qtsvg.cpp @@ -41,8 +41,3 @@ //! [0] #include <QtSvg> //! [0] - - -//! [1] -QT += svg -//! [1] diff --git a/doc/src/snippets/code/doc_src_qtsvg.pro b/doc/src/snippets/code/doc_src_qtsvg.pro new file mode 100644 index 0000000..1a75d03 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtsvg.pro @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [1] +QT += svg +#! [1] diff --git a/doc/src/snippets/code/doc_src_qttest.qdoc b/doc/src/snippets/code/doc_src_qttest.cpp index 354d188..5b21c9e 100644 --- a/doc/src/snippets/code/doc_src_qttest.qdoc +++ b/doc/src/snippets/code/doc_src_qttest.cpp @@ -41,8 +41,3 @@ //! [0] #include <QtTest> //! [0] - - -//! [1] -CONFIG += qtestlib -//! [1] diff --git a/doc/src/snippets/code/doc_src_qttest.pro b/doc/src/snippets/code/doc_src_qttest.pro new file mode 100644 index 0000000..73d210e --- /dev/null +++ b/doc/src/snippets/code/doc_src_qttest.pro @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [1] +CONFIG += qtestlib +#! [1] diff --git a/doc/src/snippets/code/doc_src_qtuiloader.qdoc b/doc/src/snippets/code/doc_src_qtuiloader.cpp index b8d8019..de35e78 100644 --- a/doc/src/snippets/code/doc_src_qtuiloader.qdoc +++ b/doc/src/snippets/code/doc_src_qtuiloader.cpp @@ -38,11 +38,6 @@ ** ****************************************************************************/ -//! [0] -CONFIG += uitools -//! [0] - - //! [1] #include <QtUiTools> //! [1] diff --git a/doc/src/snippets/code/doc_src_qtuiloader.pro b/doc/src/snippets/code/doc_src_qtuiloader.pro new file mode 100644 index 0000000..a050213 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtuiloader.pro @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [0] +CONFIG += uitools +#! [0] diff --git a/doc/src/snippets/code/doc_src_qtxml.cpp b/doc/src/snippets/code/doc_src_qtxml.cpp new file mode 100644 index 0000000..5413fd2 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtxml.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +#include <QtXml> +//! [0] diff --git a/doc/src/snippets/code/doc_src_qtxml.pro b/doc/src/snippets/code/doc_src_qtxml.pro new file mode 100644 index 0000000..d69b2ce --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtxml.pro @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [1] +QT += xml +#! [1] diff --git a/doc/src/snippets/code/doc_src_qtxml.qdoc b/doc/src/snippets/code/doc_src_qtxml.qdoc index 6576815..1e864ea 100644 --- a/doc/src/snippets/code/doc_src_qtxml.qdoc +++ b/doc/src/snippets/code/doc_src_qtxml.qdoc @@ -38,21 +38,6 @@ ** ****************************************************************************/ -//! [0] -#include <QtXml> -//! [0] - - -//! [1] -QT += xml -//! [1] - - -//! [2] -QT += xml -//! [2] - - //! [3] <quote>A quotation.</quote> //! [3] diff --git a/doc/src/snippets/code/doc_src_qtxmlpatterns.cpp b/doc/src/snippets/code/doc_src_qtxmlpatterns.cpp new file mode 100644 index 0000000..2c3235c --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtxmlpatterns.cpp @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +//! [0] +#include <QtXmlPatterns> +//! [0] diff --git a/doc/src/snippets/code/doc_src_qtxmlpatterns.pro b/doc/src/snippets/code/doc_src_qtxmlpatterns.pro new file mode 100644 index 0000000..61ee910 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtxmlpatterns.pro @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +#! [1] +QT += xmlpatterns +#! [1] diff --git a/doc/src/snippets/code/doc_src_qtxmlpatterns.qdoc b/doc/src/snippets/code/doc_src_qtxmlpatterns.qdoc index 560cc53..22e2dde 100644 --- a/doc/src/snippets/code/doc_src_qtxmlpatterns.qdoc +++ b/doc/src/snippets/code/doc_src_qtxmlpatterns.qdoc @@ -42,15 +42,6 @@ void wrapInFunction() { -//! [0] -#include <QtXmlPatterns> -//! [0] - - -//! [1] -QT += xmlpatterns -//! [1] - //! [2] xmlpatterns myQuery.xq //! [2] diff --git a/doc/src/snippets/code/doc_src_qvarlengtharray.qdoc b/doc/src/snippets/code/doc_src_qvarlengtharray.cpp index a938330..a938330 100644 --- a/doc/src/snippets/code/doc_src_qvarlengtharray.qdoc +++ b/doc/src/snippets/code/doc_src_qvarlengtharray.cpp diff --git a/doc/src/snippets/declarative/qml-intro/hello-world1.qml b/doc/src/snippets/code/doc_src_resources.cpp index 81ad333..b965cbe 100644 --- a/doc/src/snippets/declarative/qml-intro/hello-world1.qml +++ b/doc/src/snippets/code/doc_src_resources.cpp @@ -38,16 +38,17 @@ ** ****************************************************************************/ -//! [document] -import QtQuick 1.0 +//! [4] +QResource::registerResource("/path/to/myresource.rcc"); +//! [4] -Rectangle { - id: myRectangle - width: 500 - height: 400 - Text { text: "Hello World!" } - - color: "lightgray" +//! [5] +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + Q_INIT_RESOURCE(graphlib); + ... + return app.exec(); } -//! [document] +//! [5] diff --git a/doc/src/snippets/code/doc_src_resources.qdoc b/doc/src/snippets/code/doc_src_resources.qdoc index c524ae7..0b727da 100644 --- a/doc/src/snippets/code/doc_src_resources.qdoc +++ b/doc/src/snippets/code/doc_src_resources.qdoc @@ -63,19 +63,3 @@ //! [3] rcc -binary myresource.qrc -o myresource.rcc //! [3] - - -//! [4] -QResource::registerResource("/path/to/myresource.rcc"); -//! [4] - - -//! [5] -int main(int argc, char *argv[]) -{ - QApplication app(argc, argv); - Q_INIT_RESOURCE(graphlib); - ... - return app.exec(); -} -//! [5] diff --git a/doc/src/snippets/code/doc_src_richtext.cpp b/doc/src/snippets/code/doc_src_richtext.cpp new file mode 100644 index 0000000..8de5f4c --- /dev/null +++ b/doc/src/snippets/code/doc_src_richtext.cpp @@ -0,0 +1,85 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QTextDocument *newDocument = new QTextDocument; +//! [0] + + +//! [1] +QTextEdit *editor = new QTextEdit; +QTextDocument *editorDocument = editor->document(); +//! [1] + + +//! [2] +QTextEdit *editor = new QTextEdit(parent); +editor->setHtml(aStringContainingHTMLtext); +editor->show(); +//! [2] + + +//! [3] +QTextDocument *document = editor->document(); +//! [3] + + +//! [4] +QTextCursor cursor = editor->textCursor(); +//! [4] + + +//! [5] +editor->setTextCursor(cursor); +//! [5] + + +//! [6] +textEdit.show(); + +textCursor.beginEditBlock(); + +for (int i = 0; i < 1000; ++i) { + textCursor.insertBlock(); + textCursor.insertText(paragraphText.at(i)); +} + +textCursor.endEditBlock(); +//! [6] diff --git a/doc/src/snippets/code/doc_src_richtext.qdoc b/doc/src/snippets/code/doc_src_richtext.qdoc index e031d77..2b79fdb 100644 --- a/doc/src/snippets/code/doc_src_richtext.qdoc +++ b/doc/src/snippets/code/doc_src_richtext.qdoc @@ -38,53 +38,6 @@ ** ****************************************************************************/ -//! [0] -QTextDocument *newDocument = new QTextDocument; -//! [0] - - -//! [1] -QTextEdit *editor = new QTextEdit; -QTextDocument *editorDocument = editor->document(); -//! [1] - - -//! [2] -QTextEdit *editor = new QTextEdit(parent); -editor->setHtml(aStringContainingHTMLtext); -editor->show(); -//! [2] - - -//! [3] -QTextDocument *document = editor->document(); -//! [3] - - -//! [4] -QTextCursor cursor = editor->textCursor(); -//! [4] - - -//! [5] -editor->setTextCursor(cursor); -//! [5] - - -//! [6] -textEdit.show(); - -textCursor.beginEditBlock(); - -for (int i = 0; i < 1000; ++i) { - textCursor.insertBlock(); - textCursor.insertText(paragraphText.at(i)); -} - -textCursor.endEditBlock(); -//! [6] - - //! [7] <meta http-equiv="Content-Type" content="text/html; charset=EUC-JP" /> //! [7] diff --git a/doc/src/snippets/code/doc_src_sql-driver.cpp b/doc/src/snippets/code/doc_src_sql-driver.cpp new file mode 100644 index 0000000..56e4f9b --- /dev/null +++ b/doc/src/snippets/code/doc_src_sql-driver.cpp @@ -0,0 +1,82 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [2] +QSqlQuery q; +q.exec("call qtestproc (@outval1, @outval2)"); +q.exec("select @outval1, @outval2"); +q.next(); +qDebug() << q.value(0) << q.value(1); // outputs "42" and "43" +//! [2] + + +//! [10] +// STORED_PROC uses the return statement or returns multiple result sets +QSqlQuery query; +query.setForwardOnly(true); +query.exec("{call STORED_PROC}"); +//! [10] + + +//! [24] +db.setHostName("MyServer"); +db.setDatabaseName("C:\\test.gdb"); +//! [24] + + +//! [25] +// connect to database using the Latin-1 character set +db.setConnectOptions("ISC_DPB_LC_CTYPE=Latin1"); +db.open(); +//! [25] + + +//! [26] +QSqlQuery q; +q.exec("execute procedure my_procedure"); +q.next(); +qDebug() << q.value(0); // outputs the first RETURN/OUT value +//! [26] + + +//! [31] +QSqlDatabase: QMYSQL driver not loaded +QSqlDatabase: available drivers: QMYSQL +//! [31] diff --git a/doc/src/snippets/code/doc_src_sql-driver.qdoc b/doc/src/snippets/code/doc_src_sql-driver.qdoc index 482e38c..46cd1b3 100644 --- a/doc/src/snippets/code/doc_src_sql-driver.qdoc +++ b/doc/src/snippets/code/doc_src_sql-driver.qdoc @@ -59,15 +59,6 @@ END //! [1] -//! [2] -QSqlQuery q; -q.exec("call qtestproc (@outval1, @outval2)"); -q.exec("select @outval1, @outval2"); -q.next(); -qDebug() << q.value(0) << q.value(1); // outputs "42" and "43" -//! [2] - - //! [3] cd $QTDIR/src/plugins/sqldrivers/mysql qmake "INCLUDEPATH+=/usr/local/include" "LIBS+=-L/usr/local/lib -lmysqlclient_r" mysql.pro @@ -116,14 +107,6 @@ set PATH=%PATH%;c:\oracle\bin //! [9] -//! [10] -\\ STORED_PROC uses the return statement or returns multiple result sets -QSqlQuery query; -query.setForwardOnly(true); -query.exec("{call STORED_PROC}"); -//! [10] - - //! [11] cd $QTDIR/src/plugins/sqldrivers/odbc qmake "INCLUDEPATH+=/usr/local/unixODBC/include" "LIBS+=-L/usr/local/unixODBC/lib -lodbc" @@ -212,27 +195,6 @@ nmake //! [23] -//! [24] -db.setHostName("MyServer"); -db.setDatabaseName("C:\\test.gdb"); -//! [24] - - -//! [25] -// connect to database using the Latin-1 character set -db.setConnectOptions("ISC_DPB_LC_CTYPE=Latin1"); -db.open(); -//! [25] - - -//! [26] -QSqlQuery q; -q.exec("execute procedure my_procedure"); -q.next(); -qDebug() << q.value(0); // outputs the first RETURN/OUT value -//! [26] - - //! [27] cd $QTDIR/src/plugins/sqldrivers/ibase qmake "INCLUDEPATH+=/opt/interbase/include" "LIBS+=-L/opt/interbase/lib" ibase.pro @@ -261,11 +223,6 @@ nmake //! [30] -//! [31] -QSqlDatabase: QMYSQL driver not loaded -QSqlDatabase: available drivers: QMYSQL -//! [31] - //! [32] configure -I /usr/include/oracle/10.1.0.3/client -L /usr/lib/oracle/10.1.0.3/client/lib -R /usr/lib/oracle/10.1.0.3/client/lib -lclntsh -lnnz10 make @@ -276,4 +233,3 @@ cd $QTDIR/src/plugins/sqldrivers/oci qmake "INCLUDEPATH+=/usr/include/oracle/10.1.0.3/client" "LIBS+=-L/usr/lib/oracle/10.1.0.3/client/lib -Wl,-rpath,/usr/lib/oracle/10.1.0.3/client/lib -lclntsh -lnnz10" oci.pro make //! [33] - diff --git a/doc/src/snippets/code/doc_src_styles.qdoc b/doc/src/snippets/code/doc_src_styles.cpp index a2a6fa9..a2a6fa9 100644 --- a/doc/src/snippets/code/doc_src_styles.qdoc +++ b/doc/src/snippets/code/doc_src_styles.cpp diff --git a/doc/src/snippets/code/doc_src_stylesheet.cpp b/doc/src/snippets/code/doc_src_stylesheet.cpp new file mode 100644 index 0000000..3faaf2d --- /dev/null +++ b/doc/src/snippets/code/doc_src_stylesheet.cpp @@ -0,0 +1,140 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [21] +qApp->setStyleSheet("QPushButton { color: white }"); +//! [21] + + +//! [22] +myPushButton->setStyleSheet("* { color: blue }"); +//! [22] + + +//! [23] +myPushButton->setStyleSheet("color: blue"); +//! [23] + + +//! [24] +qApp->setStyleSheet("QGroupBox { color: red; } "); +//! [24] + +//! [25] +qApp->setStyleSheet("QGroupBox, QGroupBox * { color: red; }"); +//! [25] + + +//! [26] +class MyPushButton : public QPushButton { + // ... +} + +// ... +qApp->setStyleSheet("MyPushButton { background: yellow; }"); +//! [26] + + +//! [27] +namespace ns { + class MyPushButton : public QPushButton { + // ... + } +} + +// ... +qApp->setStyleSheet("ns--MyPushButton { background: yellow; }"); +//! [27] + + +//! [32] +void CustomWidget::paintEvent(QPaintEvent *) +{ + QStyleOption opt; + opt.init(this); + QPainter p(this); + style()->drawPrimitive(QStyle::PE_Widget, &opt, &p, this); +} +//! [32] + + +//! [88] +qApp->setStyleSheet("QLineEdit { background-color: yellow }"); +//! [88] + + +//! [89] +myDialog->setStyleSheet("QLineEdit { background-color: yellow }"); +//! [89] + + +//! [90] +myDialog->setStyleSheet("QLineEdit#nameEdit { background-color: yellow }"); +//! [90] + + +//! [91] +nameEdit->setStyleSheet("background-color: yellow"); +//! [91] + + +//! [92] +nameEdit->setStyleSheet("color: blue; background-color: yellow"); +//! [92] + + +//! [93] +nameEdit->setStyleSheet("color: blue;" + "background-color: yellow;" + "selection-color: yellow;" + "selection-background-color: blue;"); +//! [93] + + +//! [95] +QLineEdit *nameEdit = new QLineEdit(this); +nameEdit->setProperty("mandatoryField", true); + +QLineEdit *emailEdit = new QLineEdit(this); +emailEdit->setProperty("mandatoryField", true); + +QSpinBox *ageSpinBox = new QSpinBox(this); +ageSpinBox->setProperty("mandatoryField", true); +//! [95] diff --git a/doc/src/snippets/code/doc_src_stylesheet.qdoc b/doc/src/snippets/code/doc_src_stylesheet.qdoc index 9b8a3b5..99b31c9 100644 --- a/doc/src/snippets/code/doc_src_stylesheet.qdoc +++ b/doc/src/snippets/code/doc_src_stylesheet.qdoc @@ -170,53 +170,6 @@ LI.red.level {} /* a=0 b=2 c=1 -> specificity = 21 */ //! [20] -//! [21] -qApp->setStyleSheet("QPushButton { color: white }"); -//! [21] - - -//! [22] -myPushButton->setStyleSheet("* { color: blue }"); -//! [22] - - -//! [23] -myPushButton->setStyleSheet("color: blue"); -//! [23] - - -//! [24] -qApp->setStyleSheet("QGroupBox { color: red; } "); -//! [24] - - -//! [25] -qApp->setStyleSheet("QGroupBox, QGroupBox * { color: red; }"); -//! [25] - - -//! [26] -class MyPushButton : public QPushButton { - // ... -} - -// ... -qApp->setStyleSheet("MyPushButton { background: yellow; }"); -//! [26] - - -//! [27] -namespace ns { - class MyPushButton : public QPushButton { - // ... - } -} - -// ... -qApp->setStyleSheet("ns--MyPushButton { background: yellow; }"); -//! [27] - - //! [28] MyLabel { qproperty-pixmap: url(pixmap.png); } MyGroupBox { qproperty-titleColor: rgb(100, 200, 100); } @@ -234,17 +187,6 @@ QToolButton { background-color: red; border: none; } //! [31] -//! [32] -void CustomWidget::paintEvent(QPaintEvent *) -{ - QStyleOption opt; - opt.init(this); - QPainter p(this); - style()->drawPrimitive(QStyle::PE_Widget, &opt, &p, this); -} -//! [32] - - //! [33] QTreeView { alternate-background-color: blue; @@ -617,56 +559,11 @@ QPushButton { color: palette(dark); } //! [87] -//! [88] -qApp->setStyleSheet("QLineEdit { background-color: yellow }"); -//! [88] - - -//! [89] -myDialog->setStyleSheet("QLineEdit { background-color: yellow }"); -//! [89] - - -//! [90] -myDialog->setStyleSheet("QLineEdit#nameEdit { background-color: yellow }"); -//! [90] - - -//! [91] -nameEdit->setStyleSheet("background-color: yellow"); -//! [91] - - -//! [92] -nameEdit->setStyleSheet("color: blue; background-color: yellow"); -//! [92] - - -//! [93] -nameEdit->setStyleSheet("color: blue;" - "background-color: yellow;" - "selection-color: yellow;" - "selection-background-color: blue;"); -//! [93] - - //! [94] *[mandatoryField="true"] { background-color: yellow } //! [94] -//! [95] -QLineEdit *nameEdit = new QLineEdit(this); -nameEdit->setProperty("mandatoryField", true); - -QLineEdit *emailEdit = new QLineEdit(this); -emailEdit->setProperty("mandatoryField", true); - -QSpinBox *ageSpinBox = new QSpinBox(this); -ageSpinBox->setProperty("mandatoryField", true); -//! [95] - - //! [96] QPushButton#evilButton { background-color: red } //! [96] diff --git a/doc/src/snippets/code/doc_src_unicode.qdoc b/doc/src/snippets/code/doc_src_unicode.cpp index 4415cf2..4415cf2 100644 --- a/doc/src/snippets/code/doc_src_unicode.qdoc +++ b/doc/src/snippets/code/doc_src_unicode.cpp diff --git a/doc/src/snippets/code/doc_src_unix-signal-handlers.qdoc b/doc/src/snippets/code/doc_src_unix-signal-handlers.cpp index fd5f386..fd5f386 100644 --- a/doc/src/snippets/code/doc_src_unix-signal-handlers.qdoc +++ b/doc/src/snippets/code/doc_src_unix-signal-handlers.cpp diff --git a/doc/src/snippets/declarative/animation-signalhandler.qml b/doc/src/snippets/code/doc_src_wince-customization.cpp index 416417f..90c2207 100644 --- a/doc/src/snippets/declarative/animation-signalhandler.qml +++ b/doc/src/snippets/code/doc_src_wince-customization.cpp @@ -37,19 +37,22 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ -//![0] -import QtQuick 1.0 -Rectangle { - id: rect - width: 100; height: 100 - color: "red" +//! [9] +wchar_t* libraries[] = { + L"QtCore4.dll", + L"QtGui4.dll", + 0 +}; - MouseArea { - anchors.fill: parent - onClicked: PropertyAnimation { target: rect; properties: "x,y"; to: 50; duration: 1000 } +for (int i = 0; libraries[i] != 0; ++i) { + HINSTANCE instance = LoadLibraryW(libraries[i]); + OutputDebugStringW(libraries[i]); + if (instance != NULL) { + OutputDebugStringW(L" : Successfully instantiated\n"); + FreeLibrary(instance); + } else { + OutputDebugStringW(L" : Could not be loaded\n"); } } - -//![0] - +//! [9] diff --git a/doc/src/snippets/code/doc_src_wince-customization.qdoc b/doc/src/snippets/code/doc_src_wince-customization.qdoc index 657786f..ab09222 100644 --- a/doc/src/snippets/code/doc_src_wince-customization.qdoc +++ b/doc/src/snippets/code/doc_src_wince-customization.qdoc @@ -89,22 +89,3 @@ if(equals(TEMPLATE_PREFIX, "vc") | equals(TEMPLATE, "vc*")) { DEFINES -= _M_ARM } //! [8] - -//! [9] -wchar_t* libraries[] = { - L"QtCore4.dll", - L"QtGui4.dll", - 0 -}; - -for (int i = 0; libraries[i] != 0; ++i) { - HINSTANCE instance = LoadLibraryW(libraries[i]); - OutputDebugStringW(libraries[i]); - if (instance != NULL) { - OutputDebugStringW(L" : Successfully instantiated\n"); - FreeLibrary(instance); - } else { - OutputDebugStringW(L" : Could not be loaded\n"); - } -} -//! [9] diff --git a/doc/src/snippets/code/src_corelib_kernel_qmetaobject.cpp b/doc/src/snippets/code/src_corelib_kernel_qmetaobject.cpp index 7a752b1..86bad5e 100644 --- a/doc/src/snippets/code/src_corelib_kernel_qmetaobject.cpp +++ b/doc/src/snippets/code/src_corelib_kernel_qmetaobject.cpp @@ -43,7 +43,7 @@ void wrapInFunction() { //! [0] -class MyClass +class MyClass : public QObject { Q_OBJECT Q_CLASSINFO("author", "Sabrina Schweinsteiger") diff --git a/doc/src/snippets/code/src_gui_painting_qpen.cpp b/doc/src/snippets/code/src_gui_painting_qpen.cpp index 6973e0c..8674516 100644 --- a/doc/src/snippets/code/src_gui_painting_qpen.cpp +++ b/doc/src/snippets/code/src_gui_painting_qpen.cpp @@ -47,7 +47,7 @@ painter.setPen(pen); //! [1] QPainter painter(this); -QPen pen(); // creates a default pen +QPen pen; // creates a default pen pen.setStyle(Qt::DashDotLine); pen.setWidth(3); diff --git a/doc/src/snippets/declarative/qml-intro/anchors2.qml b/doc/src/snippets/declarative/Button.qml index 2c4ce11..214dfea 100644 --- a/doc/src/snippets/declarative/qml-intro/anchors2.qml +++ b/doc/src/snippets/declarative/Button.qml @@ -41,18 +41,27 @@ //! [document] import QtQuick 1.0 +//! [parent begin] Rectangle { - id: myWin - width: 500 - height: 400 - - Image { - id: image1 - source: "images/qt-logo.svg" - width: 150; height: 150 - anchors.bottom: myWin.bottom - anchors.horizontalCenter: myWin.horizontalCenter - anchors.bottomMargin: 10 - } +//! [parent begin] + +//! [property alias] +property alias buttonLabel: label.text +Text { + id: label + text: "empty label" +} + //! [property alias] + +//! [id alias] + property alias buttonImage: image + + Image {id: image} +//! [id alias] +//! [parent end] } +//! [parent end] + //! [document] + + diff --git a/doc/src/snippets/declarative/animation-elements.qml b/doc/src/snippets/declarative/animation-elements.qml deleted file mode 100644 index d9bfc28..0000000 --- a/doc/src/snippets/declarative/animation-elements.qml +++ /dev/null @@ -1,66 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). -** All rights reserved. -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ -//![0] -import QtQuick 1.0 - -Row { - -//![color] -Rectangle { - width: 100; height: 100 - - ColorAnimation on color { from: "red"; to: "yellow"; duration: 1000 } -} -//![color] - -//![rotation] -Item { - width: 300; height: 300 - - Rectangle { - width: 100; height: 100; anchors.centerIn: parent - color: "red" - - RotationAnimation on rotation { to: 90; direction: RotationAnimation.Clockwise } - } -} -//![rotation] - -} diff --git a/doc/src/snippets/declarative/animation-groups.qml b/doc/src/snippets/declarative/animation-groups.qml deleted file mode 100644 index f29ea48..0000000 --- a/doc/src/snippets/declarative/animation-groups.qml +++ /dev/null @@ -1,104 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). -** All rights reserved. -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ -import QtQuick 1.0 - -Row { - -//![0] -Rectangle { - id: rect - width: 120; height: 200 - - Image { - id: img - source: "pics/qt.png" - anchors.horizontalCenter: parent.horizontalCenter - y: 0 - - SequentialAnimation on y { - loops: Animation.Infinite - NumberAnimation { to: rect.height - img.height; easing.type: Easing.OutBounce; duration: 2000 } - PauseAnimation { duration: 1000 } - NumberAnimation { to: 0; easing.type: Easing.OutQuad; duration: 1000 } - } - } -} -//![0] - -//![1] -Rectangle { - id: redRect - width: 100; height: 100 - color: "red" - - MouseArea { id: mouseArea; anchors.fill: parent } - - states: State { - name: "pressed"; when: mouseArea.pressed - PropertyChanges { target: redRect; color: "blue"; y: mouseArea.mouseY; width: mouseArea.mouseX } - } - - transitions: Transition { - - SequentialAnimation { - ColorAnimation { duration: 200 } - PauseAnimation { duration: 100 } - - ParallelAnimation { - NumberAnimation { - duration: 500 - easing.type: Easing.OutBounce - targets: redRect - properties: "y" - } - - NumberAnimation { - duration: 800 - easing.type: Easing.InOutQuad - targets: redRect - properties: "width" - } - } - } - } -} -//![1] - -} diff --git a/doc/src/snippets/declarative/animation-propertyvaluesource.qml b/doc/src/snippets/declarative/animation-propertyvaluesource.qml deleted file mode 100644 index 6f93967..0000000 --- a/doc/src/snippets/declarative/animation-propertyvaluesource.qml +++ /dev/null @@ -1,51 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). -** All rights reserved. -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ -//![0] -import QtQuick 1.0 - -Rectangle { - width: 100; height: 100 - color: "red" - - PropertyAnimation on x { to: 50; duration: 1000; loops: Animation.Infinite } - PropertyAnimation on y { to: 50; duration: 1000; loops: Animation.Infinite } -} -//![0] - diff --git a/doc/src/snippets/declarative/animation.qml b/doc/src/snippets/declarative/animation.qml new file mode 100644 index 0000000..ae6142d --- /dev/null +++ b/doc/src/snippets/declarative/animation.qml @@ -0,0 +1,226 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +//! [document] +import QtQuick 1.0 + + +//! [parent begin] +Rectangle { +//! [parent begin] + width: 200; height: 600 + id: screen + +Column { + spacing: 12 +//! [direct property change] +Rectangle { + id: blob + width: 75; height: 75 + color: "blue" + + MouseArea { + anchors.fill: parent + onClicked: blob.color = "green" + } +} +//! [direct property change] + +//! [property animation] +Rectangle { + id: flashingblob + width: 75; height: 75 + color: "blue" + opacity: 1.0 + + MouseArea { + anchors.fill: parent + onClicked: { + animateColor.start() + animateOpacity.start() + } + } + + PropertyAnimation {id: animateColor; target: flashingblob; properties: "color"; to: "green"; duration: 100} + + NumberAnimation { + id: animateOpacity + target: flashingblob + properties: "opacity" + from: 0.99 + to: 1.0 + loops: Animation.Infinite + easing {type: Easing.OutBack; overshoot: 500} + } +} +//! [property animation] + +//! [transition animation] +Rectangle { + width: 75; height: 75 + id: button + state: "RELEASED" + + MouseArea { + anchors.fill: parent + onPressed: button.state = "PRESSED" + onReleased: button.state = "RELEASED" + } + + states: [ + State { + name: "PRESSED" + PropertyChanges { target: button; color: "lightblue"} + }, + State { + name: "RELEASED" + PropertyChanges { target: button; color: "lightsteelblue"} + } + ] + + transitions: [ + Transition { + from: "PRESSED" + to: "RELEASED" + ColorAnimation { target: button; duration: 100} + }, + Transition { + from: "RELEASED" + to: "PRESSED" + ColorAnimation { target: button; duration: 100} + } + ] +} +//! [transition animation] + +Rectangle { + width: 75; height: 75 + id: wildcard + color: "green" +//! [wildcard animation] + transitions: + Transition { + to: "*" + ColorAnimation { target: button; duration: 100} + } +//! [wildcard animation] + + MouseArea { + anchors.fill: parent + onPressed: { + ball.x = 10 + ball.color = "red" + } + onReleased: { + ball.x = screen.width / 2 + ball.color = "salmon" + } + } +} + +//! [behavior animation] +Rectangle { + width: 75; height: 75; radius: width + id: ball + color: "salmon" + + Behavior on x { + NumberAnimation { + id: bouncebehavior + easing { + type: Easing.OutElastic + amplitude: 1.0 + period: 0.5 + } + } + } + Behavior on y { + animation: bouncebehavior + } + Behavior { + ColorAnimation { target: ball; duration: 100 } + } +} +//! [behavior animation] + +//! [sequential animation] +Rectangle { + id: banner + width: 150; height: 100; border.color: "black" + + Column { + anchors.centerIn: parent + Text { + id: code + text: "Code less." + opacity: 0.01 + } + Text { + id: create + text: "Create more." + opacity: 0.01 + } + Text { + id: deploy + text: "Deploy everywhere." + opacity: 0.01 + } + } + + MouseArea { + anchors.fill: parent + onPressed: playbanner.start() + } + + SequentialAnimation { + id: playbanner + running: false + NumberAnimation { target: code; property: "opacity"; to: 1.0; duration: 200} + NumberAnimation { target: create; property: "opacity"; to: 1.0; duration: 200} + NumberAnimation { target: deploy; property: "opacity"; to: 1.0; duration: 200} + } +} +//! [sequential animation] + +}//end of col +//! [parent end] +} +//! [parent end] + +//! [document] diff --git a/doc/src/snippets/declarative/animation-easing.qml b/doc/src/snippets/declarative/bestpractices/group.qml index 64ba44c..8a2b398 100644 --- a/doc/src/snippets/declarative/animation-easing.qml +++ b/doc/src/snippets/declarative/bestpractices/group.qml @@ -37,15 +37,40 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ -//![0] + + +//! [document] import QtQuick 1.0 +//! [parent begin] +Rectangle { +//! [parent begin] + width: 175; height: 175; color: "white" + +Rectangle{ +width: 170; height: 170 +//! [not grouped] +border.width: 1 +border.color: "red" +anchors.bottom: parent.bottom +anchors.left: parent.left +//! [not grouped] +} Rectangle { width: 100; height: 100 + +//! [grouped] +border { + width: 1; color: "red" - - PropertyAnimation on x { to: 50; duration: 1000; easing.type: Easing.OutBounce } - PropertyAnimation on y { to: 50; duration: 1000; easing.type: Easing.OutBounce } } -//![0] - +anchors { + bottom: parent.bottom; + left: parent.left +} +//! [grouped] +} +//! [parent end] +} +//! [parent end] +//! [document] diff --git a/doc/src/snippets/declarative/events.qml b/doc/src/snippets/declarative/events.qml new file mode 100644 index 0000000..3dc44f2 --- /dev/null +++ b/doc/src/snippets/declarative/events.qml @@ -0,0 +1,141 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +//![document] +import QtQuick 1.0 + +//![parent begin] +Rectangle { +//![parent begin] + + id: screen + width: 400; height: 500 + +//! [signal declaration] + signal trigger + signal send (string notice) + signal perform (string task, variant object) +//! [signal declaration] + +//! [signal handler declaration] +onTrigger: console.log("trigger signal emitted") + +onSend: { + console.log("send signal emitted with notice: " + notice) +} + +onPerform: console.log("perform signal emitted") +//! [signal handler declaration] + +//! [automatic signals] +Rectangle { + id: sprite + width: 25; height: 25 + x: 50; y: 15 + + onXChanged: console.log("x property changed, emitted xChanged signal") + onYChanged: console.log("y property changed, emitted yChanged signal") +} +//! [automatic signals] + +//! [signal emit] +Rectangle { + id: messenger + + signal send( string person, string notice) + + onSend: { + console.log("For " + person + ", the notice is: " + notice) + } + + Component.onCompleted: messenger.send("Tom", "the door is ajar.") +} +//! [signal emit] + +//! [connect method] +Rectangle { + id: relay + + signal send( string person, string notice) + onSend: console.log("Send signal to: " + person + ", " + notice) + + Component.onCompleted: { + relay.send.connect(sendToPost) + relay.send.connect(sendToTelegraph) + relay.send.connect(sendToEmail) + relay.send("Tom", "Happy Birthday") + } + + function sendToPost(person, notice) { + console.log("Sending to post: " + person + ", " + notice) + } + function sendToTelegraph(person, notice) { + console.log("Sending to telegraph: " + person + ", " + notice) + } + function sendToEmail(person, notice) { + console.log("Sending to email: " + person + ", " + notice) + } +} +//! [connect method] + +//! [forward signal] +Rectangle { + id: forwarder + width: 100; height: 100 + + signal send() + onSend: console.log("Send clicked") + + MouseArea { + id: mousearea + anchors.fill: parent + onClicked: console.log("MouseArea clicked") + } + Component.onCompleted: { + mousearea.clicked.connect(send) + } +} +//! [forward signal] + +//! [connect method] +//![parent end] +} +//![parent end] + +//![document] diff --git a/doc/src/snippets/declarative/focus/advancedFocus.qml b/doc/src/snippets/declarative/focus/advancedFocus.qml index fda37c1..409663b 100644 --- a/doc/src/snippets/declarative/focus/advancedFocus.qml +++ b/doc/src/snippets/declarative/focus/advancedFocus.qml @@ -4,7 +4,7 @@ ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** -** This file is part of the FOO module of the Qt Toolkit. +** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:BSD$ ** You may use this file under the terms of the BSD license as follows: diff --git a/doc/src/snippets/declarative/focus/basicwidget.qml b/doc/src/snippets/declarative/focus/basicwidget.qml index b74c1cd..bf834b4 100644 --- a/doc/src/snippets/declarative/focus/basicwidget.qml +++ b/doc/src/snippets/declarative/focus/basicwidget.qml @@ -4,7 +4,7 @@ ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** -** This file is part of the FOO module of the Qt Toolkit. +** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:BSD$ ** You may use this file under the terms of the BSD license as follows: diff --git a/doc/src/snippets/declarative/focus/focusscopewidget.qml b/doc/src/snippets/declarative/focus/focusscopewidget.qml index 7421a63..6a97512 100644 --- a/doc/src/snippets/declarative/focus/focusscopewidget.qml +++ b/doc/src/snippets/declarative/focus/focusscopewidget.qml @@ -4,7 +4,7 @@ ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** -** This file is part of the FOO module of the Qt Toolkit. +** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:BSD$ ** You may use this file under the terms of the BSD license as follows: @@ -37,6 +37,7 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ +//! [document] import QtQuick 1.0 //! [focusscope window] @@ -59,3 +60,4 @@ Rectangle { } //! [focusscope window] +//! [document] diff --git a/doc/src/snippets/declarative/focus/myclickablewidget.qml b/doc/src/snippets/declarative/focus/myclickablewidget.qml index 4777dd1..30b1c69 100644 --- a/doc/src/snippets/declarative/focus/myclickablewidget.qml +++ b/doc/src/snippets/declarative/focus/myclickablewidget.qml @@ -4,7 +4,7 @@ ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** -** This file is part of the FOO module of the Qt Toolkit. +** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:BSD$ ** You may use this file under the terms of the BSD license as follows: diff --git a/doc/src/snippets/declarative/focus/myfocusscopewidget.qml b/doc/src/snippets/declarative/focus/myfocusscopewidget.qml index c87a47e..6462301 100644 --- a/doc/src/snippets/declarative/focus/myfocusscopewidget.qml +++ b/doc/src/snippets/declarative/focus/myfocusscopewidget.qml @@ -4,7 +4,7 @@ ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** -** This file is part of the FOO module of the Qt Toolkit. +** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:BSD$ ** You may use this file under the terms of the BSD license as follows: @@ -37,12 +37,13 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ +//! [document] import QtQuick 1.0 //! [widget in focusscope] FocusScope { - //FocusScope needs to bind to visual properties of the children + //FocusScope needs to bind to visual properties of the Rectangle property alias color: rectangle.color x: rectangle.x; y: rectangle.y width: rectangle.width; height: rectangle.height @@ -64,3 +65,4 @@ FocusScope { } } //! [widget in focusscope] +//! [document] diff --git a/doc/src/snippets/declarative/focus/mywidget.qml b/doc/src/snippets/declarative/focus/mywidget.qml index 86d2d0f..0cca747 100644 --- a/doc/src/snippets/declarative/focus/mywidget.qml +++ b/doc/src/snippets/declarative/focus/mywidget.qml @@ -4,7 +4,7 @@ ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** -** This file is part of the FOO module of the Qt Toolkit. +** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:BSD$ ** You may use this file under the terms of the BSD license as follows: @@ -37,10 +37,10 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ +//! [document] import QtQuick 1.0 //! [mywidget] -//MyWidget code Rectangle { id: widget color: "lightsteelblue"; width: 175; height: 25; radius: 10; smooth: true diff --git a/doc/src/snippets/declarative/focus/widget.qml b/doc/src/snippets/declarative/focus/widget.qml index a5053d9..a3a726e 100644 --- a/doc/src/snippets/declarative/focus/widget.qml +++ b/doc/src/snippets/declarative/focus/widget.qml @@ -4,7 +4,7 @@ ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** -** This file is part of the FOO module of the Qt Toolkit. +** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:BSD$ ** You may use this file under the terms of the BSD license as follows: diff --git a/doc/src/snippets/declarative/grid/grid-spacing.qml b/doc/src/snippets/declarative/grid-spacing.qml index 8914ce3..8914ce3 100644 --- a/doc/src/snippets/declarative/grid/grid-spacing.qml +++ b/doc/src/snippets/declarative/grid-spacing.qml diff --git a/doc/src/snippets/declarative/grid/grid-items.qml b/doc/src/snippets/declarative/grid/grid-items.qml deleted file mode 100644 index 3c60d12..0000000 --- a/doc/src/snippets/declarative/grid/grid-items.qml +++ /dev/null @@ -1,58 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). -** All rights reserved. -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -import QtQuick 1.0 - -Rectangle { - width: 112; height: 112 - color: "#303030" - - Grid { - anchors.horizontalCenter: parent.horizontalCenter - anchors.verticalCenter: parent.verticalCenter - columns: 2 - spacing: 6 - - Rectangle { color: "#aa6666"; width: 50; height: 50 } - Rectangle { color: "#aaaa66"; width: 50; height: 50 } - Rectangle { color: "#9999aa"; width: 50; height: 50 } - Rectangle { color: "#6666aa"; width: 50; height: 50 } - } -} diff --git a/doc/src/snippets/declarative/grid/grid-no-spacing.qml b/doc/src/snippets/declarative/grid/grid-no-spacing.qml deleted file mode 100644 index 7c8b0f8..0000000 --- a/doc/src/snippets/declarative/grid/grid-no-spacing.qml +++ /dev/null @@ -1,57 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). -** All rights reserved. -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -import QtQuick 1.0 - -Rectangle { - width: 112; height: 112 - color: "#303030" - - Grid { - anchors.horizontalCenter: parent.horizontalCenter - anchors.verticalCenter: parent.verticalCenter - columns: 2 - - Rectangle { color: "#aa6666"; width: 50; height: 50 } - Rectangle { color: "#aaaa66"; width: 50; height: 50 } - Rectangle { color: "#9999aa"; width: 50; height: 50 } - Rectangle { color: "#6666aa"; width: 50; height: 50 } - } -} diff --git a/doc/src/snippets/code/doc_src_phonon.qdoc b/doc/src/snippets/declarative/imports/best-practices.qml index 61ee189..17e5b7a 100644 --- a/doc/src/snippets/code/doc_src_phonon.qdoc +++ b/doc/src/snippets/declarative/imports/best-practices.qml @@ -38,16 +38,12 @@ ** ****************************************************************************/ -//! [0] -QT += phonon -//! [0] +//! [imports] +import QtQuick 1.0 +import QtWebKit 1.0 +import "subdirectory" +import "script.js" +//! [imports] - -//! [1] -QT += phonon -//! [1] - - -//! [2] -#include <Phonon/MediaObject> -//! [2] +Item { +} diff --git a/doc/src/snippets/declarative/imports/chart.qml b/doc/src/snippets/declarative/imports/chart.qml new file mode 100644 index 0000000..6de02c1 --- /dev/null +++ b/doc/src/snippets/declarative/imports/chart.qml @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [import] +import Charts 1.0 +//! [import] + +Item { +} diff --git a/doc/src/snippets/declarative/imports/installed-module.qml b/doc/src/snippets/declarative/imports/installed-module.qml new file mode 100644 index 0000000..288bdd3 --- /dev/null +++ b/doc/src/snippets/declarative/imports/installed-module.qml @@ -0,0 +1,47 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [imports] +import QtQuick 1.0 +import com.nokia.qml.mymodule 1.0 +//! [imports] + +Item { +} diff --git a/doc/src/snippets/code/doc.src.qtscripttools.qdoc b/doc/src/snippets/declarative/imports/merged-named-imports.qml index 76840b3..366e76e 100644 --- a/doc/src/snippets/code/doc.src.qtscripttools.qdoc +++ b/doc/src/snippets/declarative/imports/merged-named-imports.qml @@ -38,11 +38,10 @@ ** ****************************************************************************/ -//! [0] - #include <QtScriptTools> -//! [0] +//! [imports] +import QtQuick 1.0 as Nokia +import Ovi 1.0 as Nokia +//! [imports] - -//! [1] - QT += scripttools -//! [1] +Item { +} diff --git a/doc/src/snippets/declarative/qml-intro/hello-world4.qml b/doc/src/snippets/declarative/imports/named-imports.qml index 832e37d..a8fa743 100644 --- a/doc/src/snippets/declarative/qml-intro/hello-world4.qml +++ b/doc/src/snippets/declarative/imports/named-imports.qml @@ -38,24 +38,24 @@ ** ****************************************************************************/ -import QtQuick 1.0 +//! [imports] +import QtQuick 1.0 as QtLibrary +import "../MyComponents" as MyComponents +import com.nokia.qml.mymodule 1.0 as MyModule +//! [imports] -Rectangle { - id: myRectangle - width: 500 - height: 400 - - Text { - text: "<h1>Hello world again</h1>" - color: "#002288" - x: 100; y: 100 +Item { + //! [imported items] + QtLibrary.Rectangle { + // ... } -//! [added an image] - Image { - source: "images/qt-logo.svg" + MyComponents.Slider { + // ... } -//! [added an image] - color: "lightgray" + MyModule.SomeComponent { + // ... + } + //! [imported items] } diff --git a/doc/src/snippets/declarative/imports/network-imports.qml b/doc/src/snippets/declarative/imports/network-imports.qml new file mode 100644 index 0000000..54e177a --- /dev/null +++ b/doc/src/snippets/declarative/imports/network-imports.qml @@ -0,0 +1,47 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [imports] +import "http://www.my-server.com/MyQMLProject/MyComponents" +import "http://www.my-server.com/MyQMLProject/MyComponents" 1.0 +//! [imports] + +Item { +} diff --git a/doc/src/snippets/declarative/imports/qtquick-1.0.qml b/doc/src/snippets/declarative/imports/qtquick-1.0.qml new file mode 100644 index 0000000..e2a642d --- /dev/null +++ b/doc/src/snippets/declarative/imports/qtquick-1.0.qml @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [import] +import QtQuick 1.0 +//! [import] + +Item { +} diff --git a/doc/src/snippets/declarative/imports/timeexample.qml b/doc/src/snippets/declarative/imports/timeexample.qml new file mode 100644 index 0000000..24eafd7 --- /dev/null +++ b/doc/src/snippets/declarative/imports/timeexample.qml @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [import] +import com.nokia.TimeExample 1.0 +//! [import] + +Item { +} diff --git a/doc/src/snippets/declarative/qml-intro/transformations1.qml b/doc/src/snippets/declarative/listview-decorations.qml index 7be79c8..9ba9b70 100644 --- a/doc/src/snippets/declarative/qml-intro/transformations1.qml +++ b/doc/src/snippets/declarative/listview-decorations.qml @@ -41,40 +41,71 @@ //! [document] import QtQuick 1.0 +//! [parent begin] Rectangle { - id: myWin - width: 500 - height: 400 +//! [parent begin] + width: 550; height: 220; color: "white" - Image { - id: image1 - source: "images/qt-logo.svg" - width: 150; height: 150 - anchors.bottom: myWin.bottom - anchors.horizontalCenter: myWin.horizontalCenter - anchors.bottomMargin: 10 - - transform: Rotation { - origin.x: 75; origin.y: 75 - axis{ x: 0; y: 0; z:1 } angle: -90 - } - - } +//! [model] +ListModel { + id: nameModel + ListElement { name: "Alice" } + ListElement { name: "Bob" } + ListElement { name: "Jane" } + ListElement { name: "Harry" } + ListElement { name: "Wendy" } +} +//! [model] +//! [delegate] +Component { + id: nameDelegate Text { - text: "<h2>The Qt Logo -- taking it easy</h2>" - anchors.bottom: image1.top - anchors.horizontalCenter: myWin.horizontalCenter - anchors.bottomMargin: 15 + text: name; + font.pixelSize: 24 + } +} +//! [delegate] - transform: [ - Scale { xScale: 1.5; yScale: 1.2 } , +//! [decorations] +ListView { + anchors.fill: parent + clip: true + model: nameModel + delegate: nameDelegate + header: bannercomponent + footer: Rectangle { + width: parent.width; height: 30; + gradient: clubcolors + } + highlight: Rectangle { + width: parent.width + color: "lightgray" + } +} - Rotation { - origin.x: 75; origin.y: 75 - axis{ x: 0; y: 0; z:1 } angle: -45 - } - ] +Component { //instantiated when header is processed + id: bannercomponent + Rectangle { + id: banner + width: parent.width; height: 50 + gradient: clubcolors + border {color: "#9EDDF2"; width: 2} + Text { + anchors.centerIn: parent + text: "Club Members" + font.pixelSize: 32 + } } } +Gradient { + id: clubcolors + GradientStop { position: 0.0; color: "#8EE2FE"} + GradientStop { position: 0.66; color: "#7ED2EE"} +} +//! [decorations] + +//! [parent end] +} +//! [parent end] //! [document] diff --git a/doc/src/snippets/declarative/qml-intro/states1.qml b/doc/src/snippets/declarative/listview-sections.qml index 270d6c3..74c96dd 100644 --- a/doc/src/snippets/declarative/qml-intro/states1.qml +++ b/doc/src/snippets/declarative/listview-sections.qml @@ -37,58 +37,65 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - //! [document] import QtQuick 1.0 +//! [parent begin] Rectangle { - id: mainRectangle - width: 600 - height: 400 - color: "black" +//! [parent begin] + width: 150; height: 300; color: "white" - Rectangle { - id: sky - width: 600 - height: 200 - y: 0 - color: "lightblue" - } +//! [model] +ListModel { + id: nameModel + ListElement { name: "Alice"; team: "Crypto" } + ListElement { name: "Bob"; team: "Crypto" } + ListElement { name: "Jane"; team: "QA" } + ListElement { name: "Victor"; team: "QA" } + ListElement { name: "Wendy"; team: "Graphics" } +} +//! [model] - Rectangle { - id: ground - width: 600; height: 200 - y: 200 - color: "green" +//! [delegate] +Component { + id: nameDelegate + Text { + text: name; + font.pixelSize: 24 + anchors.left: parent.left + anchors.leftMargin: 2 } +} +//! [delegate] - MouseArea { - id: mousearea - anchors.fill: mainRectangle +//! [section] +ListView { + anchors.fill: parent + model: nameModel + delegate: nameDelegate + focus: true + highlight: Rectangle { + color: "lightblue" + width: parent.width } - - states: [ State { - name: "night" - when: mousearea.pressed == true - PropertyChanges { target: sky; color: "darkblue" } - PropertyChanges { target: ground; color: "black" } - }, - State { - name: "daylight" - when: mousearea.pressed == false - PropertyChanges { target: sky; color: "lightblue" } - PropertyChanges { target: ground; color: "green" } + section { + property: "team" + criteria: ViewSection.FullString + delegate: Rectangle { + color: "#b0dfb0" + width: parent.width + height: childrenRect.height + 4 + Text { anchors.horizontalCenter: parent.horizontalCenter + font.pixelSize: 16 + font.bold: true + text: section + } } - ] + } +} +//! [section] - transitions: [ Transition { - from: "daylight"; to: "night" - ColorAnimation { duration: 1000 } - }, - Transition { - from: "night"; to: "daylight" - ColorAnimation { duration: 500 } - } - ] +//! [parent end] } +//! [parent end] //! [document] diff --git a/doc/src/snippets/declarative/qml-intro/number-animation1.qml b/doc/src/snippets/declarative/listview.qml index ccf2d36..081d2b0 100644 --- a/doc/src/snippets/declarative/qml-intro/number-animation1.qml +++ b/doc/src/snippets/declarative/listview.qml @@ -41,24 +41,47 @@ //! [document] import QtQuick 1.0 +//! [parent begin] Rectangle { - id: mainRec - width: 600 - height: 400 +//! [parent begin] + width: 175; height: 175; color: "white" - Image { - id: image1 - source: "images/qt-logo.svg" - x: 200; y: 100 - width: 100; height: 100 +//! [model] +ListModel { + id: petlist + ListElement { type: "Cat" } + ListElement { type: "Dog" } + ListElement { type: "Mouse" } + ListElement { type: "Rabbit" } + ListElement { type: "Horse" } +} +//! [model] - // Animate a rotation - transformOrigin: Item.Center - NumberAnimation on rotation { - from: 0; to: 360 - duration: 2000 - loops: Animation.Infinite - } +//! [delegate] +Component { + id: petdelegate + Text { + id: label + font.pixelSize: 24 + text: if (index == 0) + label.text = type + " (default)" + else + text: type } } +//! [delegate] + +//! [view] +ListView { + id: view + anchors.fill: parent + + model: petlist + delegate: petdelegate +} +//! [view] + +//! [parent end] +} +//! [parent end] //! [document] diff --git a/doc/src/snippets/declarative/listview/listview-snippet.qml b/doc/src/snippets/declarative/listview/listview-snippet.qml deleted file mode 100644 index f73dec9..0000000 --- a/doc/src/snippets/declarative/listview/listview-snippet.qml +++ /dev/null @@ -1,52 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). -** All rights reserved. -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [document] -import QtQuick 1.0 - -ListView { - width: 50; height: 200 - model: 4 - delegate: Text { - text: index; - font.pixelSize: 40 - } -} -//! [document] diff --git a/doc/src/snippets/declarative/animation-behavioral.qml b/doc/src/snippets/declarative/models/views-models-delegates.qml index 93cf2fa..2f76856 100644 --- a/doc/src/snippets/declarative/animation-behavioral.qml +++ b/doc/src/snippets/declarative/models/views-models-delegates.qml @@ -37,25 +37,42 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ -//![0] -import QtQuick 1.0 -Item { - width: 100; height: 100 +//! [rectangle] +Rectangle { + width: 200; height: 200 - Rectangle { - id: rect - width: 100; height: 100 - color: "red" - - Behavior on x { PropertyAnimation { duration: 500 } } - Behavior on y { PropertyAnimation { duration: 500 } } + ListModel { + id: fruitModel + property string language: "en" + ListElement { + name: "Apple" + cost: 2.45 + } + ListElement { + name: "Orange" + cost: 3.25 + } + ListElement { + name: "Banana" + cost: 1.95 + } } - MouseArea { + Component { + id: fruitDelegate + Row { + Text { text: " Fruit: " + name; color: ListView.view.fruit_color } + Text { text: " Cost: $" + cost } + Text { text: " Language: " + ListView.view.model.language } + } + } + + ListView { + property color fruit_color: "green" + model: fruitModel + delegate: fruitDelegate anchors.fill: parent - onClicked: { rect.x = mouse.x; rect.y = mouse.y } } } -//![0] - +//! [rectangle] diff --git a/doc/src/snippets/declarative/animation-transitions.qml b/doc/src/snippets/declarative/models/visual-model-and-view.qml index 62bef23..4d42b65 100644 --- a/doc/src/snippets/declarative/animation-transitions.qml +++ b/doc/src/snippets/declarative/models/visual-model-and-view.qml @@ -37,26 +37,21 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ -//![0] -import QtQuick 1.0 Rectangle { - id: rect - width: 100; height: 100 - color: "red" - - MouseArea { - anchors.fill: parent - onClicked: rect.state = "moved" - } - - states: State { - name: "moved" - PropertyChanges { target: rect; x: 50; y: 50 } + width: 200; height: 200 + + //! [visual model and view] + VisualItemModel { + id: itemModel + Rectangle { height: 30; width: 80; color: "red" } + Rectangle { height: 30; width: 80; color: "green" } + Rectangle { height: 30; width: 80; color: "blue" } } - - transitions: Transition { - PropertyAnimation { properties: "x,y"; duration: 1000 } + + ListView { + anchors.fill: parent + model: itemModel } + //! [visual model and view] } -//![0] diff --git a/doc/src/snippets/declarative/mousearea/mousearea-snippet.qml b/doc/src/snippets/declarative/mousearea/mousearea-snippet.qml index 3c2e143..03473ba 100644 --- a/doc/src/snippets/declarative/mousearea/mousearea-snippet.qml +++ b/doc/src/snippets/declarative/mousearea/mousearea-snippet.qml @@ -41,13 +41,60 @@ //! [document] import QtQuick 1.0 -Rectangle { - width: 100; height: 100 +//! [parent begin] +Rectangle { +//! [parent begin] + width: 500; height: 500 color: "green" - MouseArea { +Column { +//! [anchor fill] +Rectangle { + id: button + width: 100; height: 100 + + MouseArea { anchors.fill: parent - onClicked: { parent.color = 'red' } + onClicked: console.log("button clicked") + } + MouseArea { + width:150; height: 75 + onClicked: console.log("irregular area clicked") + } +} +//! [anchor fill] + +Rectangle { + id: button + width: 100; height: 100 + +//! [enable handlers] + MouseArea { + hoverEnabled: true + acceptedButtons: Qt.LeftButton | Qt.RightButton + onEntered: console.log("mouse entered the area") + onExited: console.log("mouse left the area") } +//! [enable handlers] +} + +Rectangle { + id: button + width: 100; height: 100 + +//! [mouse handlers] + MouseArea { + anchors.fill: parent + onClicked: console.log("area clicked") + onDoubleClicked: console.log("area double clicked") + onEntered: console.log("mouse entered the area") + onExited: console.log("mouse left the area") + } +//! [mouse handlers] +} + +} //end of column +//! [parent end] } +//! [parent end] //! [document] diff --git a/doc/src/snippets/declarative/pics/qt.png b/doc/src/snippets/declarative/pics/qt.png Binary files differindex cbed1a9..4f68e16 100644 --- a/doc/src/snippets/declarative/pics/qt.png +++ b/doc/src/snippets/declarative/pics/qt.png diff --git a/doc/src/snippets/declarative/properties.qml b/doc/src/snippets/declarative/properties.qml new file mode 100644 index 0000000..330d1cf --- /dev/null +++ b/doc/src/snippets/declarative/properties.qml @@ -0,0 +1,315 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [document] +import QtQuick 1.0 + +//! [parent begin] +Rectangle { +//! [parent begin] + + //! [inherited properties] + width: 320; height: 240 + color: "lightblue" + focus: true + //! [inherited properties] + + //! [custom properties] + property int counter + property real area: 100.45 + //! [custom properties] + + //! [property types] + property int number + property real volume: 100.45 + property date today: "2011-01-01" + property color background: "yellow" + //! [property types] + + +//! [grouped properties] +Text { + //dot notation + font.pixelSize: 12 + font.bold: true +} + +Text { + //group notation + font {pixelSize: 12; bold: true} +} +//! [grouped properties] + + +//! [property binding] +Rectangle { + width: parent.width +} +//! [property binding] + +//! [property assignment] +Rectangle { + Component.onCompleted: { + width = 150 + } +} +//! [property assignment] + +Rectangle { + //placeholder slider + id: slider + property real value +} +Rectangle { + //placeholder system + id: system + property real brightness +} +//! [binding element] +Binding { + target: system + property: "brightness" + value: slider.value +} +//! [binding element] + +Rectangle { + //placeholder warning + id: warning + color: "red" +} +//! [PropertyChanges element] +Rectangle { + id: rectangle + + states: State { + name: "WARNING" + PropertyChanges { + target: rectangle + color: warning.color + } + } +} +//! [PropertyChanges element] + +//! [list property] +Item { + id: multistate + states: [ + State {name: "FETCH"}, + State {name: "DECODE"}, + State {name: "EXECUTE"} + ] +} +//! [list property] +//! [single property] +Item { + id: monostate + states: State {name: "RUNNING"} +} +//! [single property] + +Item { + id: printstate +//! [print list property] + Component.onCompleted: console.log (multistate.states[0].name) +//! [print list property] +} + +//! [JavaScript sample] +function calculateArea(width, height) { + return (width * height) * 0.5 +} + +Rectangle { + width: 150; height: 75 + property real area: calculateArea(width, height) + property real parentArea: calculateArea(parent.width,parent.height) + color: { if (area > parentArea) "blue"; else "red" } +} +//! [JavaScript sample] + +//! [id property] +Rectangle { + id: container + width: 100; height: 100 + Rectangle { + width: parent.width; height: parent.height + } +} +Rectangle { + width: container.width; height: container.height +} +//! [id property] + +//! [default property] +Item { + Text {} + Rectangle {} + Timer {} +} + +Item { + //without default property + children: [ + Text {}, + Rectangle {} + ] + resources: [ + Timer {} + ] +} +//! [default property] + +//! [state default] +State { + changes: [ + PropertyChanges {}, + PropertyChanges {} + ] +} + +State { + PropertyChanges {} + PropertyChanges {} +} +//! [state default] + +//! [object binding] +Rectangle { + + id: parentrectangle + gradient: + Gradient { //not a child of parentrectangle + + //generates a TypeError + //Component.onCompleted: console.log(parent.width) + } + + //child of parentrectangle + Rectangle {property string name: "childrectangle"} + + //prints "childrectangle" + Component.onCompleted: console.log(children[0].name) +} +//! [object binding] + +//! [list attached property] +Component { + id: listdelegate + Text { + text: "Hello" + color: ListView.isCurrentItem ? "red" : "blue" + } +} +ListView { + delegate: listdelegate +} +//! [list attached property] + +//! [attached signal handler] +Item { + Keys.onPressed: console.log("Key Press Detected") + Component.onCompleted: console.log("Completed initialization") +} +//! [attached signal handler] + +//! [alias usage] +Button { + id: textbutton + buttonLabel: "Click Me!" +} +//! [alias usage] + +//! [image alias] +Button { + id: imagebutton + buttonImage.source: "http://qt.nokia.com/logo.png" + buttonLabel: buttonImage.source +} +//! [image alias] + +Item { +id: widget + +//! [alias complete] +property alias widgetLabel: label + +//will generate an error +//widgetLabel.text: "Initial text" + +//will generate an error +//property alias widgetLabelText: widgetLabel.text + +Component.onCompleted: widgetLabel.text = "Alias completed Initialization" +//! [alias complete] + + Text {id: label} +} + +//![alias overwrite] +Rectangle { + id: coloredrectangle + property alias color: bluerectangle.color + color: "red" + + Rectangle { + id: bluerectangle + color: "#1234ff" + } + + Component.onCompleted: { + console.log (coloredrectangle.color) //prints "#1234ff" + setInternalColor() + console.log (coloredrectangle.color) //prints "#111111" + coloredrectangle.color = "#884646" + console.log (coloredrectangle.color) //prints #884646 + } + + //internal function that has access to internal properties + function setInternalColor() { + color = "#111111" + } +} +//![alias overwrite] +//! [parent end] +} +//! [parent end] +//! [document] diff --git a/doc/src/snippets/declarative/qml-intro/anchors3.qml b/doc/src/snippets/declarative/qml-intro/anchors3.qml deleted file mode 100644 index 24851af..0000000 --- a/doc/src/snippets/declarative/qml-intro/anchors3.qml +++ /dev/null @@ -1,65 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). -** All rights reserved. -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -import QtQuick 1.0 - -Rectangle { - id: myWin - width: 500 - height: 400 - - Image { - id: image1 - source: "images/qt-logo.svg" - width: 150; height: 150 - anchors.bottom: myWin.bottom - anchors.horizontalCenter: myWin.horizontalCenter - anchors.bottomMargin: 10 - } - -//! [adding some text] - Text { - text: "<h2>The Qt Logo</h2>" - anchors.bottom: image1.top - anchors.horizontalCenter: myWin.horizontalCenter - anchors.bottomMargin: 15 - } -//! [adding some text] -} diff --git a/doc/src/snippets/declarative/qml-intro/hello-world2.qml b/doc/src/snippets/declarative/qml-intro/hello-world2.qml deleted file mode 100644 index 2564e25..0000000 --- a/doc/src/snippets/declarative/qml-intro/hello-world2.qml +++ /dev/null @@ -1,56 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). -** All rights reserved. -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -import QtQuick 1.0 - -Rectangle { - id: myRectangle - width: 500 - height: 400 - -//! [updated text] - Text { - text: "<h2>Hello World</h2>"; color: "darkgreen" - x: 100; y:100 - } -//! [updated text] - - color: "lightgray" -} diff --git a/doc/src/snippets/declarative/qml-intro/hello-world3.qml b/doc/src/snippets/declarative/qml-intro/hello-world3.qml deleted file mode 100644 index 03358d0..0000000 --- a/doc/src/snippets/declarative/qml-intro/hello-world3.qml +++ /dev/null @@ -1,57 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). -** All rights reserved. -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -import QtQuick 1.0 - -Rectangle { - id: myRectangle - width: 500 - height: 400 - -//! [updated text] - Text { - text: "<h1>Hello world again</h1>" - color: "#002288" - x: 100; y: 100 - } -//! [updated text] - - color: "lightgray" -} diff --git a/doc/src/snippets/declarative/qml-intro/images/qt-logo.svg b/doc/src/snippets/declarative/qml-intro/images/qt-logo.svg deleted file mode 100644 index 8c018be..0000000 --- a/doc/src/snippets/declarative/qml-intro/images/qt-logo.svg +++ /dev/null @@ -1,104 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<svg - xmlns:dc="http://purl.org/dc/elements/1.1/" - xmlns:cc="http://creativecommons.org/ns#" - xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" - xmlns:svg="http://www.w3.org/2000/svg" - xmlns="http://www.w3.org/2000/svg" - xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - clip-rule="evenodd" - stroke-miterlimit="10" - viewBox="0 0 174.35 209.78" - id="svg2" - sodipodi:version="0.32" - inkscape:version="0.46" - width="744.09186" - height="895.29858" - sodipodi:docname="qt-logo.svg" - inkscape:output_extension="org.inkscape.output.svg.inkscape" - version="1.0" - style="stroke-miterlimit:10"> - <metadata - id="metadata29"> - <rdf:RDF> - <cc:Work - rdf:about=""> - <dc:format>image/svg+xml</dc:format> - <dc:type - rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - </cc:Work> - </rdf:RDF> - </metadata> - <sodipodi:namedview - inkscape:window-height="668" - inkscape:window-width="722" - inkscape:pageshadow="2" - inkscape:pageopacity="0.0" - guidetolerance="10.0" - gridtolerance="10.0" - objecttolerance="10.0" - borderopacity="1.0" - bordercolor="#666666" - pagecolor="#ffffff" - id="base" - showgrid="false" - inkscape:zoom="0.12195802" - inkscape:cx="525.6108" - inkscape:cy="-287.87189" - inkscape:window-x="476" - inkscape:window-y="228" - inkscape:current-layer="svg2" /> - <desc - id="desc4">SVG generated by Lineform</desc> - <defs - id="defs6"> - <inkscape:perspective - sodipodi:type="inkscape:persp3d" - inkscape:vp_x="0 : 526.18109 : 1" - inkscape:vp_y="0 : 1000 : 0" - inkscape:vp_z="744.09448 : 526.18109 : 1" - inkscape:persp3d-origin="372.04724 : 350.78739 : 1" - id="perspective31" /> - </defs> - <g - id="g8" - transform="translate(-1.5304326e-4,-3.775985e-4)"> - <path - d="M 43.08,0.36 C 40.94,0 38.84,-0.08 36.81,0.08 L 36.8,0.08 C 36.8,0.08 22.92,1.02 22.29,1.07 C 9.62,2.08 0,12.5 0,26.89 L 0,196.55 L 14.19,209.78 L 156.79,185.81 C 166.6,184.11 174.35,172.54 174.35,160.04 L 174.35,21.88 L 43.08,0.36" - id="path10" - style="fill:#0c481e" /> - <path - d="M 174.35,160.04 C 174.35,172.54 166.6,184.11 156.79,185.82 L 14.19,209.78 L 14.19,25.99 C 14.19,9.27 27.53,-2.21 43.08,0.36 L 174.35,21.88 L 174.35,160.04" - id="path12" - style="fill:#66b036" /> - <path - d="M 130.42,45.91 L 141.94,47.15 L 141.94,67.36 L 154.9,68.28 L 154.9,80.96 L 141.94,80.36 L 141.94,126.69 C 141.94,130.72 142.38,133.31 143.28,134.48 C 144.08,135.55 145.32,136.07 146.99,136.07 C 147.15,136.07 147.32,136.07 147.48,136.06 C 150.03,135.91 152.81,135.13 155.83,133.75 L 155.83,145.4 C 150.69,147.65 145.65,149 140.7,149.42 C 139.99,149.47 139.29,149.5 138.62,149.5 C 134.14,149.5 130.72,148.2 128.38,145.57 C 125.65,142.52 124.29,137.62 124.29,130.9 L 124.29,79.54 L 118.06,79.26 L 118.06,65.67 L 125.65,66.22 L 130.42,45.91" - id="path14" - style="fill:#ffffff" /> - <path - d="M 154.9,80.96 L 141.94,80.36 L 141.94,80.64 L 148.88,80.96 L 154.9,80.96" - id="path16" - style="fill:#0c481e" /> - <path - d="M 144.64,135.6 C 145.3,135.92 146.07,136.07 146.99,136.07 C 147.15,136.07 147.32,136.07 147.48,136.06 C 150.03,135.91 152.81,135.13 155.83,133.75 L 149.81,133.75 C 147.99,134.58 146.28,135.21 144.64,135.6" - id="path18" - style="fill:#0c481e" /> - <path - d="M 128.38,145.57 C 125.65,142.52 124.29,137.62 124.29,130.9 L 124.29,79.54 L 118.06,79.26 L 118.06,65.67 L 112.05,65.67 L 112.05,68.71 C 112.92,71.98 113.6,75.53 114.11,79.35 L 118.28,79.54 L 118.28,130.9 C 118.28,137.62 119.64,142.52 122.37,145.57 C 124.71,148.2 128.13,149.5 132.61,149.5 L 138.62,149.5 C 134.14,149.5 130.72,148.2 128.38,145.57 z M 130.42,45.91 L 124.41,45.91 L 119.74,65.79 L 125.65,66.22 L 130.42,45.91" - id="path20" - style="fill:#0c481e" /> - <path - d="M 91.15,132.4 C 93.5,126.36 94.66,114.49 94.66,96.79 C 94.66,80.9 93.51,69.97 91.18,63.98 C 88.84,57.95 85.35,54.69 80.66,54.28 C 80.3,54.25 79.95,54.23 79.6,54.23 C 75.26,54.23 71.92,56.77 69.59,61.86 C 67.07,67.4 65.8,78.9 65.8,96.3 C 65.8,113.11 67.04,125.05 69.54,132.05 C 71.89,138.72 75.41,142.03 80.04,142.03 C 80.25,142.03 80.45,142.02 80.66,142.01 C 85.29,141.71 88.78,138.51 91.15,132.4 M 109.13,136.15 C 105.01,145.86 98.73,152.21 90.14,155.15 C 91.01,159.6 92.32,162.6 94.06,164.17 C 95.41,165.39 97.49,165.99 100.28,165.99 C 101.09,165.99 101.96,165.94 102.87,165.84 L 102.87,178.96 L 96.91,179.75 C 95.16,179.97 93.49,180.09 91.91,180.09 C 86.69,180.09 82.47,178.82 79.29,176.26 C 75.08,172.89 71.98,166.37 69.99,156.73 C 60.86,154.78 53.73,148.97 48.8,139.23 C 43.8,129.32 41.25,114.83 41.25,95.89 C 41.25,75.46 44.74,60.38 51.6,50.81 C 57.38,42.75 65.46,38.78 75.62,38.78 C 77.24,38.78 78.93,38.88 80.66,39.08 C 92.61,40.46 101.28,46.1 106.92,55.87 C 112.46,65.43 115.17,79.14 115.17,97.13 C 115.17,113.62 113.17,126.58 109.13,136.15" - id="path22" - style="fill:#ffffff" /> - <path - d="M 100.28,165.99 C 101.09,165.99 101.95,165.94 102.87,165.84 L 98.04,165.84 C 98.71,165.94 99.49,165.99 100.28,165.99" - id="path24" - style="fill:#0c481e" /> - <path - d="M 84.85,63.98 C 87.19,69.97 88.34,80.9 88.34,96.79 C 88.34,114.49 87.18,126.36 84.82,132.4 C 82.93,137.28 80.3,140.31 76.96,141.48 C 77.93,141.84 78.96,142.03 80.04,142.03 C 80.25,142.03 80.45,142.02 80.66,142.01 C 85.29,141.71 88.78,138.51 91.15,132.4 C 93.5,126.36 94.66,114.49 94.66,96.79 C 94.66,80.9 93.51,69.97 91.18,63.98 C 88.84,57.95 85.35,54.69 80.66,54.28 C 80.3,54.25 79.95,54.23 79.6,54.23 C 78.51,54.23 77.48,54.39 76.52,54.72 L 76.52,54.72 C 80.12,55.83 82.89,58.93 84.85,63.98 z M 82.51,178.25 C 82.4,178.2 82.28,178.15 82.17,178.09 C 82.16,178.09 82.15,178.08 82.14,178.08 C 82.03,178.03 81.93,177.97 81.83,177.92 C 81.81,177.91 81.79,177.9 81.77,177.89 C 81.68,177.84 81.59,177.79 81.49,177.74 C 81.46,177.72 81.44,177.71 81.41,177.69 C 81.33,177.65 81.24,177.6 81.16,177.55 C 81.12,177.53 81.09,177.51 81.05,177.48 C 80.98,177.44 80.91,177.4 80.84,177.36 C 80.79,177.33 80.74,177.3 80.7,177.27 C 80.64,177.23 80.58,177.19 80.52,177.15 C 80.46,177.12 80.41,177.08 80.35,177.04 C 80.3,177.01 80.25,176.98 80.2,176.94 C 80.14,176.9 80.07,176.85 80.01,176.81 C 79.97,176.78 79.93,176.75 79.89,176.72 C 79.82,176.67 79.74,176.61 79.67,176.55 C 79.64,176.54 79.61,176.52 79.59,176.5 C 79.49,176.42 79.39,176.34 79.29,176.26 C 75.08,172.89 71.98,166.37 69.99,156.73 C 60.86,154.78 53.73,148.97 48.8,139.23 C 43.8,129.32 41.25,114.83 41.25,95.89 C 41.25,75.46 44.74,60.38 51.6,50.81 C 57.38,42.75 65.46,38.78 75.62,38.78 C 75.65,38.78 69.27,38.77 69.27,38.77 L 69.27,38.78 C 59.12,38.78 51.05,42.75 45.27,50.81 C 38.41,60.38 34.92,75.46 34.92,95.89 C 34.92,114.83 37.47,129.32 42.47,139.23 C 47.41,148.97 54.53,154.78 63.67,156.73 C 65.65,166.37 68.76,172.89 72.96,176.26 C 76.14,178.82 80.36,180.09 85.58,180.09 C 85.68,180.09 85.78,180.09 85.88,180.09 L 91.42,180.09 C 88.01,180.03 85.04,179.43 82.52,178.26 C 82.51,178.26 82.51,178.26 82.51,178.25" - id="path26" - style="fill:#0c481e" /> - </g> -</svg> diff --git a/doc/src/snippets/declarative/qml-intro/number-animation2.qml b/doc/src/snippets/declarative/qml-intro/number-animation2.qml deleted file mode 100644 index 7be22b5..0000000 --- a/doc/src/snippets/declarative/qml-intro/number-animation2.qml +++ /dev/null @@ -1,66 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). -** All rights reserved. -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [document] -import QtQuick 1.0 - -Rectangle { - id: mainRec - width: 600 - height: 400 - - Image { - id: image1 - source: "images/qt-logo.svg" - x: 200; y: 100 - width: 100; height: 100 - - // Animate a rotation - transform: Rotation { - origin.x: 50; origin.y: 50; axis {x:0; y:1; z:0} angle:0 - NumberAnimation on angle { - from: 0; to: 360; - duration: 3000; - loops: Animation.Infinite - } - } - } -} -//! [document] diff --git a/doc/src/snippets/declarative/qml-intro/rectangle.qml b/doc/src/snippets/declarative/qml-intro/rectangle.qml deleted file mode 100644 index b25accc..0000000 --- a/doc/src/snippets/declarative/qml-intro/rectangle.qml +++ /dev/null @@ -1,50 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). -** All rights reserved. -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [document] -import QtQuick 1.0 - -// This is a comment. And below myRectangle is defined. -Rectangle { - id: myRectangle - width: 500 - height: 400 -} -//! [document] diff --git a/doc/src/snippets/declarative/qml-intro/sequential-animation1.qml b/doc/src/snippets/declarative/qml-intro/sequential-animation1.qml deleted file mode 100644 index c789bbe..0000000 --- a/doc/src/snippets/declarative/qml-intro/sequential-animation1.qml +++ /dev/null @@ -1,65 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). -** All rights reserved. -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [document] -import QtQuick 1.0 - -Rectangle { - id: mainRec - width: 600 - height: 400 - z: 0 - - Image { - id: image1 - source: "images/qt-logo.svg" - x: 20; y: 20 ; z: 1 - width: 100; height: 100 - } - - Image { - id: image2 - source: "images/qt-logo.svg" - width: 100; height: 100 - x: (mainRec.width - 100)/2; y: (mainRec.height - 100)/2 - z: 2 - } -} -//! [document] diff --git a/doc/src/snippets/declarative/qml-intro/sequential-animation2.qml b/doc/src/snippets/declarative/qml-intro/sequential-animation2.qml deleted file mode 100644 index b2b1a57..0000000 --- a/doc/src/snippets/declarative/qml-intro/sequential-animation2.qml +++ /dev/null @@ -1,73 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). -** All rights reserved. -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -import QtQuick 1.0 - -Rectangle { - id: mainRec - width: 600 - height: 400 - z: 0 - -//! [adding a sequential animation] - Image { - id: image1 - source: "images/qt-logo.svg" - width: 100; height: 100 - - SequentialAnimation on x { - loops: Animation.Infinite - NumberAnimation { - from: 20; to: 450; easing.type: "InOutQuad"; - duration: 2000 - } - PauseAnimation { duration: 500 } - } - } -//! [adding a sequential animation] - - Image { - id: image2 - source: "images/qt-logo.svg" - width: 100; height: 100 - x: (mainRec.width - 100)/2; y: (mainRec.height - 100)/2 - z: 2 - } -} diff --git a/doc/src/snippets/declarative/reusablecomponents/Button.qml b/doc/src/snippets/declarative/reusablecomponents/Button.qml new file mode 100644 index 0000000..3b97e00 --- /dev/null +++ b/doc/src/snippets/declarative/reusablecomponents/Button.qml @@ -0,0 +1,84 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +//! [document] +//contents of Button.qml +import QtQuick 1.0 + +//! [parent begin] +Rectangle { +//! [parent begin] + id: button +//! [properties] + width: 145; height: 60 + color: "blue" + smooth: true; radius: 9 + property alias text: label.text +//! [properties] + border {color: "#B9C5D0"; width: 1} + + gradient: Gradient { + GradientStop {color: "#CFF7FF"; position: 0.0} + GradientStop {color: "#99C0E5"; position: 0.57} + GradientStop {color: "#719FCB"; position: 0.9} + } + + Text { + id: label + anchors.centerIn: parent + text: "Click Me!" + font.pointSize: 12 + color: "blue" + } + + MouseArea { + anchors.fill: parent + onClicked: console.log(text + " clicked") + } +//! [parent end] +} +//! [parent end] + +//! [document] + +//! [ellipses] + //... +//! [ellipses] + + diff --git a/doc/src/snippets/declarative/qml-intro/anchors1.qml b/doc/src/snippets/declarative/reusablecomponents/application.qml index b958138..a09b276 100644 --- a/doc/src/snippets/declarative/qml-intro/anchors1.qml +++ b/doc/src/snippets/declarative/reusablecomponents/application.qml @@ -37,20 +37,19 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - //! [document] import QtQuick 1.0 Rectangle { - id: myWin - width: 500 - height: 400 + width: 175; height: 350 + color: "lightgrey" - Image { - id: image1 - source: "images/qt-logo.svg" - width: 150; height: 150 - anchors.bottom: myWin.bottom + Column { + anchors.centerIn: parent + spacing: 15 + Button {} + Button {text: "Me Too!"} + Button {text: "Me Three!"} } } //! [document] diff --git a/doc/src/snippets/declarative/animation-standalone.qml b/doc/src/snippets/declarative/reusablecomponents/component.qml index 0bf3020..8660c50 100644 --- a/doc/src/snippets/declarative/animation-standalone.qml +++ b/doc/src/snippets/declarative/reusablecomponents/component.qml @@ -37,27 +37,41 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ -//![0] +//! [document] import QtQuick 1.0 +//! [parent begin] Rectangle { - id: rect - width: 100; height: 100 - color: "red" - - PropertyAnimation { - id: animation - target: rect - properties: "x,y" - duration: 1000 +//! [parent begin] + id: screen + width: 175; height: 175 + color: "lightgrey" + +//! [define inline component] + Component { + id: inlinecomponent + Rectangle { + id: display + width: 50; height: 50 + color: "blue" + } } - +//! [define inline component] +//! [create inline component] MouseArea { anchors.fill: parent onClicked: { - animation.to = 50; - animation.running = true; + inlinecomponent.createObject(parent) + + var second = inlinecomponent.createObject(parent) + + var third = inlinecomponent.createObject(parent) + third.x = second.width + 10 + third.color = "red" } - } + } +//! [create inline component] +//! [parent end] } -//![0] +//! [parent end] +//! [document] diff --git a/doc/src/snippets/declarative/qml-intro/sequential-animation3.qml b/doc/src/snippets/declarative/reusablecomponents/focusbutton.qml index d840575..2522a98 100644 --- a/doc/src/snippets/declarative/qml-intro/sequential-animation3.qml +++ b/doc/src/snippets/declarative/reusablecomponents/focusbutton.qml @@ -37,56 +37,62 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - -import QtQuick 1.0 - //! [document] +//contents of focusbutton.qml import QtQuick 1.0 -Rectangle { - id: mainRec - width: 600 - height: 400 - z: 0 +//! [parent begin] +FocusScope { +//! [parent begin] - Image { - id: image2 - source: "images/qt-logo.svg" - width: 100; height: 100 - x: (mainRec.width - 100)/2; y: (mainRec.height - 100)/2 - z: 2 - } + //! [expose visuals] + //FocusScope needs to bind to visual properties of the children + property alias color: button.color + x: button.x; y: button.y + width: button.width; height: button.height + //! [expose visuals] - Image { - id: image1 - source: "images/qt-logo.svg" - x: 20; y: 20 ; z: 1 - width: 100; height: 100 + //! [rectangle begin] + Rectangle { + //! [rectangle begin] + id: button + //! [properties] + width: 145; height: 60 + color: "blue" + smooth: true; radius: 9 + property alias text: label.text + //! [properties] + border {color: "#B9C5D0"; width: 1} - SequentialAnimation on x { - loops: Animation.Infinite - NumberAnimation { - from: 20; to: 450 - easing.type: "InOutQuad"; duration: 2000 - } - PauseAnimation { duration: 500 } + gradient: Gradient { + GradientStop {color: "#CFF7FF"; position: 0.0} + GradientStop {color: "#99C0E5"; position: 0.57} + GradientStop {color: "#719FCB"; position: 0.9} } - SequentialAnimation on y { - loops: Animation.Infinite - NumberAnimation { - from: 20; to: 250 - easing.type: "InOutQuad"; duration: 2000 - } - PauseAnimation { duration: 500 } + Text { + id: label + anchors.centerIn: parent + text: "Click Me!" + font.pointSize: 12 + color: "blue" } - SequentialAnimation on scale { - loops: Animation.Infinite - NumberAnimation { from: 1; to: 0.5; duration: 1000 } - NumberAnimation { from: 0.5; to: 1; duration: 1000 } - PauseAnimation { duration: 500 } + MouseArea { + anchors.fill: parent + onClicked: console.log(text + " clicked") } + //! [rectangle end] } + //! [rectangle end] +//! [parent end] } +//! [parent end] + //! [document] + +//! [ellipses] + //... +//! [ellipses] + + diff --git a/doc/src/snippets/declarative/reusablecomponents/qmldir b/doc/src/snippets/declarative/reusablecomponents/qmldir new file mode 100644 index 0000000..253732d --- /dev/null +++ b/doc/src/snippets/declarative/reusablecomponents/qmldir @@ -0,0 +1,4 @@ +//! [document] +Button ./Button.qml +FocusButton ./focusbutton.qml +//! [document] diff --git a/doc/src/snippets/declarative/states.qml b/doc/src/snippets/declarative/states.qml index c3b7197..ab6b8d0 100644 --- a/doc/src/snippets/declarative/states.qml +++ b/doc/src/snippets/declarative/states.qml @@ -37,24 +37,85 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ -//![0] +//![document] import QtQuick 1.0 - + +//![parent begin] Rectangle { - id: myRect - width: 200; height: 200 - color: "red" +//![parent begin] + + id: screen + width: 400; height: 500 - MouseArea { - anchors.fill: parent - onClicked: myRect.state = 'moved' - } + +Rectangle { + id: flag +} +Column { + spacing: 15 +//![signal states] +Rectangle { + id: signal + width: 200; height: 200 + state: "NORMAL" states: [ State { - name: "moved" - PropertyChanges { target: myRect; x: 50; y: 50 } + name: "NORMAL" + PropertyChanges { target: signal; color: "green"} + PropertyChanges { target: flag; state: "FLAG_DOWN"} + }, + State { + name: "CRITICAL" + PropertyChanges { target: signal; color: "red"} + PropertyChanges { target: flag; state: "FLAG_UP"} } ] } -//![0] +//![signal states] + +//![switch states] +Rectangle { + id: signalswitch + width: 75; height: 75 + color: "blue" + + MouseArea { + anchors.fill: parent + onClicked: { + if (signal.state == "NORMAL") + signal.state = "CRITICAL" + else + signal.state = "NORMAL" + } + } +} +//![switch states] + +//![when property] +Rectangle { + id: bell + width: 75; height: 75 + color: "yellow" + + states: State { + name: "RINGING" + when: (signal.state == "CRITICAL") + PropertyChanges {target: speaker; play: "RING!"} + } +} +//![when property] + +Text { + id: speaker + property alias play: speaker.text + text: "NORMAL" +} + +} // end of row + +//![parent end] +} +//![parent end] + +//![document] diff --git a/doc/src/snippets/declarative/qml-intro/hello-world5.qml b/doc/src/snippets/declarative/texthandling.qml index 7357282..377bb8b 100644 --- a/doc/src/snippets/declarative/qml-intro/hello-world5.qml +++ b/doc/src/snippets/declarative/texthandling.qml @@ -37,29 +37,53 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - //! [document] import QtQuick 1.0 + +//! [parent begin] Rectangle { - id: myRectangle - width: 500 - height: 400 +//! [parent begin] + width: 300; height: 300 + id: screen + +Column { + anchors.centerIn:parent + +//! [int validator] +Column { + spacing: 10 Text { - text: "<h1>Hello world again</h1>" - color: "#002288" - x: 100; y: 100 + text: "Enter a value from 0 to 2000" } + TextInput { + focus: true + validator: IntValidator { bottom:0; top: 2000} + } +} +//! [int validator] + +//! [regexp validator] +Column { + spacing: 10 -//! [positioning the image] - Image { - source: "images/qt-logo.svg" - x: 100; y: 150 - width: 150; height: 150 + Text { + text: "Which basket?" + } + TextInput { + focus: true + validator: RegExpValidator { regExp: /fruit basket/ } } -//! [positioning the image] +} +//! [regexp validator] - color: "lightgray" +//end of column } + +//! [parent end] +} +//! [parent end] + //! [document] + diff --git a/doc/src/snippets/declarative/webview/webview.qml b/doc/src/snippets/declarative/webview/webview.qml index dac8010..f652369 100644 --- a/doc/src/snippets/declarative/webview/webview.qml +++ b/doc/src/snippets/declarative/webview/webview.qml @@ -39,7 +39,9 @@ ****************************************************************************/ //! [document] +//! [import] import QtWebKit 1.0 +//! [import] WebView { url: "http://www.nokia.com" diff --git a/doc/src/snippets/qtreeview-dnd/dragdropmodel.h b/doc/src/snippets/qtreeview-dnd/dragdropmodel.h index ed01540..a20b1bb 100644 --- a/doc/src/snippets/qtreeview-dnd/dragdropmodel.h +++ b/doc/src/snippets/qtreeview-dnd/dragdropmodel.h @@ -38,17 +38,6 @@ ** ****************************************************************************/ -/**************************************************************************** -** -** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). -** All rights reserved. -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of an example program for Qt. -** EDITIONS: NOLIMITS -** -****************************************************************************/ - #ifndef DRAGDROPMODEL_H #define DRAGDROPMODEL_H diff --git a/doc/src/snippets/qtscript/evaluation/main.cpp b/doc/src/snippets/qtscript/evaluation/main.cpp index e7efd8e..01e06b6 100644 --- a/doc/src/snippets/qtscript/evaluation/main.cpp +++ b/doc/src/snippets/qtscript/evaluation/main.cpp @@ -42,9 +42,9 @@ int main(int argc, char *argv[]) { -//! [0] + //! [0] QScriptEngine engine; qDebug() << "the magic number is:" << engine.evaluate("1 + 2").toNumber(); -//! [0] + //! [0] return 0; } diff --git a/doc/src/snippets/qtscript/registeringobjects/main.cpp b/doc/src/snippets/qtscript/registeringobjects/main.cpp index 1911442..9dab25a 100644 --- a/doc/src/snippets/qtscript/registeringobjects/main.cpp +++ b/doc/src/snippets/qtscript/registeringobjects/main.cpp @@ -44,12 +44,12 @@ int main(int argc, char *argv[]) { -//! [0] + //! [0] QScriptEngine engine; QObject *someObject = new MyObject; QScriptValue objectValue = engine.newQObject(someObject); engine.globalObject().setProperty("myObject", objectValue); -//! [0] + //! [0] qDebug() << "myObject's calculate() function returns" << engine.evaluate("myObject.calculate(10)").toNumber(); return 0; diff --git a/doc/src/snippets/qtscript/registeringvalues/main.cpp b/doc/src/snippets/qtscript/registeringvalues/main.cpp index 3defc1f..6dc5b7c 100644 --- a/doc/src/snippets/qtscript/registeringvalues/main.cpp +++ b/doc/src/snippets/qtscript/registeringvalues/main.cpp @@ -43,10 +43,10 @@ int main(int argc, char *argv[]) { QScriptEngine engine; -//! [0] + //! [0] engine.globalObject().setProperty("foo", 123); qDebug() << "foo times two is:" << engine.evaluate("foo * 2").toNumber(); -//! [0] + //! [0] return 0; } diff --git a/doc/src/snippets/textblock-fragments/xmlwriter.cpp b/doc/src/snippets/textblock-fragments/xmlwriter.cpp index 9f66d9a..252720b 100644 --- a/doc/src/snippets/textblock-fragments/xmlwriter.cpp +++ b/doc/src/snippets/textblock-fragments/xmlwriter.cpp @@ -102,11 +102,10 @@ void XmlWriter::readFragment(const QTextBlock ¤tBlock, QDomText fragmentText = document->createTextNode(currentFragment.text()); fragmentElement.appendChild(fragmentText); -//! [6] } -//! [7] - } //! [6] //! [7] + } +//! [7] //! [6] } void XmlWriter::processBlock(const QTextBlock ¤tBlock) diff --git a/doc/src/snippets/textdocument-frames/xmlwriter.cpp b/doc/src/snippets/textdocument-frames/xmlwriter.cpp index 31f08f3..8988100 100644 --- a/doc/src/snippets/textdocument-frames/xmlwriter.cpp +++ b/doc/src/snippets/textdocument-frames/xmlwriter.cpp @@ -100,6 +100,8 @@ void XmlWriter::processFrame(QDomElement &parent, QTextFrame *frame) parent.appendChild(frameElement); //! [1] + QDomElement frameElement = ... + QTextFrame::iterator it; for (it = frame->begin(); !(it.atEnd()); ++it) { diff --git a/doc/src/snippets/textdocument-tables/xmlwriter.cpp b/doc/src/snippets/textdocument-tables/xmlwriter.cpp index d1d6798..8f98295 100644 --- a/doc/src/snippets/textdocument-tables/xmlwriter.cpp +++ b/doc/src/snippets/textdocument-tables/xmlwriter.cpp @@ -98,6 +98,8 @@ void XmlWriter::processFrame(QDomElement &parent, QTextFrame *frame) parent.appendChild(frameElement); //! [0] + QDomElement frameElement = ... + QTextFrame::iterator it; for (it = frame->begin(); !(it.atEnd()); ++it) { diff --git a/doc/src/sql-programming/sql-driver.qdoc b/doc/src/sql-programming/sql-driver.qdoc index a4bcb97..2cb7aab 100644 --- a/doc/src/sql-programming/sql-driver.qdoc +++ b/doc/src/sql-programming/sql-driver.qdoc @@ -121,7 +121,7 @@ Source code to access the OUT values: - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 2 + \snippet doc/src/snippets/code/doc_src_sql-driver.cpp 2 \bold{Note:} \c{@outval1} and \c{@outval2} are variables local to the current connection and will not be affected by queries sent from another host @@ -394,7 +394,7 @@ sets, will be accessible only if you set the query's forward only mode to \e forward using \l QSqlQuery::setForwardOnly(). - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 10 + \snippet doc/src/snippets/code/doc_src_sql-driver.cpp 10 \bold{Note:} The value returned by the stored procedure's return statement is discarded. @@ -681,7 +681,7 @@ database file, no matter whether it is stored locally or on another server. - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 24 + \snippet doc/src/snippets/code/doc_src_sql-driver.cpp 24 You need the InterBase/Firebird development headers and libraries to build this plugin. @@ -696,7 +696,7 @@ be overridden by setting the ISC_DPB_LC_CTYPE parameter with QSqlDatabase::setConnectOptions() before opening the connection. - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 25 + \snippet doc/src/snippets/code/doc_src_sql-driver.cpp 25 If Qt doesn't support the given text encoding the driver will issue a warning message and connect to the database using UNICODE_FSS. @@ -710,7 +710,7 @@ procedure, only IN values need to be bound via QSqlQuery::bindValue(). The RETURN/OUT values can be retrieved via QSqlQuery::value(). Example: - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 26 + \snippet doc/src/snippets/code/doc_src_sql-driver.cpp 26 \section3 How to Build the QIBASE Plugin on Unix and Mac OS X @@ -777,7 +777,7 @@ Make sure you have followed the guide to \l{Deploying Plugins}. If you experience plugin load problems and see output like this: - \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 31 + \snippet doc/src/snippets/code/doc_src_sql-driver.cpp 31 the problem is usually that the plugin had the wrong \l{Deploying Plugins#The Build Key}{build key}. This might require removing an diff --git a/doc/src/template/style/offline.css b/doc/src/template/style/offline.css index 4083a75..44abb3c 100644 --- a/doc/src/template/style/offline.css +++ b/doc/src/template/style/offline.css @@ -26,14 +26,14 @@ { text-decoration: none; } - li - { - list-style: none; - } ol li { list-style: decimal; } + ul li + { + list-style: none; + } caption, th { text-align: left; @@ -76,6 +76,8 @@ { margin-left: 0.5em; margin-right: 0.5em; + font-family: sans-serif; + line-height: normal } a { @@ -124,13 +126,13 @@ } th { - padding: 0.5em 1.5em 0.5em 1.5em; + padding: 0.5em 1.5em 0.5em 1em; background-color: #E1E1E1; border-left: 1px solid #E6E6E6; } td { - padding: 0.25em 1.5em 0.25em 2em; + padding: 0.25em 1.5em 0.25em 1em; } td.rightAlign @@ -141,13 +143,13 @@ { border-left: 1px solid #E6E6E6; background-color: #F6F6F6; - color: #66666E; + color: black; } table tr.even { border-left: 1px solid #E6E6E6; background-color: #ffffff; - color: #66666E; + color: #202020; } div.float-left @@ -239,10 +241,6 @@ margin-bottom: 0.5em } - .naviNextPrevious - { - display: none - } .header .breadcrumb { font-size: 90%; @@ -309,19 +307,19 @@ .content h1 { font-weight: bold; - font-size: 150% + font-size: 130% } .content h2 { font-weight: bold; - font-size: 135%; + font-size: 120%; width: 100%; } .content h3 { font-weight: bold; - font-size: 120%; + font-size: 110%; width: 100%; } .content table p @@ -471,6 +469,11 @@ padding: 0.25em 0.5em 0.25em 0.5em; } + .toc + { + font-size: 80% + } + .header .content .toc ul { padding-left: 0px; diff --git a/doc/src/template/style/style.css b/doc/src/template/style/style.css index df2729c..4071145 100755 --- a/doc/src/template/style/style.css +++ b/doc/src/template/style/style.css @@ -7,7 +7,7 @@ color: #000000; background: #FFFFFF; } - body, div, dl, dt, dd, ul, ol, li, h1, h2, h3, h4, h5, h6, pre, code, form, fieldset, legend, input, button, textarea, p, blockquote, th, td + body, div, dl, dt, dd, ul, ol, li, h1, h2, h3, h4, h5, h6, pre, code, form, fieldset, legend, input, button, textarea, p, th, td { margin: 0; padding: 0; @@ -146,13 +146,13 @@ } th { - padding: 5px 15px 5px 15px; + padding: 5px 15px 5px 10px; background-color: #E1E1E1; border-left: 1px solid #E6E6E6; } td { - padding: 3px 15px 3px 20px; + padding: 3px 15px 3px 10px; } tr.odd td:hover, tr.even td:hover {} @@ -185,10 +185,165 @@ { float: right; margin-left: 2em } + div.clear-both + { + clear: both + } + div.clear-left + { + clear: left + } + div.clear-right + { + clear: right + } + #color-white + { + background: #ffffff; + color: #000000; + } + #color-black + { + background: #000000; + color: #ffffff; + } + #color-red + { + background: #ff0000; + color: #000000; + } + #color-darkRed + { + background: #800000; + color: #ffffff; + } + #color-green + { + background: #00ff00; + color: #000000; + } + #color-darkGreen + { + background: #008000; + color: #ffffff; + } + #color-blue + { + background: #0000ff; + color: #ffffff; + } + #color-darkBlue + { + background: #000080; + color: #ffffff; + } + #color-cyan + { + background: #00ffff; + color: #000000; + } + #color-darkCyan + { + background: #008080; + color: #ffffff; + } + #color-magenta + { + background: #ff00ff; + color: #000000; + } + #color-darkMagenta + { + background: #800080; + color: #ffffff; + } + #color-yellow + { + background: #ffff00; + color: #000000; + } + #color-darkYellow + { + background: #808000; + color: #ffffff; + } + #color-gray + { + background: #a0a0a4; + color: #000000; + } + #color-darkGray + { + background: #808080; + color: #ffffff; + } + #color-lightGray + { + background: #c0c0c0; + color: #000000; + } + #QtGuiColor + { + background-color: #98fd00; + color: black; + } + #QtCoreColor + { + background-color: #9c9cff; + color: black; + } + #DefaultColor + { + background-color: #f6f6dc; + color: black; + } + #FreetypeColor + { + background-color: #e6e6fa; + color: black; + } + #GLColor + { + background-color: #ffc0cb; + color: black; + } + #PthreadColor + { + background-color: #bdb76b; + color: black; + } + #OptionalColor + { + background-color: #cae1ff; + color: black; + } + #SMColor + { + background-color: #c2fafa; + color: black; + } + #MiscColor + { + background-color: #f0f9ff; + color: black; + } + #GlibColor + { + background-color: #b3b3b3; + color: black; + } + .figCaption + { + color:#363534; + font:italic 11px/1.2 Verdana; + text-align: center; + padding-top:0; + } span.comment { color: #008B00; + font-style: italic } span.string, span.char { @@ -1030,11 +1185,28 @@ padding:0px; } - .content .alignedsummary - { - margin: 15px; - } - + .content .alignedsummary + { + margin: 15px; + } + + .details + { + text-align: left; + font-size: 80%; + color: blue + } + .variableName + { + font-family: courier; + color: blue + } + .newStuff + { + text-align: left; + font-size: 80%; + color: red + } .qmltype { @@ -1381,6 +1553,10 @@ font: normal bold 13px/1 Verdana; } + .content .normallist li + { + font: normal 13px/1 Verdana; + } .indexbox a:hover, .indexbox a:visited:hover { color: #4c0033; @@ -1417,6 +1593,13 @@ background: url(../images/sprites-combined.png) no-repeat -111px -376px; padding: 0; } + .indexbox.tools .indexIcon2 + { + width: 115px; + height: 137px; + background: url(../images/sprites-combined.png) no-repeat -111px -376px; + padding: 0; + } .indexboxcont:after { content: "."; diff --git a/doc/src/tutorials/modelview.qdoc b/doc/src/tutorials/modelview.qdoc index cae7764..efd0ff2 100644 --- a/doc/src/tutorials/modelview.qdoc +++ b/doc/src/tutorials/modelview.qdoc @@ -27,7 +27,7 @@ /*! \page modelview.html - + \ingroup tutorials \startpage {index.html}{Qt Reference Documentation} \title Model/View Tutorial diff --git a/doc/src/tutorials/threads.qdoc b/doc/src/tutorials/threads.qdoc new file mode 100644 index 0000000..1d807a0 --- /dev/null +++ b/doc/src/tutorials/threads.qdoc @@ -0,0 +1,572 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page thread-basics.html + \ingroup tutorials + \startpage {index.html}{Qt Reference Documentation} + + \title Threading Basics + \brief An introduction to threads + + \section1 What Are Threads + + Threads are about doing things in parallel, just like processes. So how do + threads differ from processes? While you are making calculations on a + spreadsheet, there may also be a media player running on the same desktop + playing your favorite song. Here is an example of two processes working in + parallel: one running the spreadsheet program; one running a media player. + Multitasking is a well known term for this. A closer look at the media + player reveals that there are again things going on in parallel within one + single process. While the media player is sending music to the audio driver, + the user interface with all its bells and whistles is being constantly + updated. This is what threads are for \mdash concurrency within one single + process. + + So how is concurrency implemented? Parallel work on single core CPUs is an + illusion which is somewhat similar to the illusion of moving images in + cinema. + For processes, the illusion is produced by interrupting the processor's + work on one process after a very short time. Then the processor moves on to + the next process. In order to switch between processes, the current program + counter is saved and the next processor's program counter is loaded. This + is not sufficient because the same needs to be done with registers and + certain architecture and OS specific data. + + Just as one CPU can power two or more processes, it is also possible to let + the CPU run on two different code segments of one single process. When a + process starts, it always executes one code segment and therefore the + process is said to have one thread. However, the program may decide to + start a second thread. Then, two different code sequences are processed + simultaneously inside one process. Concurrency is achieved on single core + CPUs by repeatedly saving program counters and registers then loading the + next thread's program counters and registers. No cooperation from the + program is required to cycle between the active threads. A thread may be in + any state when the switch to the next thread occurs. + + The current trend in CPU design is to have several cores. A typical + single-threaded application can make use of only one core. However, a + program with multiple threads can be assigned to multiple cores, making + things happen in a truly concurrent way. As a result, distributing work + to more than one thread can make a program run much faster on multicore + CPUs because additional cores can be used. + + \section2 GUI Thread and Worker Thread + + As mentioned, each program has one thread when it is started. This thread + is called the "main thread" (also known as the "GUI thread" in Qt + applications). The Qt GUI must run in this thread. All widgets and several + related classes, for example QPixmap, don't work in secondary threads. + A secondary thread is commonly referred to as a "worker thread" because it + is used to offload processing work from the main thread. + + \section2 Simultaneous Access to Data + + Each thread has its own stack, which means each thread has its own call + history and local variables. Unlike processes, threads share the same + address space. The following diagram shows how the building blocks of + threads are located in memory. Program counter and registers of inactive + threads are typically kept in kernel space. There is a shared copy of the + code and a separate stack for each thread. + + \image threadvisual-example.png "Thread visualization" + + If two threads have a pointer to the same object, it is possible that both + threads will access that object at the same time and this can potentially + destroy the object's integrity. It's easy to imagine the many things that + can go wrong when two methods of the same object are executed + simultaneously. + + Sometimes it is necessary to access one object from different threads; + for example, when objects living in different threads need to communicate. + Since threads use the same address space, it is easier and faster for + threads to exchange data than it is for processes. Data does not have to be + serialized and copied. Passing pointers is possible, but there must be a + strict coordination of what thread touches which object. Simultaneous + execution of operations on one object must be prevented. There are several + ways of achieving this and some of them are described below. + + So what can be done safely? All objects created in a thread can be used + safely within that thread provided that other threads don't have references + to them and objects don't have implicit coupling with other threads. Such + implicit coupling may happen when data is shared between instances as with + static members, singletons or global data. Familiarize yourself with the + concept of \l{Reentrancy and Thread-Safety}{thread safe and reentrant} + classes and functions. + + \section1 Using Threads + + There are basically two use cases for threads: + + \list + \o Make processing faster by making use of multicore processors. + \o Keep the GUI thread or other time critical threads responsive by + offloading long lasting processing or blocking calls to other threads. + \endlist + + \section2 When to Use Alternatives to Threads + + Developers need to be very careful with threads. It is easy to start other + threads, but very hard to ensure that all shared data remains consistent. + Problems are often hard to find because they may only show up once in a + while or only on specific hardware configurations. Before creating threads + to solve certain problems, possible alternatives should be considered. + + \table + \header + \o Alternative + \o Comment + \row + \o QEventLoop::processEvents() + \o Calling QEventLoop::processEvents() repeatedly during a + time-consuming calculation prevents GUI blocking. However, this + solution doesn't scale well because the call to processEvents() may + occur too often, or not often enough, depending on hardware. + \row + \o QTimer + \o Background processing can sometimes be done conveniently using a + timer to schedule execution of a slot at some point in the future. + A timer with an interval of 0 will time out as soon as there are no + more events to process. + \row + \o QSocketNotifier QNetworkAccessManager QIODevice::readyRead() + \o This is an alternative to having one or multiple threads, each with + a blocking read on a slow network connection. As long as the + calculation in response to a chunk of network data can be executed + quickly, this reactive design is better than synchronous waiting in + threads. Reactive design is less error prone and energy efficient + than threading. In many cases there are also performance benefits. + \endtable + + In general, it is recommended to only use safe and tested paths and to + avoid introducing ad-hoc threading concepts. QtConcurrent provides an easy + interface for distributing work to all of the processor's cores. The + threading code is completely hidden in the QtConcurrent framework, so you + don't have to take care of the details. However, QtConcurrent can't be used + when communication with the running thread is needed, and it shouldn't be + used to handle blocking operations. + + \section2 Which Qt Thread Technology Should You Use? + + Sometimes you want to do more than just running a method in the context of + another thread. You may want to have an object which lives in another + thread that provides a service to the GUI thread. Maybe you want another + thread to stay alive forever to poll hardware ports and send a signal to + the GUI thread when something noteworthy has happened. Qt provides + different solutions for developing threaded applications. The right + solution depends on the purpose of the new thread as well as on the + thread's lifetime. + + \table + \header + \o Lifetime of thread + \o Development task + \o Solution + \row + \o One call + \o Run one method within another thread and quit the thread when the + method is finished. + \o Qt provides different solutions: + \list + \o Write a function and run it with QtConcurrent::run() + \o Derive a class from QRunnable and run it in the global thread + pool with QThreadPool::globalInstance()->start() + \o Derive a class from QThread, reimplement the QThread::run() + method and use QThread::start() to run it. + \endlist + + \row + \o One call + \o Operations are to be performed on all items of a container. + Processing should be performed using all available cores. A common + example is to produce thumbnails from a list of images. + \o QtConcurrent provides the \l{QtConcurrent::}{map()} function for + applying operations on every container element, + \l{QtConcurrent::}{filter()} for selecting container elements, and + the option of specifying a reduce function for combining the + remaining elements. + \row + \o One call + \o A long running operation has to be put in another thread. During the + course of processing, status information should be sent to the GUI + thread. + \o Use QThread, reimplement run and emit signals as needed. Connect the + signals to the GUI thread's slots using queued signal/slot + connections. + + \row + \o Permanent + \o Have an object living in another thread and let it perform different + tasks upon request. + This means communication to and from the worker thread is required. + \o Derive a class from QObject and implement the necessary slots and + signals, move the object to a thread with a running event loop and + communicate with the object over queued signal/slot connections. + \row + \o Permanent + \o Have an object living in another thread, let the object perform + repeated tasks such as polling a port and enable communication with + the GUI thread. + \o Same as above but also use a timer in the worker thread to implement + polling. However, the best solution for polling is to avoid it + completely. Sometimes using QSocketNotifier is an alternative. + \endtable + + + \section1 Qt Thread Basics + + QThread is a very convenient cross platform abstraction of native platform + threads. Starting a thread is very simple. Let us look at a short piece of + code that generates another thread which says hello in that thread and then + exits. + + \snippet examples/tutorials/threads/hellothread/hellothread.h 1 + + We derive a class from QThread and reimplement the \l{QThread::}{run()} + method. + + \snippet examples/tutorials/threads/hellothread/hellothread.cpp 1 + + The run method contains the code that will be run in a separate thread. In + this example, a message containing the thread ID will be printed. + QThread::start() will call the method in another thread. + + \snippet examples/tutorials/threads/hellothread/main.cpp 1 + + To start the thread, our thread object needs to be instantiated. The + \l{QThread::}{start()} method creates a new thread and calls the + reimplemented \l{QThread::}{run()} method in this new thread. Right after + \l{QThread::}{start()} is called, two program counters walk through the + program code. The main function starts with only the GUI thread running and + it should terminate with only the GUI thread running. Exiting the program + when another thread is still busy is a programming error, and therefore, + wait is called which blocks the calling thread until the + \l{QThread::}{run()} method has completed. + + This is the result of running the code: + + \badcode + hello from GUI thread 3079423696 + hello from worker thread 3076111216 + \endcode + + + \section2 QObject and Threads + + A QObject is said to have a \e{thread affinity} or, in other words, that it + lives in a certain thread. This means that, at creation time, QObject saves + a pointer to the current thread. This information becomes relevant when an + event is posted with \l{QCoreApplication::}{postEvent()}. The event will be + put in the corresponding thread's event loop. If the thread where the + QObject lives doesn't have an event loop, the event will never be delivered. + + To start an event loop, \l{QThread::}{exec()} must be called inside + \l{QThread::}{run()}. Thread affinity can be changed using + \l{QObject::}{moveToThread()}. + + As mentioned above, developers must always be careful when calling objects' + methods from other threads. Thread affinity does not change this situation. + Qt documentation marks several methods as thread-safe. + \l{QCoreApplication::}{postEvent()} is a noteworthy example. A thread-safe + method may be called from different threads simultaneously. + + In cases where there is usually no concurrent access to methods, calling + non-thread-safe methods of objects in other threads may work thousands + of times before a concurrent access occurs, causing unexpected behavior. + Writing test code does not entirely ensure thread correctness, but it is + still important. + On Linux, Valgrind and Helgrind can help detect threading errors. + + The anatomy of QThread is quite interesting: + + \list + \o QThread does not live in the new thread where \l{QThread::}{run()} is + executed. It lives in the old thread. + \o Most QThread methods are the thread's control interface and are meant to + be called from the old thread. Do not move this interface to the newly + created thread using \l{QObject::}{moveToThread()}; i.e., calling + \l{QObject::moveToThread()}{moveToThread(this)} is regarded as bad + practice. + \o \l{QThread::}{exec()} and the static methods + \l{QThread::}{usleep()}, \l{QThread::}{msleep()}, + \l{QThread::}{sleep()} are meant to be called from the newly created + thread. + \o Additional members defined in the QThread subclass are + accessible by both threads. The developer is responsible for + coordinating access. A typical strategy is to set the members before + \l{QThread::}{start()} is called. Once the worker thread is running, + the main thread should not touch the additional members anymore. After + the worker has terminated, the main thread can access the additional + members again. This is a convenient strategy for passing parameters to a + thread before it is started as well as for collecting the result once it + has terminated. + \endlist + + A QObject's parent must always be in the same thread. This has a surprising + consequence for objects generated within the \l{QThread::}{run()} method: + + \code + void HelloThread::run() + { + QObject *object1 = new QObject(this); //error, parent must be in the same thread + QObject object2; // OK + QSharedPointer <QObject> object3(new QObject); // OK + } + \endcode + + \section2 Using a Mutex to Protect the Integrity of Data + + A mutex is an object that has \l{QMutex::}{lock()} and \l{QMutex::}{unlock()} + methods and remembers if it is already locked. A mutex is designed to be + called from multiple threads. \l{QMutex::}{lock()} returns immediately if + the mutex is not locked. The next call from another thread will find the + mutex in a locked state and then \l{QMutex::}{lock()} will block the thread + until the other thread calls \l{QMutex::}{unlock()}. This functionality can + make sure that a code section will be executed by only one thread at a time. + + The following line sketches how a mutex can be used to make a method + thread-safe: + + \code + void Worker::work() + { + this->mutex.lock(); // first thread can pass, other threads will be blocked here + doWork(); + this->mutex.unlock(); + } + \endcode + + What happens if one thread does not unlock a mutex? The result can be a + frozen application. In the example above, an exception might be thrown and + \c{mutex.unlock()} will never be reached. To prevent problems like this, + QMutexLocker should be used. + + \code + void Worker::work() + { + QMutexLocker locker(&mutex); // Locks the mutex and unlocks when locker exits the scope + doWork(); + } + \endcode + + This looks easy, but mutexes introduce a new class of problems: deadlocks. + A deadlock happens when a thread waits for a mutex to become unlocked, but + the mutex remains locked because the owning thread is waiting for the first + thread to unlock it. The result is a frozen application. Mutexes can be + used to make a method thread safe. Most Qt methods aren't thread safe + because there is always a performance penalty when using mutexes. + + It isn't always possible to lock and unlock a mutex in a method. Sometimes + the need to lock spans several calls. For example, modifying a container + with an iterator requires a sequence of several calls which should not be + interrupted by other threads. In such a scenario, locking can be achieved + with a mutex that is kept outside of the object to be manipulated. With an + external mutex, the duration of locking can be adjusted to the needs of the + operation. One disadvantage is that external mutexes aid locking, but do + not enforce it because users of the object may forget to use it. + + \section2 Using the Event Loop to Prevent Data Corruption + + The event loops of Qt are a very valuable tool for inter-thread + communication. Every thread may have its own event loop. A safe way of + calling a slot in another thread is by placing that call in another + thread's event loop. This ensures that the target object finishes the + method that is currently running before another method is started. + + So how is it possible to put a method invocation in an event loop? Qt has + two ways of doing this. One way is via queued signal-slot connections; the + other way is to post an event with QCoreApplication::postEvent(). A queued + signal-slot connection is a signal slot connection that is executed + asynchronously. The internal implementation is based on posted events. The + arguments of the signal are put into the event loop and the signal method + returns immediately. + + The connected slot will be executed at a time which depends on what else is + in the event loop. + + Communication via the event loop eliminates the deadlock problem we face + when using mutexes. This is why we recommend using the event loop rather + than locking an object using a mutex. + + \section2 Dealing with Asynchronous Execution + + One way to obtain a worker thread's result is by waiting for the thread + to terminate. In many cases, however, a blocking wait isn't acceptable. The + alternative to a blocking wait are asynchronous result deliveries with + either posted events or queued signals and slots. This generates a certain + overhead because an operation's result does not appear on the next source + line, but in a slot located somewhere else in the source file. Qt + developers are used to working with this kind of asynchronous behavior + because it is much similar to the kind of event-driven programming used in + GUI applications. + + \section1 Examples + + This tutorial comes with examples for Qt's three basic ways of working with + threads. Two more examples show how to communicate with a running thread + and how a QObject can be placed in another thread, providing service to the + main thread. + + \list + \o Using QThread as shown \l{Qt thread basics}{above} + \o \l{Example 1: Using the Thread Pool}{Using the global QThreadPool} + \o \l{Example 2: Using QtConcurrent}{Using QtConcurrent} + \o \l{Example 3: Clock}{Communication with the GUI thread} + \o \l{Example 4: A Permanent Thread}{A permanent QObject in another thread + provides service to the main thread} + \endlist + + The following examples can all be compiled and run independently. The source can + be found in the examples directory: examples/tutorials/threads/ + + \section2 Example 1: Using the Thread Pool + + Creating and destroying threads frequently can be expensive. To avoid the + cost of thread creation, a thread pool can be used. A thread pool is a + place where threads can be parked and fetched. We can write the same + "hello thread" program as \l{Qt Thread Basics}{above} using the global + thread pool. We derive a class from QRunnable. The code we want to run in + another thread needs to be placed in the reimplemented QRunnable::run() + method. + + \snippet examples/tutorials/threads/hellothreadpool/hellothreadpool.cpp 1 + + We instantiate Work in main(), locate the global thread pool and use the + QThreadPool::start() method. Now the thread pool runs our worker in another + thread. Using the thread pool has a performance advantage because threads + are not destroyed after they have finished running. They are kept in a pool + and wait to be used again later. + + \section2 Example 2: Using QtConcurrent + + \snippet examples/tutorials/threads/helloconcurrent/helloconcurrent.cpp 1 + + We write a global function hello() to implement the work. QtConcurrent::run() + is used to run the function in another thread. The result is a QFuture. + QFuture provides a method called \l{QFuture::}{waitForFinished()}, which + blocks until the calculation is completed. The real power of QtConcurrent + becomes visible when data can be made available in a container. QtConcurrent + provides several functions that are able to process itemized data on all + available cores simultaneously. The use of QtConcurrent is very similar to + applying an STL algorithm to an STL container. + \l{examples-threadandconcurrent.html}{QtConcurrent Map} is a very short and + clear example about how a container of images can be scaled on all available + cores. The image scaling example uses the blocking variants of the functions + used. For every blocking function there is also a non-blocking, asynchronous + counterpart. Getting results asynchronously is implemented with QFuture and + QFutureWatcher. + + \section2 Example 3: Clock + + \image thread_clock.png "clock" + + We want to produce a clock application. The application has a GUI and a + worker thread. The worker thread checks every 10 milliseconds what time it + is. If the formatted time has changed, the result will be sent to the GUI + thread where it is displayed. + + Of course, this is an overly complicated way of designing a clock and, + actually, a separate thread is unnecessary. We would be better off placing + the timer in the main thread because the calculation made in the timer slot + is very short-lived. This example is purely for instructional use and shows + how to communicate from a worker thread to a GUI thread. Note that + communication in this direction is easy. We only need to add a signal + to QThread and make a queued signal/slot connection to the main thread. + Communication from the GUI to the worker thread is shown in the next + example. + + \snippet examples/tutorials/threads/clock/main.cpp 1 + + We've connected the \c clockThread with the label. The connection must be a + queued signal-slot connection because we want to put the call in the event + loop. + + \snippet examples/tutorials/threads/clock/clockthread.h 1 + + We have derived a class from QThread and declared the \c sendTime() signal. + + \snippet examples/tutorials/threads/clock/clockthread.cpp 1 + + The trickiest part of this example is that the timer is connected to its + slot via a direct connection. A default connection would produce a queued + signal-slot connection because the connected objects live in different + threads; remember that QThread does not live in the thread it creates. + + Still it is safe to access ClockThread::timerHit() from the worker thread + because ClockThread::timerHit() is private and only touches local variables + and a private member that isn't touched by public methods. + QDateTime::currentDateTime() isn't marked as thread-safe in Qt + documentation, however we can get away with using it in this small + example because we know that the QDateTime::currentDateTime() static + method isn't used in any other threads. + + \section2 Example 4: A Permanent Thread + + This example shows how it is possible to have a QObject in a worker thread + that accepts requests from the GUI thread, does polling using a timer and + continuously reports results back to the GUI thread. The actual work + including the polling must be implemented in a class derived from QObject. + We have called this class \c WorkerObject in the code shown below. The + thread-specific code is hidden in a class called \c Thread, derived from + QThread. + \c Thread has two additional public members. The \c launchWorker() member + takes the worker object and moves it to another thread with a started event + loop. + The call blocks for a very short moment until the thread creation operation + is completed, allowing the worker object to be used again on the next line. + The \c Thread class's code is short but somewhat involved, so we only show + how to use the class. + + \snippet examples/tutorials/threads/movedobject/main.cpp 1 + + QMetaObject::invokeMethod() calls a slot via the event loop. The worker + object's methods should not be called directly after the object has been + moved to another thread. We let the worker thread do some work and polling, + and use a timer to shut the application down after 3 seconds. Shutting the + worker down needs some care. We call \c{Thread::stop()} to exit the event + loop. We wait for the thread to terminate and, after this has occurred, we + delete the worker. + + \section1 Digging Deeper + + Threading is a very complicated subject. Qt offers more classes for + threading than we have presented in this tutorial. The following materials + can help you go into the subject in more depth: + + \list + \o Good video tutorials about threads with Qt can be found in the material + from the \l{Training Day at Qt Developer Days 2009}. + \o The \l{Thread Support in Qt} document is a good starting point into + the reference documentation. + \o Qt comes with several additional examples for + \l{Threading and Concurrent Programming Examples}{QThread and QtConcurrent}. + \o Several good books describe how to work with Qt threads. The most + extensive coverage can be found in \e{Advanced Qt Programming} by Mark + Summerfield, Prentice Hall - roughly 70 of 500 pages cover QThread and + QtConcurrent. + \endlist +*/ diff --git a/doc/src/tutorials/widgets-tutorial.qdoc b/doc/src/tutorials/widgets-tutorial.qdoc index 2125edc..4877339 100644 --- a/doc/src/tutorials/widgets-tutorial.qdoc +++ b/doc/src/tutorials/widgets-tutorial.qdoc @@ -27,6 +27,7 @@ /*! \page widgets-tutorial.html + \ingroup tutorials \title Widgets Tutorial \brief This tutorial covers basic usage of widgets and layouts, showing how they are used to build GUI applications. @@ -133,19 +134,13 @@ In the following example, we use QWidget to create and show a window with a default size: - \raw HTML - <table align="left" width="100%"> - <tr class="qt-code"><td> - \endraw - \snippet tutorials/widgets/toplevel/main.cpp main program - \raw HTML - </td><td align="right"> - \endraw - \inlineimage widgets-tutorial-toplevel.png - \raw HTML - </td></tr> - </table> - \endraw + \div {class="qt-code"} + \table + \row + \o \snippet tutorials/widgets/toplevel/main.cpp main program + \o \inlineimage widgets-tutorial-toplevel.png + \endtable + \enddiv To create a real GUI, we need to place widgets inside the window. To do this, we pass a QWidget instance to a widget's constructor, as we will @@ -161,19 +156,13 @@ passing \c window as the parent to its constructor. In this case, we add a button to the window and place it in a specific location: - \raw HTML - <table align="left" width="100%"> - <tr class="qt-code"><td> - \endraw - \snippet tutorials/widgets/childwidget/main.cpp main program - \raw HTML - </td><td align="right"> - \endraw - \inlineimage widgets-tutorial-childwidget.png - \raw HTML - </td></tr> - </table> - \endraw + \div {class="qt-code"} + \table + \row + \o \snippet tutorials/widgets/childwidget/main.cpp main program + \o \inlineimage widgets-tutorial-childwidget.png + \endtable + \enddiv The button is now a child of the window and will be deleted when the window is destroyed. Note that hiding or closing the window does not @@ -189,19 +178,13 @@ construct a label and line edit widget that we would like to arrange side-by-side. - \raw HTML - <table align="left" width="100%"> - <tr class="qt-code"><td> - \endraw - \snippet tutorials/widgets/windowlayout/main.cpp main program - \raw HTML - </td><td align="right"> - \endraw - \inlineimage widgets-tutorial-windowlayout.png - \raw HTML - </td></tr> - </table> - \endraw + \div {class="qt-code"} + \table + \row + \o \snippet tutorials/widgets/windowlayout/main.cpp main program + \o \inlineimage widgets-tutorial-windowlayout.png + \endtable + \enddiv The \c layout object we construct manages the positions and sizes of widgets supplied to it with the \l{QHBoxLayout::}{addWidget()} function. @@ -233,20 +216,14 @@ \c{mainLayout} is a QVBoxLayout that contains \c{queryLayout} and a QTableView arranged vertically. - \raw HTML - <table align="left" width="100%"> - <tr class="qt-code"><td> - \endraw - \snippet tutorials/widgets/nestedlayouts/main.cpp first part - \snippet tutorials/widgets/nestedlayouts/main.cpp last part - \raw HTML - </td><td align="right"> - \endraw - \inlineimage widgets-tutorial-nestedlayouts.png - \raw HTML - </td></tr> - </table> - \endraw + \div {class="qt-code"} + \table + \row + \o \snippet tutorials/widgets/nestedlayouts/main.cpp first part + \snippet tutorials/widgets/nestedlayouts/main.cpp last part + \o \inlineimage widgets-tutorial-nestedlayouts.png + \endtable + \enddiv Note that we call the \c{mainLayout}'s \l{QBoxLayout::}{addLayout()} function to insert the \c{queryLayout} above the \c{resultView} table. diff --git a/doc/src/widgets-and-layouts/layout.qdoc b/doc/src/widgets-and-layouts/layout.qdoc index c3db5fa..1d8214b 100644 --- a/doc/src/widgets-and-layouts/layout.qdoc +++ b/doc/src/widgets-and-layouts/layout.qdoc @@ -319,16 +319,16 @@ \section2 The Header File (\c card.h) - \snippet doc/src/snippets/code/doc_src_layout.qdoc 0 + \snippet doc/src/snippets/code/doc_src_layout.cpp 0 \section2 The Implementation File (\c card.cpp) - \snippet doc/src/snippets/code/doc_src_layout.qdoc 1 + \snippet doc/src/snippets/code/doc_src_layout.cpp 1 First we define \c{count()} to fetch the number of items in the list. - \snippet doc/src/snippets/code/doc_src_layout.qdoc 2 + \snippet doc/src/snippets/code/doc_src_layout.cpp 2 Then we define two functions that iterate over the layout: \c{itemAt()} and \c{takeAt()}. These functions are used internally by the layout system @@ -341,7 +341,7 @@ structure, we may have to spend more effort defining a linear order for the items. - \snippet doc/src/snippets/code/doc_src_layout.qdoc 3 + \snippet doc/src/snippets/code/doc_src_layout.cpp 3 \c{addItem()} implements the default placement strategy for layout items. This function must be implemented. It is used by QLayout::add(), by the @@ -351,26 +351,26 @@ QGridLayout::addItem(), QGridLayout::addWidget(), and QGridLayout::addLayout(). - \snippet doc/src/snippets/code/doc_src_layout.qdoc 4 + \snippet doc/src/snippets/code/doc_src_layout.cpp 4 The layout takes over responsibility of the items added. Since QLayoutItem does not inherit QObject, we must delete the items manually. In the destructor, we remove each item from the list using \c{takeAt()}, and then delete it. - \snippet doc/src/snippets/code/doc_src_layout.qdoc 5 + \snippet doc/src/snippets/code/doc_src_layout.cpp 5 The \c{setGeometry()} function actually performs the layout. The rectangle supplied as an argument does not include \c{margin()}. If relevant, use \c{spacing()} as the distance between items. - \snippet doc/src/snippets/code/doc_src_layout.qdoc 6 + \snippet doc/src/snippets/code/doc_src_layout.cpp 6 \c{sizeHint()} and \c{minimumSize()} are normally very similar in implementation. The sizes returned by both functions should include \c{spacing()}, but not \c{margin()}. - \snippet doc/src/snippets/code/doc_src_layout.qdoc 7 + \snippet doc/src/snippets/code/doc_src_layout.cpp 7 \section2 Further Notes diff --git a/doc/src/widgets-and-layouts/styles.qdoc b/doc/src/widgets-and-layouts/styles.qdoc index 8231fcb..9e9dd64 100644 --- a/doc/src/widgets-and-layouts/styles.qdoc +++ b/doc/src/widgets-and-layouts/styles.qdoc @@ -283,12 +283,12 @@ pointer type is correct. If the object isn't of the right type, qstyleoption_cast() returns 0. For example: - \snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qt4-styles.cpp 0 The following code snippet illustrates how to use QStyle to draw the focus rectangle from a custom widget's paintEvent(): - \snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qt4-styles.cpp 1 The next example shows how to derive from an existing style to customize the look of a graphical element: @@ -542,7 +542,7 @@ We start with a look at how QCheckBox builds it style option, which is QStyleOptionButton for checkboxes: - \snippet doc/src/snippets/code/doc_src_styles.qdoc 0 + \snippet doc/src/snippets/code/doc_src_styles.cpp 0 First we let QStyleOption set up the option with the information that is common for all widgets with \c initFrom(). We will look at @@ -561,7 +561,7 @@ attributes that are common for all widgets. We print its implementation here: - \snippet doc/src/snippets/code/doc_src_styles.qdoc 1 + \snippet doc/src/snippets/code/doc_src_styles.cpp 1 The State_Enabled is set when the widget is enabled. When the widget has focus the State_HasFocus flag is set. Equally, the @@ -625,7 +625,7 @@ notably, it wraps the methods in QStyle used for painting. The QCheckBox draws itself as follows: - \snippet doc/src/snippets/code/doc_src_styles.qdoc 2 + \snippet doc/src/snippets/code/doc_src_styles.cpp 2 QCommonStyle handles the CE_CheckBox element. The QCheckBox has two sub elements: SE_CheckBoxIndicator (the checked indicator) @@ -633,7 +633,7 @@ checkbox label). QCommonStyle also implements these sub element bounding rectangles. We have a look at the QCommonStyle code: - \snippet doc/src/snippets/code/doc_src_styles.qdoc 3 + \snippet doc/src/snippets/code/doc_src_styles.cpp 3 As can be seen from the code extract, the common style gets the bounding rectangles of the two sub elements of @@ -644,7 +644,7 @@ handles CE_CheckboxLabel. We will examine each implementation and start with CE_CheckBoxLabel: - \snippet doc/src/snippets/code/doc_src_styles.qdoc 4 + \snippet doc/src/snippets/code/doc_src_styles.cpp 4 \l{QStyle::}{visualAlignment()} adjusts the alignment of text according to the layout direction. We then draw an icon if it diff --git a/doc/src/widgets-and-layouts/stylesheet.qdoc b/doc/src/widgets-and-layouts/stylesheet.qdoc index be845c4..8cfa2b4 100644 --- a/doc/src/widgets-and-layouts/stylesheet.qdoc +++ b/doc/src/widgets-and-layouts/stylesheet.qdoc @@ -469,11 +469,11 @@ sheet. Consider the following example. First, we set a style sheet on the QApplication: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 21 + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 21 Then we set a style sheet on a QPushButton object: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 22 + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 22 The style sheet on the QPushButton forces the QPushButton (and any child widget) to have blue text, in spite of the more @@ -481,7 +481,7 @@ The result would have been the same if we had written - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 23 + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 23 except that if the QPushButton had children (which is unlikely), the style sheet would have no impact on them. @@ -500,14 +500,14 @@ For example, consider a QPushButton inside a QGroupBox: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 24 + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 24 The QPushButton does not have an explicit color set. Hence, instead of inheriting color of its parent QGroupBox, it has the system color. If we want to set the color on a QGroupBox and its children, we can write: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 25 + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 25 In contrast, setting a font and propagate using QWidget::setFont() and QWidget::setPalette() propagates to child widgets. @@ -517,7 +517,7 @@ The Type Selector can be used to style widgets of a particular type. For example, - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 26 + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 26 Qt Style Sheet uses QObject::className() of the widget to determine when to apply the Type Selector. When custom widgets are inside namespaces, @@ -526,7 +526,7 @@ when using the Type Selector for widgets inside namespaces, we must replace the "::" with "--". For example, - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 27 + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 27 \section1 Setting QObject properties @@ -1328,7 +1328,7 @@ If you subclass from QWidget, you need to provide a paintEvent for your custom QWidget as below: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 32 + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 32 The above code is a no-operation if there is no stylesheet set. @@ -3373,35 +3373,35 @@ \l{QLineEdit}s in an application. This could be achieved like this: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 88 + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 88 If we want the property to apply only to the \l{QLineEdit}s that are children (or grandchildren or grand-grandchildren) of a specific dialog, we would rather do this: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 89 + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 89 If we want the property to apply only to one specific QLineEdit, we can give it a name using QObject::setObjectName() and use an ID Selector to refer to it: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 90 + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 90 Alternatively, we can set the \l{Qt Style Sheets Reference#background-prop}{background-color} property directly on the QLineEdit, omitting the selector: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 91 + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 91 To ensure a good contrast, we should also specify a suitable color for the text: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 92 + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 92 It might be a good idea to change the colors used for selected text as well: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 93 + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 93 \section2 Customizing Using Dynamic Properties @@ -3422,7 +3422,7 @@ \c mandatoryField property on the fly and set it to true. For example: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 95 + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 95 \section2 Customizing a QPushButton Using the Box Model diff --git a/doc/src/windows-and-dialogs/mainwindow.qdoc b/doc/src/windows-and-dialogs/mainwindow.qdoc index 0bf4909..e7df502 100644 --- a/doc/src/windows-and-dialogs/mainwindow.qdoc +++ b/doc/src/windows-and-dialogs/mainwindow.qdoc @@ -198,7 +198,7 @@ the first time it is called. You can also call QMainWindow::setMenuBar() to use a custom menu bar in the main window. - \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 0 \dots \snippet examples/mainwindows/menus/mainwindow.cpp 5 \dots @@ -222,7 +222,7 @@ \snippet examples/mainwindows/sdi/mainwindow.cpp 0 \dots - \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 1 In this example, the toolbar is restricted to the top and bottom toolbar areas of the main window, and is initially placed in the @@ -244,7 +244,7 @@ required, the default can be changed with the QMainWindow::setCorner() function: - \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 2 + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 2 The following diagram shows the configuration produced by the above code. Note that the left and right dock widgets will occupy the top and bottom @@ -255,7 +255,7 @@ Once all of the main window components have been set up, the central widget is created and installed by using code similar to the following: - \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 3 + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 3 The central widget can be any subclass of QWidget. */ diff --git a/doc/src/zh_CN/getting-started/how-to-learn-qt.qdoc b/doc/src/zh_CN/getting-started/how-to-learn-qt.qdoc index ad2d702..f734e43 100644 --- a/doc/src/zh_CN/getting-started/how-to-learn-qt.qdoc +++ b/doc/src/zh_CN/getting-started/how-to-learn-qt.qdoc @@ -41,7 +41,7 @@ 现在您已ç»ç¼–写了一些å°åž‹å¯ç”¨çš„应用程åºï¼Œå¹¶å¯¹ Qt ç¼–ç¨‹æœ‰æ›´åŠ å¹¿æ³›çš„äº†è§£ã€‚æ‚¨å¯ä»¥ç›´æŽ¥ç€æ‰‹åšè‡ªå·±çš„é¡¹ç›®ï¼Œä½†æˆ‘ä»¬å»ºè®®æ‚¨é˜…è¯»ä»¥ä¸‹ä¸€äº›å…³é”®ç®€ä»‹ä»¥åŠ æ·±æ‚¨å¯¹ Qt 的了解：\l{Qt Object Model}Qt 对象模型}å’Œ\l{Signals and Slots}{ä¿¡å·å’Œæ§½}。 - \div {float-left} + \div {class="float-left"} \inlineimage qtdemo-small.png \enddiv diff --git a/examples/declarative/ui-components/tabwidget/TabWidget.qml b/examples/declarative/ui-components/tabwidget/TabWidget.qml index ac2dea3..fe838b5 100644 --- a/examples/declarative/ui-components/tabwidget/TabWidget.qml +++ b/examples/declarative/ui-components/tabwidget/TabWidget.qml @@ -45,7 +45,7 @@ Item { // Setting the default property to stack.children means any child items // of the TabWidget are actually added to the 'stack' item's children. - // See the "Writing QML Components: Properties, Methods and Signals" + // See the "Property Binding" // documentation for details on default properties. default property alias content: stack.children diff --git a/examples/tools/undoframework/commands.cpp b/examples/tools/undoframework/commands.cpp index 9e81c3e..ff7b0b7 100644 --- a/examples/tools/undoframework/commands.cpp +++ b/examples/tools/undoframework/commands.cpp @@ -136,6 +136,12 @@ AddCommand::AddCommand(DiagramItem::DiagramType addType, } //! [7] +AddCommand::~AddCommand() +{ + if (!myDiagramItem->scene()) + delete myDiagramItem; +} + //! [8] void AddCommand::undo() { diff --git a/examples/tools/undoframework/commands.h b/examples/tools/undoframework/commands.h index ba27e2d..a4e4ab9 100644 --- a/examples/tools/undoframework/commands.h +++ b/examples/tools/undoframework/commands.h @@ -87,6 +87,7 @@ class AddCommand : public QUndoCommand public: AddCommand(DiagramItem::DiagramType addType, QGraphicsScene *graphicsScene, QUndoCommand *parent = 0); + ~AddCommand(); void undo(); void redo(); diff --git a/examples/tutorials/threads/clock/clock.pro b/examples/tutorials/threads/clock/clock.pro new file mode 100755 index 0000000..450bfe4 --- /dev/null +++ b/examples/tutorials/threads/clock/clock.pro @@ -0,0 +1,14 @@ +CONFIG += console +TEMPLATE = app +SOURCES += main.cpp \ + clockthread.cpp +HEADERS += clockthread.h + +# install +target.path = $$[QT_INSTALL_EXAMPLES]/tutorials/threads/clock +sources.files = $$SOURCES $$HEADERS $$RESOURCES $$FORMS clock.pro +sources.path = $$[QT_INSTALL_EXAMPLES]/tutorials/threads/clock +INSTALLS += target sources + +symbian: include($$QT_SOURCE_TREE/examples/symbianpkgrules.pri) + diff --git a/examples/tutorials/threads/clock/clockthread.cpp b/examples/tutorials/threads/clock/clockthread.cpp new file mode 100644 index 0000000..01d3f1f --- /dev/null +++ b/examples/tutorials/threads/clock/clockthread.cpp @@ -0,0 +1,66 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include "clockthread.h" + + //This class starts another thread where it emits a signal for every new second. + +//! [1] +// clock/clockthread.cpp +void ClockThread::run() +{ + QTimer timer; + connect(&timer, SIGNAL(timeout()), this, SLOT(timerHit()), Qt::DirectConnection); + timer.setInterval(10); + timer.start(); // puts one event in the threads event queue + exec(); + timer.stop(); +} + +void ClockThread::timerHit() +{ + QString newTime= QDateTime::currentDateTime().toString("ddd MMMM d yy, hh:mm:ss"); + if(m_lastTime != newTime ){ + m_lastTime = newTime; + emit sendTime(newTime) ; + } +} +//! [1] diff --git a/examples/tutorials/threads/clock/clockthread.h b/examples/tutorials/threads/clock/clockthread.h new file mode 100644 index 0000000..966dbea --- /dev/null +++ b/examples/tutorials/threads/clock/clockthread.h @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef CLOCKTHREAD_H +#define CLOCKTHREAD_H + +#include <QString> +#include <QThread> + + + +//! [1] +// clock/clockthread.h +class ClockThread : public QThread +{ + Q_OBJECT +signals: + void sendTime(QString time); +private: + void run(); + QString m_lastTime; +private slots: + void timerHit(); + +}; +//! [1] +#endif // CLOCKTHREAD_H
\ No newline at end of file diff --git a/examples/tutorials/threads/clock/main.cpp b/examples/tutorials/threads/clock/main.cpp new file mode 100755 index 0000000..a0f86d6 --- /dev/null +++ b/examples/tutorials/threads/clock/main.cpp @@ -0,0 +1,67 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include "clockthread.h" + +//A clock that does time formatting in another thread + +//! [1] +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + // build gui + QWidget widget; + QLabel *label = new QLabel; + QHBoxLayout *layout = new QHBoxLayout(&widget); + layout->addWidget(label); + widget.setWindowTitle("clock"); + + //instantiate thread object + ClockThread clockThread; + QObject::connect(&clockThread, SIGNAL(sendTime(QString)), label, SLOT(setText(QString)), Qt::QueuedConnection); + clockThread.start(); + widget.show(); + app.exec(); + clockThread.quit(); + clockThread.wait(); + return 0; +} +//! [1] diff --git a/examples/tutorials/threads/helloconcurrent/helloconcurrent.cpp b/examples/tutorials/threads/helloconcurrent/helloconcurrent.cpp new file mode 100755 index 0000000..26ee255 --- /dev/null +++ b/examples/tutorials/threads/helloconcurrent/helloconcurrent.cpp @@ -0,0 +1,61 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtCore> +/* + says hello from main thread and secondary thread using QtConcurrent +*/ + +//! [1] +// helloconcurrent/main.cpp +void hello() +{ + qDebug() << "Hello from thread " << QThread::currentThread(); +} + +int main(int argc, char *argv[]) +{ + QCoreApplication app(argc, argv); + QFuture<void> future = QtConcurrent::run(hello); + qDebug() << "hello from GUI thread " << QThread::currentThread(); + future.waitForFinished(); + return 0; +} +//! [1] diff --git a/examples/tutorials/threads/helloconcurrent/helloconcurrent.pro b/examples/tutorials/threads/helloconcurrent/helloconcurrent.pro new file mode 100755 index 0000000..30e9413 --- /dev/null +++ b/examples/tutorials/threads/helloconcurrent/helloconcurrent.pro @@ -0,0 +1,16 @@ +QT -= gui + +CONFIG += console +CONFIG -= app_bundle +TEMPLATE = app +SOURCES += helloconcurrent.cpp + +# install +target.path = $$[QT_INSTALL_EXAMPLES]/tutorials/threads/helloconcurrent +sources.files = $$SOURCES $$HEADERS $$RESOURCES $$FORMS helloconcurrent.pro +sources.path = $$[QT_INSTALL_EXAMPLES]/tutorials/threads/helloconcurrent +INSTALLS += target sources + +symbian: include($$QT_SOURCE_TREE/examples/symbianpkgrules.pri) + + diff --git a/examples/tutorials/threads/hellothread/hellothread.cpp b/examples/tutorials/threads/hellothread/hellothread.cpp new file mode 100755 index 0000000..01cd0f5 --- /dev/null +++ b/examples/tutorials/threads/hellothread/hellothread.cpp @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QDebug> +#include "hellothread.h" +/* + * demonstrates use of QThread, says hello in another thread and terminates + */ + +//! [1] +// hellothread/hellothread.cpp +void HelloThread::run() +{ + qDebug() << "hello from worker thread " << thread()->currentThreadId(); +} +//! [1] diff --git a/examples/tutorials/threads/hellothread/hellothread.h b/examples/tutorials/threads/hellothread/hellothread.h new file mode 100755 index 0000000..a3202c6 --- /dev/null +++ b/examples/tutorials/threads/hellothread/hellothread.h @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef HELLOTHREAD_H +#define HELLOTHREAD_H + +#include <QThread> +//! [1] +// hellothread/hellothread.h +class HelloThread : public QThread +{ + Q_OBJECT +private: + void run(); +}; +//! [1] +#endif // HELLOTHREAD_H diff --git a/examples/tutorials/threads/hellothread/hellothread.pro b/examples/tutorials/threads/hellothread/hellothread.pro new file mode 100755 index 0000000..fee7025 --- /dev/null +++ b/examples/tutorials/threads/hellothread/hellothread.pro @@ -0,0 +1,17 @@ +QT -= gui + +CONFIG += console +CONFIG -= app_bundle +TEMPLATE = app +SOURCES += main.cpp \ + hellothread.cpp +HEADERS += hellothread.h + +# install +target.path = $$[QT_INSTALL_EXAMPLES]/tutorials/threads/hellothread +sources.files = $$SOURCES $$HEADERS $$RESOURCES $$FORMS hellothread.pro +sources.path = $$[QT_INSTALL_EXAMPLES]/tutorials/threads/hellothread +INSTALLS += target sources + +symbian: include($$QT_SOURCE_TREE/examples/symbianpkgrules.pri) + diff --git a/examples/tutorials/threads/hellothread/main.cpp b/examples/tutorials/threads/hellothread/main.cpp new file mode 100755 index 0000000..9a548ea --- /dev/null +++ b/examples/tutorials/threads/hellothread/main.cpp @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtCore> +#include "hellothread.h" + +//! [1] +int main(int argc, char *argv[]) +{ + QCoreApplication app(argc, argv); + HelloThread thread; + thread.start(); + qDebug() << "hello from GUI thread " << app.thread()->currentThreadId(); + thread.wait(); // do not exit before the thread is completed! + return 0; +} +//! [1] diff --git a/examples/tutorials/threads/hellothreadpool/hellothreadpool.cpp b/examples/tutorials/threads/hellothreadpool/hellothreadpool.cpp new file mode 100755 index 0000000..30410a5 --- /dev/null +++ b/examples/tutorials/threads/hellothreadpool/hellothreadpool.cpp @@ -0,0 +1,65 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +#include <QtCore> +// A hello world program to demonstrate the use of the global thread pool + +//! [1] +// hellothreadpool/main.cpp +class Work : public QRunnable +{ +public: + void run() + { + qDebug() << "Hello from thread " << QThread::currentThread(); + } +}; + +int main(int argc, char *argv[]) +{ + QCoreApplication app(argc, argv); + Work work; + work.setAutoDelete(false); + QThreadPool *threadPool = QThreadPool::globalInstance(); + threadPool->start(&work); + qDebug() << "hello from GUI thread " << QThread::currentThread(); + threadPool->waitForDone(); + return 0; +} +//! [1] diff --git a/examples/tutorials/threads/hellothreadpool/hellothreadpool.pro b/examples/tutorials/threads/hellothreadpool/hellothreadpool.pro new file mode 100755 index 0000000..9cf9c73 --- /dev/null +++ b/examples/tutorials/threads/hellothreadpool/hellothreadpool.pro @@ -0,0 +1,17 @@ +QT -= gui + +CONFIG += console +CONFIG -= app_bundle +TEMPLATE = app +SOURCES += hellothreadpool.cpp + +# install +target.path = $$[QT_INSTALL_EXAMPLES]/tutorials/threads/hellothreadpool +sources.files = $$SOURCES $$HEADERS $$RESOURCES $$FORMS hellothreadpool.pro +sources.path = $$[QT_INSTALL_EXAMPLES]/tutorials/threads/hellothreadpool +INSTALLS += target sources + +symbian: include($$QT_SOURCE_TREE/examples/symbianpkgrules.pri) + + + diff --git a/examples/tutorials/threads/movedobject/main.cpp b/examples/tutorials/threads/movedobject/main.cpp new file mode 100755 index 0000000..a244316 --- /dev/null +++ b/examples/tutorials/threads/movedobject/main.cpp @@ -0,0 +1,69 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtCore> +#include "workerobject.h" +#include "thread.h" + +/* + * moves a class derived from QObject (WorkerObject) to another thread + * and calls methods over thread boundaries. + */ + +//![1] +// movedobject/main.cpp +int main(int argc, char *argv[]) +{ + QCoreApplication app(argc, argv); + Thread thread; + qDebug() << "main thread ID: " << app.thread()->currentThreadId(); + WorkerObject *worker = new WorkerObject; + thread.launchWorker(worker); + QMetaObject::invokeMethod(worker, "doWork", Qt::QueuedConnection); + QMetaObject::invokeMethod(worker, "startPolling", Qt::QueuedConnection, Q_ARG(int, 500)); + //let application produce output for 3 seconds and quit + QTimer::singleShot(3000, &app, SLOT(quit())); + app.exec(); + thread.stop(); + thread.wait(); + delete worker; + return 0; +} +//![1] diff --git a/examples/tutorials/threads/movedobject/movedobject.pro b/examples/tutorials/threads/movedobject/movedobject.pro new file mode 100755 index 0000000..678d1d9 --- /dev/null +++ b/examples/tutorials/threads/movedobject/movedobject.pro @@ -0,0 +1,18 @@ +CONFIG += console +CONFIG -= app_bundle +TEMPLATE = app +SOURCES += main.cpp \ + workerobject.cpp \ + thread.cpp + +HEADERS += \ + workerobject.h \ + thread.h + +# install +target.path = $$[QT_INSTALL_EXAMPLES]/tutorials/threads/movedobject +sources.files = $$SOURCES $$HEADERS $$RESOURCES $$FORMS movedobject.pro +sources.path = $$[QT_INSTALL_EXAMPLES]/tutorials/threads/movedobject +INSTALLS += target sources + +symbian: include($$QT_SOURCE_TREE/examples/symbianpkgrules.pri) diff --git a/examples/tutorials/threads/movedobject/thread.cpp b/examples/tutorials/threads/movedobject/thread.cpp new file mode 100644 index 0000000..6dfe8ff --- /dev/null +++ b/examples/tutorials/threads/movedobject/thread.cpp @@ -0,0 +1,101 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "thread.h" + +/* + * QThread derived class with additional capability to move a QObject to the + * new thread, to stop the thread and move the QObject back to the thread where + *it came from. + */ + +Thread::Thread( QObject *parent) + : QThread (parent) +{ + //we need a class that receives signals from other threads and emits a signal in response + shutDownHelper=new QSignalMapper; + shutDownHelper->setMapping(this,0); + connect(this, SIGNAL(started()), this, SLOT(setReadyStatus() ), Qt::DirectConnection); + connect(this, SIGNAL(aboutToStop()), shutDownHelper, SLOT(map()) ); +} + +//------------------------------------------------------ +Thread::~Thread() +{ + delete shutDownHelper; +} + +//------------------------------------------------------ +// starts thread, moves worker to this thread and blocks +void Thread::launchWorker(QObject *worker) +{ + worker = worker; + start(); + int i=0; + worker->moveToThread(this); + shutDownHelper->moveToThread(this); + connect(shutDownHelper, SIGNAL(mapped(int) ), this, SLOT(stopExecutor()), Qt::DirectConnection ); + mutex.lock(); + waitCondition.wait(&mutex); +} + +//------------------------------------------------------ +// puts a command to stop processing in the event queue of worker thread +void Thread::stop() +{ + emit aboutToStop(); +} + +//------------------------------------------------------ + +// methods above this line should be called in gui thread context +// methods below this line are private and will be run in secondary thread context + +//------------------------------------------------------ +void Thread::stopExecutor() //secondary thread context +{ + exit(); +} + +//------------------------------------------------------ +void Thread::setReadyStatus() +{ + waitCondition.wakeAll(); +} diff --git a/examples/tutorials/threads/movedobject/thread.h b/examples/tutorials/threads/movedobject/thread.h new file mode 100644 index 0000000..e941e99 --- /dev/null +++ b/examples/tutorials/threads/movedobject/thread.h @@ -0,0 +1,67 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +#ifndef THREAD_H +#define THREAD_H + +#include <QtCore> + +class Thread :public QThread +{ + Q_OBJECT +public: + Thread( QObject *parent=0); + ~Thread(); + void stop(); + void launchWorker(QObject *worker); +private: + QObject *worker; + QSignalMapper *shutDownHelper; + QWaitCondition waitCondition; + QMutex mutex; +private slots: + void stopExecutor(); + void setReadyStatus(); +signals: + void aboutToStop(); +}; + +#endif // THREAD_H diff --git a/examples/tutorials/threads/movedobject/workerobject.cpp b/examples/tutorials/threads/movedobject/workerobject.cpp new file mode 100644 index 0000000..819da20 --- /dev/null +++ b/examples/tutorials/threads/movedobject/workerobject.cpp @@ -0,0 +1,87 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +#include <QtCore> +#include "workerobject.h" + +/* + * represents an object that lives in another thread where it polls a resource + * and communicates with the gui thread + */ + +WorkerObject::WorkerObject(QObject *parent) + : QObject(parent) +{ + timer = new QTimer(this); + connect(timer, SIGNAL(timeout()), this, SLOT(poll())); +} + +//--------------------------------------------------------------- +void WorkerObject::doWork() +{ + + qDebug() << "doing work in thread " << thread()->currentThreadId() ; +} + +//--------------------------------------------------------------- +WorkerObject::~WorkerObject() +{ + qDebug() << "destruction WorkerObject in thread " << thread()->currentThreadId(); +} + +//--------------------------------------------------------------- +void WorkerObject::startPolling(int milliseconds) +{ + count=0; + timer->start(milliseconds); +} + +//--------------------------------------------------------------- +void WorkerObject::stopPolling() +{ + timer->stop(); +} + +//--------------------------------------------------------------- +void WorkerObject::poll() +{ + qDebug() << QString("timer hit %1").arg(count); + count++; +} + diff --git a/examples/tutorials/threads/movedobject/workerobject.h b/examples/tutorials/threads/movedobject/workerobject.h new file mode 100644 index 0000000..09a827c --- /dev/null +++ b/examples/tutorials/threads/movedobject/workerobject.h @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +#ifndef WORKEROBJECT_H +#define WORKEROBJECT_H + +#include <QtCore> + +class WorkerObject : public QObject +{ + Q_OBJECT +public: + explicit WorkerObject(QObject *parent = 0); + ~WorkerObject(); +public slots: + void doWork(); + void startPolling(int milliseconds); + void stopPolling(); +private slots: + void poll(); +private: + QTimer *timer; + int count; +}; + +#endif // WORKEROBJECT_H diff --git a/examples/tutorials/threads/threads.pro b/examples/tutorials/threads/threads.pro new file mode 100644 index 0000000..d737513 --- /dev/null +++ b/examples/tutorials/threads/threads.pro @@ -0,0 +1,8 @@ +TEMPLATE = subdirs + +SUBDIRS = hellothread \ + hellothreadpool \ + helloconcurrent \ + clock \ + movedobject + diff --git a/examples/tutorials/tutorials.pro b/examples/tutorials/tutorials.pro index 34723c2..1b4667e 100644 --- a/examples/tutorials/tutorials.pro +++ b/examples/tutorials/tutorials.pro @@ -1,7 +1,8 @@ TEMPLATE = subdirs SUBDIRS = \ addressbook \ - modelview + modelview \ + threads # install diff --git a/examples/webkit/fancybrowser/fancybrowser.pro b/examples/webkit/fancybrowser/fancybrowser.pro index 3786d9c..df4dbe3 100644 --- a/examples/webkit/fancybrowser/fancybrowser.pro +++ b/examples/webkit/fancybrowser/fancybrowser.pro @@ -12,5 +12,7 @@ INSTALLS += target sources symbian { TARGET.UID3 = 0xA000CF6C + TARGET.EPOCHEAPSIZE = 0×020000 0×4000000 + TARGET.CAPABILITY += Location NetworkServices include($$QT_SOURCE_TREE/examples/symbianpkgrules.pri) } diff --git a/mkspecs/common/symbian/symbian.conf b/mkspecs/common/symbian/symbian.conf index 74acc64..549113a 100644 --- a/mkspecs/common/symbian/symbian.conf +++ b/mkspecs/common/symbian/symbian.conf @@ -162,28 +162,35 @@ exists($${EPOCROOT}epoc32/tools/qt/mkspecs/features/environment.prf) { } # Try to detect SDK version if it wasn't set by environment.prf -isEmpty(SYMBIAN_VERSION) { - exists($${EPOCROOT}epoc32/release/winscw/udeb/z/system/install/Symbianv4.sis)|exists($${EPOCROOT}epoc32/data/z/system/install/Symbianv4.sis) { - SYMBIAN_VERSION = Symbian4 +isEmpty(SYMBIAN_VERSION)|isEmpty(S60_VERSION) { + exists($${EPOCROOT}epoc32/release/winscw/udeb/z/system/install/series60v5.3.sis)|exists($${EPOCROOT}epoc32/data/z/system/install/series60v5.3.sis) { + isEmpty(SYMBIAN_VERSION): SYMBIAN_VERSION = Symbian3 + isEmpty(S60_VERSION): S60_VERSION = 5.3 } else { # The Symbian^3 PDK does not necessarily contain the required sis files. # However, libstdcppv5 first appeared in Symbian^3 (S60 5.2), so check for that too. exists($${EPOCROOT}epoc32/release/winscw/udeb/z/system/install/series60v5.2.sis)|exists($${EPOCROOT}epoc32/data/z/system/install/series60v5.2.sis)|exists($${EPOCROOT}epoc32/release/armv5/lib/libstdcppv5.dso) { - SYMBIAN_VERSION = Symbian3 + isEmpty(SYMBIAN_VERSION): SYMBIAN_VERSION = Symbian3 + isEmpty(S60_VERSION): S60_VERSION = 5.2 } else { exists($${EPOCROOT}epoc32/release/winscw/udeb/z/system/install/series60v5.1.sis)|exists($${EPOCROOT}epoc32/data/z/system/install/series60v5.1.sis) { - SYMBIAN_VERSION = Symbian2 + isEmpty(SYMBIAN_VERSION): SYMBIAN_VERSION = Symbian2 + isEmpty(S60_VERSION): S60_VERSION = 5.1 } else { exists($${EPOCROOT}epoc32/release/winscw/udeb/z/system/install/series60v5.0.sis)|exists($${EPOCROOT}epoc32/data/z/system/install/series60v5.0.sis) { - SYMBIAN_VERSION = 9.4 + isEmpty(SYMBIAN_VERSION): SYMBIAN_VERSION = 9.4 + isEmpty(S60_VERSION): S60_VERSION = 5.0 } else { exists($${EPOCROOT}epoc32/release/winscw/udeb/z/system/install/series60v3.2.sis)|exists($${EPOCROOT}epoc32/data/z/system/install/series60v3.2.sis) { - SYMBIAN_VERSION = 9.3 + isEmpty(SYMBIAN_VERSION): SYMBIAN_VERSION = 9.3 + isEmpty(S60_VERSION): S60_VERSION = 3.2 } else { exists($${EPOCROOT}epoc32/release/winscw/udeb/z/system/install/series60v3.1.sis)|exists($${EPOCROOT}epoc32/data/z/system/install/series60v3.1.sis) { - SYMBIAN_VERSION = 9.2 + isEmpty(SYMBIAN_VERSION): SYMBIAN_VERSION = 9.2 + isEmpty(S60_VERSION): S60_VERSION = 3.1 } else { - SYMBIAN_VERSION = Unknown + isEmpty(SYMBIAN_VERSION): SYMBIAN_VERSION = Unknown + isEmpty(S60_VERSION): S60_VERSION = Unknown } } } @@ -192,22 +199,6 @@ isEmpty(SYMBIAN_VERSION) { } } -isEmpty(S60_VERSION) { - contains(SYMBIAN_VERSION, "9\\.2") { - S60_VERSION = 3.1 - } else:contains(SYMBIAN_VERSION, "9\\.3") { - S60_VERSION = 3.2 - } else:contains(SYMBIAN_VERSION, "9\\.4") { - S60_VERSION = 5.0 - } else:contains(SYMBIAN_VERSION, "Symbian2") { - S60_VERSION = 5.1 - } else:contains(SYMBIAN_VERSION, "Symbian3") { - S60_VERSION = 5.2 - } else { - S60_VERSION = Unknown - } -} - # pkg_depends_webkit, pkg_depends_core, and pkg_platform_dependencies can be removed by developer # if multiple languages need to be supported by pkg file. In that case the developer should declare # multiple language compatible dependency statements him/herself. diff --git a/mkspecs/features/symbian/default_post.prf b/mkspecs/features/symbian/default_post.prf index 98ab547..470372e 100644 --- a/mkspecs/features/symbian/default_post.prf +++ b/mkspecs/features/symbian/default_post.prf @@ -85,13 +85,13 @@ contains(CONFIG, qt):!contains(TARGET.UID3, 0x2001E61C):!contains(TARGET.UID3, 0 isEmpty(TARGET.EPOCSTACKSIZE):TARGET.EPOCSTACKSIZE = 0x14000 isEmpty(TARGET.EPOCHEAPSIZE):TARGET.EPOCHEAPSIZE = 0x020000 0x800000 -# Supports Symbian^3 and Symbian^4 by default and also S60 3.1, 3.2, and 5.0 if built against any of those. +# Supports Symbian^3 platforms by default and also S60 3.1, 3.2, and 5.0 if built against any of those. platform_product_id = S60ProductID platform_product_id = $$addLanguageDependentPkgItem(platform_product_id) pkg_platform_dependencies = \ "; Default HW/platform dependencies" \ "[0x20022E6D],0,0,0,{$$platform_product_id}" \ - "[0x20032DE7],0,0,0,{$$platform_product_id}" + "[0x2003A678],0,0,0,{$$platform_product_id}" contains(S60_VERSION, 3.1)|contains(S60_VERSION, 3.2)|contains(S60_VERSION, 5.0) { pkg_platform_dependencies += \ "[0x102032BE],0,0,0,{$$platform_product_id}" \ diff --git a/mkspecs/unsupported/win32-g++-cross/qmake.conf b/mkspecs/unsupported/win32-g++-cross/qmake.conf index 7e077a1..efc3de2 100644 --- a/mkspecs/unsupported/win32-g++-cross/qmake.conf +++ b/mkspecs/unsupported/win32-g++-cross/qmake.conf @@ -52,8 +52,8 @@ QMAKE_RUN_CXX_IMP = $(CXX) -c $(CXXFLAGS) $(INCPATH) -o $@ $< QMAKE_LINK = i686-pc-mingw32-g++ QMAKE_LINK_C = i686-pc-mingw32-gcc -QMAKE_LFLAGS = -enable-stdcall-fixup -Wl,-enable-auto-import -Wl,-enable-runtime-pseudo-reloc -QMAKE_LFLAGS_EXCEPTIONS_ON = -mthreads -Wl +QMAKE_LFLAGS = -Wl,-enable-stdcall-fixup -Wl,-enable-auto-import -Wl,-enable-runtime-pseudo-reloc +QMAKE_LFLAGS_EXCEPTIONS_ON = -mthreads QMAKE_LFLAGS_EXCEPTIONS_OFF = QMAKE_LFLAGS_RELEASE = -Wl,-s QMAKE_LFLAGS_DEBUG = diff --git a/src/corelib/animation/qabstractanimation.cpp b/src/corelib/animation/qabstractanimation.cpp index 2d5cfab..f20bbf4 100644 --- a/src/corelib/animation/qabstractanimation.cpp +++ b/src/corelib/animation/qabstractanimation.cpp @@ -206,6 +206,10 @@ void QUnifiedTimer::ensureTimerUpdate() void QUnifiedTimer::updateAnimationsTime() { + //setCurrentTime can get this called again while we're the for loop. At least with pauseAnimations + if(insideTick) + return; + qint64 totalElapsed = time.elapsed(); // ignore consistentTiming in case the pause timer is active int delta = (consistentTiming && !isPauseTimerActive) ? @@ -223,12 +227,14 @@ void QUnifiedTimer::updateAnimationsTime() //it might happen in some cases that the time doesn't change because events are delayed //when the CPU load is high if (delta) { + insideTick = true; for (currentAnimationIdx = 0; currentAnimationIdx < animations.count(); ++currentAnimationIdx) { QAbstractAnimation *animation = animations.at(currentAnimationIdx); int elapsed = QAbstractAnimationPrivate::get(animation)->totalCurrentTime + (animation->direction() == QAbstractAnimation::Forward ? delta : -delta); animation->setCurrentTime(elapsed); } + insideTick = false; currentAnimationIdx = 0; } } diff --git a/src/corelib/animation/qabstractanimation_p.h b/src/corelib/animation/qabstractanimation_p.h index 1ab05cd..ba92960 100644 --- a/src/corelib/animation/qabstractanimation_p.h +++ b/src/corelib/animation/qabstractanimation_p.h @@ -202,6 +202,7 @@ private: qint64 lastTick; int timingInterval; int currentAnimationIdx; + bool insideTick; bool consistentTiming; bool slowMode; diff --git a/src/corelib/concurrent/qfutureinterface.cpp b/src/corelib/concurrent/qfutureinterface.cpp index 627d0c7..c5bd802 100644 --- a/src/corelib/concurrent/qfutureinterface.cpp +++ b/src/corelib/concurrent/qfutureinterface.cpp @@ -219,7 +219,7 @@ QString QFutureInterfaceBase::progressText() const bool QFutureInterfaceBase::isProgressUpdateNeeded() const { QMutexLocker locker(&d->m_mutex); - return (d->progressTime.elapsed() > (1000 / MaxProgressEmitsPerSecond)); + return !d->progressTime.isValid() || (d->progressTime.elapsed() > (1000 / MaxProgressEmitsPerSecond)); } void QFutureInterfaceBase::reportStarted() diff --git a/src/corelib/global/global.pri b/src/corelib/global/global.pri index d80706a..68582bf 100644 --- a/src/corelib/global/global.pri +++ b/src/corelib/global/global.pri @@ -26,6 +26,9 @@ linux*:!static:!symbian-gcce:!*-armcc* { } # Compensate for lack of platform defines in Symbian3 and Symbian4 -symbian: DEFINES += SYMBIAN_VERSION_$$upper($$replace(SYMBIAN_VERSION,\\.,_)) +symbian { + DEFINES += SYMBIAN_VERSION_$$upper($$replace(SYMBIAN_VERSION,\\.,_)) \ + S60_VERSION_$$upper($$replace(S60_VERSION,\\.,_)) +} include(../../../tools/shared/symbian/epocroot.pri) diff --git a/src/corelib/global/qglobal.cpp b/src/corelib/global/qglobal.cpp index 54b9d89..bcaed41 100644 --- a/src/corelib/global/qglobal.cpp +++ b/src/corelib/global/qglobal.cpp @@ -86,7 +86,6 @@ # include "private/qcore_symbian_p.h" _LIT(qt_S60Filter, "Series60v?.*.sis"); -_LIT(qt_symbianFilter, "Symbianv*.sis"); _LIT(qt_symbianSystemInstallDir, "z:\\system\\install\\"); #endif @@ -1203,7 +1202,7 @@ bool qSharedBuild() \value SV_SF_1 Symbian^1 \value SV_SF_2 Symbian^2 \value SV_SF_3 Symbian^3 - \value SV_SF_4 Symbian^4 + \value SV_SF_4 \e{This enum value is deprecated.} \value SV_Unknown An unknown and currently unsupported platform \sa S60Version, WinVersion, MacVersion @@ -1221,7 +1220,8 @@ bool qSharedBuild() \value SV_S60_3_2 S60 3rd Edition Feature Pack 2 \value SV_S60_5_0 S60 5th Edition \value SV_S60_5_1 S60 5th Edition Feature Pack 1 - \value SV_S60_5_2 S60 5th Edition Feature Pack 2 + \value SV_S60_5_2 Symbian^3 + \value SV_S60_5_3 To be determined - FIXME \value SV_S60_Unknown An unknown and currently unsupported platform \omitvalue SV_S60_None @@ -1829,12 +1829,10 @@ const QSysInfo::WinVersion QSysInfo::WindowsVersion = QSysInfo::windowsVersion() #ifdef Q_OS_SYMBIAN static QSysInfo::SymbianVersion cachedSymbianVersion = QSysInfo::SymbianVersion(-1); +static QSysInfo::S60Version cachedS60Version = QSysInfo::S60Version(-1); -QSysInfo::SymbianVersion QSysInfo::symbianVersion() +static void symbianInitVersions() { - if (cachedSymbianVersion != -1) - return cachedSymbianVersion; - // Use pure Symbian code, because if done using QDir, there will be a call back // to this method, resulting doing this expensive operation twice before the cache kicks in. // Pure Symbian code also makes this method ~10x faster, speeding up the application launch. @@ -1842,21 +1840,8 @@ QSysInfo::SymbianVersion QSysInfo::symbianVersion() TFindFile fileFinder(rfs); CDir* contents; - // Check for Symbian4 - TInt err = fileFinder.FindWildByDir(qt_symbianFilter, qt_symbianSystemInstallDir, contents); - if (err == KErrNone) { - QScopedPointer<CDir> contentsDeleter(contents); - err = contents->Sort(EDescending|ESortByName); - if (err == KErrNone && contents->Count() > 0 && (*contents)[0].iName.Length() >= 9) { - TInt major = (*contents)[0].iName[8] - '0'; - if (major == 4) { - return cachedSymbianVersion = SV_SF_4; - } - } - } - - // Check for S60 and Symbian3 platforms, which use older .sis naming scheme - err = fileFinder.FindWildByDir(qt_S60Filter, qt_symbianSystemInstallDir, contents); + // Check for platform version + TInt err = fileFinder.FindWildByDir(qt_S60Filter, qt_symbianSystemInstallDir, contents); if (err == KErrNone) { QScopedPointer<CDir> contentsDeleter(contents); err = contents->Sort(EDescending|ESortByName); @@ -1865,61 +1850,76 @@ QSysInfo::SymbianVersion QSysInfo::symbianVersion() TInt minor = (*contents)[0].iName[11] - '0'; if (major == 3) { if (minor == 1) { - return cachedSymbianVersion = SV_9_2; + cachedS60Version = QSysInfo::SV_S60_3_1; + cachedSymbianVersion = QSysInfo::SV_9_2; } else if (minor == 2) { - return cachedSymbianVersion = SV_9_3; + cachedS60Version = QSysInfo::SV_S60_3_2; + cachedSymbianVersion = QSysInfo::SV_9_3; } } else if (major == 5) { if (minor == 0) { - return cachedSymbianVersion = SV_9_4; - } - else if (minor == 1) { - return cachedSymbianVersion = SV_SF_2; - } - else if (minor >= 2) { - return cachedSymbianVersion = SV_SF_3; + cachedS60Version = QSysInfo::SV_S60_5_0; + cachedSymbianVersion = QSysInfo::SV_9_4; + } else if (minor == 1) { + cachedS60Version = QSysInfo::SV_S60_5_1; + cachedSymbianVersion = QSysInfo::SV_SF_2; + } else if (minor == 2) { + cachedS60Version = QSysInfo::SV_S60_5_2; + cachedSymbianVersion = QSysInfo::SV_SF_3; + } else if (minor >= 3) { + cachedS60Version = QSysInfo::SV_S60_5_3; + cachedSymbianVersion = QSysInfo::SV_SF_3; } } } } # ifdef Q_CC_NOKIAX86 - // Some emulator environments may not contain the version specific .sis files, so - // simply hardcode the version on those environments. Note that can't use - // SYMBIAN_VERSION_* defines for S60 3.x/5.0 platforms, as they do not define them - // right anyway in case .sis files are not found. + if (cachedS60Version == -1) { + // Some emulator environments may not contain the version specific .sis files, so + // simply hardcode the version on those environments. Note that can't use + // S60_VERSION_* defines for S60 3.x/5.0 platforms, as they do not define them + // right anyway in case .sis files are not found. # if defined(__SERIES60_31__) - return cachedSymbianVersion = SV_9_2; + cachedS60Version = QSysInfo::SV_S60_3_1; + cachedSymbianVersion = QSysInfo::SV_9_2; # elif defined(__S60_32__) - return cachedSymbianVersion = SV_9_3; + cachedS60Version = QSysInfo::SV_S60_3_2; + cachedSymbianVersion = QSysInfo::SV_9_3; # elif defined(__S60_50__) - return cachedSymbianVersion = SV_9_4; -# elif defined(SYMBIAN_VERSION_SYMBIAN3) - return cachedSymbianVersion = SV_SF_3; -# elif defined(SYMBIAN_VERSION_SYMBIAN4) - return cachedSymbianVersion = SV_SF_4; + cachedS60Version = QSysInfo::SV_S60_5_0; + cachedSymbianVersion = QSysInfo::SV_9_4; +# elif defined(S60_VERSION_5_2) + cachedS60Version = QSysInfo::SV_S60_5_2; + cachedSymbianVersion = QSysInfo::SV_SF_3; +# elif defined(S60_VERSION_5_3) + cachedS60Version = QSysInfo::SV_S60_5_3; + cachedSymbianVersion = QSysInfo::SV_SF_3; # endif + } # endif - //If reaching here, it was not possible to determine the version - return cachedSymbianVersion = SV_Unknown; + + if (cachedS60Version == -1) { + //If reaching here, it was not possible to determine the version + cachedS60Version = QSysInfo::SV_S60_Unknown; + cachedSymbianVersion = QSysInfo::SV_Unknown; + } +} + +QSysInfo::SymbianVersion QSysInfo::symbianVersion() +{ + if (cachedSymbianVersion == -1) + symbianInitVersions(); + + return cachedSymbianVersion; } QSysInfo::S60Version QSysInfo::s60Version() { - switch (symbianVersion()) { - case SV_9_2: - return SV_S60_3_1; - case SV_9_3: - return SV_S60_3_2; - case SV_9_4: - return SV_S60_5_0; - case SV_SF_2: - return SV_S60_5_1; - case SV_SF_3: - return SV_S60_5_2; - default: - return SV_S60_Unknown; - } + if (cachedS60Version == -1) + symbianInitVersions(); + + return cachedS60Version; } #endif // ifdef Q_OS_SYMBIAN diff --git a/src/corelib/global/qglobal.h b/src/corelib/global/qglobal.h index 8dd8850..d3b3e14 100644 --- a/src/corelib/global/qglobal.h +++ b/src/corelib/global/qglobal.h @@ -1599,7 +1599,7 @@ public: SV_SF_1 = SV_9_4, SV_SF_2 = 40, SV_SF_3 = 50, - SV_SF_4 = 60 + SV_SF_4 = 60 // Deprecated }; static SymbianVersion symbianVersion(); enum S60Version { @@ -1608,9 +1608,9 @@ public: SV_S60_3_1 = SV_9_2, SV_S60_3_2 = SV_9_3, SV_S60_5_0 = SV_9_4, - //versions beyond 5.0 are to be confirmed - it is better to use symbian version SV_S60_5_1 = SV_SF_2, - SV_S60_5_2 = SV_SF_3 + SV_S60_5_2 = SV_SF_3, + SV_S60_5_3 = 70 }; static S60Version s60Version(); #endif @@ -2517,6 +2517,10 @@ QT3_SUPPORT Q_CORE_EXPORT const char *qInstallPathSysconf(); #define Q_SYMBIAN_SUPPORTS_MULTIPLE_SCREENS #endif +#ifdef SYMBIAN_GRAPHICS_FIXNATIVEORIENTATION +#define Q_SYMBIAN_SUPPORTS_FIXNATIVEORIENTATION +#endif + //Symbian does not support data imports from a DLL #define Q_NO_DATA_RELOCATION diff --git a/src/corelib/global/qnamespace.qdoc b/src/corelib/global/qnamespace.qdoc index bc15514..07a9503 100644 --- a/src/corelib/global/qnamespace.qdoc +++ b/src/corelib/global/qnamespace.qdoc @@ -242,81 +242,25 @@ /*! \enum Qt::GlobalColor - \raw HTML - <style type="text/css" id="colorstyles"> - #white { background-color: #ffffff; color: #000000 } - #black { background-color: #000000; color: #ffffff } - #red { background-color: #ff0000; color: #000000 } - #darkRed { background-color: #800000; color: #ffffff } - #green { background-color: #00ff00; color: #000000 } - #darkGreen { background-color: #008000; color: #ffffff } - #blue { background-color: #0000ff; color: #ffffff } - #darkBlue { background-color: #000080; color: #ffffff } - #cyan { background-color: #00ffff; color: #000000 } - #darkCyan { background-color: #008080; color: #ffffff } - #magenta { background-color: #ff00ff; color: #000000 } - #darkMagenta { background-color: #800080; color: #ffffff } - #yellow { background-color: #ffff00; color: #000000 } - #darkYellow { background-color: #808000; color: #ffffff } - #gray { background-color: #a0a0a4; color: #000000 } - #darkGray { background-color: #808080; color: #ffffff } - #lightGray { background-color: #c0c0c0; color: #000000 } - </style> - \endraw - Qt's predefined QColor objects: - \value white \raw HTML - White <tt id="white">(#ffffff)</tt> - \endraw - \value black \raw HTML - Black <tt id="black">(#000000)</tt> - \endraw - \value red \raw HTML - Red <tt id="red">(#ff0000)</tt> - \endraw - \value darkRed \raw HTML - Dark red <tt id="darkRed">(#800000)</tt> - \endraw - \value green \raw HTML - Green <tt id="green">(#00ff00)</tt> - \endraw - \value darkGreen \raw HTML - Dark green <tt id="darkGreen">(#008000)</tt> - \endraw - \value blue \raw HTML - Blue <tt id="blue">(#0000ff)</tt> - \endraw - \value darkBlue \raw HTML - Dark blue <tt id="darkBlue">(#000080)</tt> - \endraw - \value cyan \raw HTML - Cyan <tt id="cyan">(#00ffff)</tt> - \endraw - \value darkCyan \raw HTML - Dark cyan <tt id="darkCyan">(#008080)</tt> - \endraw - \value magenta \raw HTML - Magenta <tt id="magenta">(#ff00ff)</tt> - \endraw - \value darkMagenta \raw HTML - Dark magenta <tt id="darkMagenta">(#800080)</tt> - \endraw - \value yellow \raw HTML - Yellow <tt id="yellow">(#ffff00)</tt> - \endraw - \value darkYellow \raw HTML - Dark yellow <tt id="darkYellow">(#808000)</tt> - \endraw - \value gray \raw HTML - Gray <tt id="gray">(#a0a0a4)</tt> - \endraw - \value darkGray \raw HTML - Dark gray <tt id="darkGray">(#808080)</tt> - \endraw - \value lightGray \raw HTML - Light gray <tt id="lightGray">(#c0c0c0)</tt> - \endraw + \value white \span {id="color-white"} {White (#ffffff) } + \value black \span {id="color-black"} {Black (#000000) } + \value red \span {id="color-red"} {Red (#ff0000) } + \value darkRed \span {id="color-darkRed"} {Dark red (#800000) } + \value green \span {id="color-green"} {Green (#00ff00) } + \value darkGreen \span {id="color-darkGreen"} {Dark green (#008000) } + \value blue \span {id="color-blue"} {Blue (#0000ff) } + \value darkBlue \span {id="color-darkBlue"} {Dark blue (#000080) } + \value cyan \span {id="color-cyan"} {Cyan (#00ffff) } + \value darkCyan \span {id="color-darkCyan"} {Dark cyan (#008080) } + \value magenta \span {id="color-magenta"} {Magenta (#ff00ff) } + \value darkMagenta \span {id="color-darkMagenta"} {Dark magenta (#800080) } + \value yellow \span {id="color-yellow"} {Yellow (#ffff00) } + \value darkYellow \span {id="color-darkYellow"} {Dark yellow (#808000) } + \value gray \span {id="color-gray"} {Gray (#a0a0a4) } + \value darkGray \span {id="color-darkGray"} {Dark gray (#808080) } + \value lightGray \span {id="color-lightGray"} {Light gray (#c0c0c0) } \value transparent a transparent black value (i.e., QColor(0, 0, 0, 0)) \value color0 0 pixel value (for bitmaps) \value color1 1 pixel value (for bitmaps) @@ -2882,7 +2826,7 @@ INT_MIN, inclusive. For example, you can define custom priorities as being relative to each other: - \snippet doc/src/snippets/code/doc_src_qnamespace.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qnamespace.cpp 1 \sa QCoreApplication::postEvent() */ diff --git a/src/corelib/io/qiodevice.cpp b/src/corelib/io/qiodevice.cpp index 76e8409..8759f8b 100644 --- a/src/corelib/io/qiodevice.cpp +++ b/src/corelib/io/qiodevice.cpp @@ -1628,10 +1628,11 @@ QString QIODevice::errorString() const \fn qint64 QIODevice::readData(char *data, qint64 maxSize) Reads up to \a maxSize bytes from the device into \a data, and - returns the number of bytes read or -1 if an error occurred. If - there are no bytes to be read, this function should return -1 if - there can never be more bytes available (for example: socket - closed, pipe closed, sub-process finished). + returns the number of bytes read or -1 if an error occurred. + + If there are no bytes to be read and there can never be more bytes + available (examples include socket closed, pipe closed, sub-process + finished), this function returns -1. This function is called by QIODevice. Reimplement this function when creating a subclass of QIODevice. diff --git a/src/corelib/io/qresource.cpp b/src/corelib/io/qresource.cpp index 0435256..cd8c1a3 100644 --- a/src/corelib/io/qresource.cpp +++ b/src/corelib/io/qresource.cpp @@ -373,7 +373,7 @@ QResourcePrivate::ensureChildren() const Constructs a QResource pointing to \a file. \a locale is used to load a specific localization of a resource data. - \sa QFileInfo, searchPaths(), setFileName(), setLocale() + \sa QFileInfo, QDir::searchPaths(), setFileName(), setLocale() */ QResource::QResource(const QString &file, const QLocale &locale) : d_ptr(new QResourcePrivate(this)) @@ -418,7 +418,7 @@ QLocale QResource::locale() const /*! Sets a QResource to point to \a file. \a file can either be absolute, in which case it is opened directly, if relative then the file will be - tried to be found in searchPaths(). + tried to be found in QDir::searchPaths(). \sa absoluteFilePath() */ @@ -446,7 +446,7 @@ QString QResource::fileName() const /*! Returns the real path that this QResource represents, if the resource - was found via the searchPaths() it will be indicated in the path. + was found via the QDir::searchPaths() it will be indicated in the path. \sa fileName() */ diff --git a/src/corelib/kernel/qtranslator.cpp b/src/corelib/kernel/qtranslator.cpp index daa5dc6..3570564 100644 --- a/src/corelib/kernel/qtranslator.cpp +++ b/src/corelib/kernel/qtranslator.cpp @@ -354,10 +354,15 @@ QTranslator::~QTranslator() } /*! - Loads \a filename + \a suffix (".qm" if the \a suffix is - not specified), which may be an absolute file name or relative - to \a directory. Returns true if the translation is successfully - loaded; otherwise returns false. + + Loads \a filename + \a suffix (".qm" if the \a suffix is not + specified), which may be an absolute file name or relative to \a + directory. Returns true if the translation is successfully loaded; + otherwise returns false. + + If \a directory is not specified, the directory of the + application's executable is used (i.e., as + \l{QCoreApplication::}{applicationDirPath()}). The previous contents of this translator object are discarded. diff --git a/src/corelib/plugin/qplugin.qdoc b/src/corelib/plugin/qplugin.qdoc index 54b2b38..7043fa0 100644 --- a/src/corelib/plugin/qplugin.qdoc +++ b/src/corelib/plugin/qplugin.qdoc @@ -51,7 +51,7 @@ If you want to use Q_DECLARE_INTERFACE with interface classes declared in a namespace then you have to make sure the Q_DECLARE_INTERFACE is not inside a namespace though. For example: - \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qplugin.cpp 0 \sa Q_INTERFACES(), Q_EXPORT_PLUGIN2(), {How to Create Qt Plugins} */ @@ -82,7 +82,7 @@ Example: - \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qplugin.cpp 1 See the \l{tools/plugandpaint}{Plug & Paint} example for details. @@ -102,14 +102,14 @@ Example: - \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 2 + \snippet doc/src/snippets/code/doc_src_qplugin.cpp 2 Static plugins must also be included by the linker when your application is built. For Qt's predefined plugins, you can use the \c QTPLUGIN to add the required plugins to your build. For example: - \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 3 + \snippet doc/src/snippets/code/doc_src_qplugin.pro 3 \sa {Static Plugins}, {How to Create Qt Plugins}, {Using qmake} */ diff --git a/src/corelib/statemachine/qhistorystate.cpp b/src/corelib/statemachine/qhistorystate.cpp index 350c1a0..7093c32 100644 --- a/src/corelib/statemachine/qhistorystate.cpp +++ b/src/corelib/statemachine/qhistorystate.cpp @@ -168,6 +168,9 @@ QAbstractState *QHistoryState::defaultState() const /*! Sets this history state's default state to be the given \a state. \a state must be a sibling of this history state. + + Note that this function does not set \a state as the initial state + of its parent. */ void QHistoryState::setDefaultState(QAbstractState *state) { diff --git a/src/corelib/tools/qalgorithms.qdoc b/src/corelib/tools/qalgorithms.qdoc index 34918a3..a9b7ddc 100644 --- a/src/corelib/tools/qalgorithms.qdoc +++ b/src/corelib/tools/qalgorithms.qdoc @@ -60,14 +60,14 @@ a particular value. If you need that functionality, you can use qFill(): - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 0 qFill() takes a begin iterator, an end iterator, and a value. In the example above, we pass \c list.begin() and \c list.end() as the begin and end iterators, but this doesn't have to be the case: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 1 Different algorithms can have different requirements for the iterators they accept. For example, qFill() accepts two @@ -98,13 +98,13 @@ name_table array and return the corresponding Unicode value from the \c value_table if the entity is recognized: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 2 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 2 This kind of code is for advanced users only; for most applications, a QMap- or QHash-based approach would work just as well: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 3 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 3 \section1 Types of Iterators @@ -185,7 +185,7 @@ position \a begin2 + 1; and so on. Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 4 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 4 \sa qCopyBackward(), {input iterators}, {output iterators} */ @@ -201,7 +201,7 @@ at position \a end2 - 2; and so on. Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 5 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 5 \sa qCopy(), {bidirectional iterators} */ @@ -214,7 +214,7 @@ items compare equal; otherwise returns false. Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 6 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 6 This function requires the item type (in the example above, QString) to implement \c operator==(). @@ -228,7 +228,7 @@ Fills the range [\a begin, \a end) with \a value. Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 7 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 7 \sa qCopy(), {forward iterators} */ @@ -249,7 +249,7 @@ value isn't found. Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 8 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 8 This function requires the item type (in the example above, QString) to implement \c operator==(). @@ -278,7 +278,7 @@ Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 9 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 9 This function requires the item type (in the example above, \c int) to implement \c operator==(). @@ -302,7 +302,7 @@ of \a value in the variable passed as a reference in argument \a n. Exchanges the values of variables \a var1 and \a var2. Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 10 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 10 */ /*! \fn void qSort(RandomAccessIterator begin, RandomAccessIterator end) @@ -312,7 +312,7 @@ of \a value in the variable passed as a reference in argument \a n. using the quicksort algorithm. Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 11 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 11 The sort algorithm is efficient on large data sets. It operates in \l {linear-logarithmic time}, O(\e{n} log \e{n}). @@ -338,13 +338,13 @@ of \a value in the variable passed as a reference in argument \a n. For example, here's how to sort the strings in a QStringList in case-insensitive alphabetical order: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 12 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 12 To sort values in reverse order, pass \l{qGreater()}{qGreater<T>()} as the \a lessThan parameter. For example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 13 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 13 If neither of the two items is "less than" the other, the items are taken to be equal. It is then undefined which one of the two @@ -356,7 +356,7 @@ of \a value in the variable passed as a reference in argument \a n. following code shows how to sort a list of strings case insensitively using QMap: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 14 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 14 \sa QMap */ @@ -382,7 +382,7 @@ of \a value in the variable passed as a reference in argument \a n. property is often useful when sorting user-visible data. Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 15 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 15 The sort algorithm is efficient on large data sets. It operates in \l {linear-logarithmic time}, O(\e{n} log \e{n}). @@ -405,7 +405,7 @@ of \a value in the variable passed as a reference in argument \a n. For example, here's how to sort the strings in a QStringList in case-insensitive alphabetical order: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 16 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 16 Note that earlier versions of Qt allowed using a lessThan function that took its arguments by non-const reference. From 4.3 and on this is no longer possible, @@ -415,7 +415,7 @@ of \a value in the variable passed as a reference in argument \a n. \l{qGreater()}{qGreater<T>()} as the \a lessThan parameter. For example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 17 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 17 If neither of the two items is "less than" the other, the items are taken to be equal. The item that appeared before the other in the @@ -444,7 +444,7 @@ of \a value in the variable passed as a reference in argument \a n. ascending order; see qSort(). Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 18 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 18 This function requires the item type (in the example above, \c{int}) to implement \c operator<(). @@ -452,7 +452,7 @@ of \a value in the variable passed as a reference in argument \a n. qLowerBound() can be used in conjunction with qUpperBound() to iterate over all occurrences of the same value: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 19 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 19 \sa qUpperBound(), qBinaryFind() */ @@ -494,7 +494,7 @@ of \a value in the variable passed as a reference in argument \a n. ascending order; see qSort(). Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 20 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 20 This function requires the item type (in the example above, \c{int}) to implement \c operator<(). @@ -502,7 +502,7 @@ of \a value in the variable passed as a reference in argument \a n. qUpperBound() can be used in conjunction with qLowerBound() to iterate over all occurrences of the same value: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 21 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 21 \sa qLowerBound(), qBinaryFind() */ @@ -545,7 +545,7 @@ of \a value in the variable passed as a reference in argument \a n. finer control. Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 22 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 22 This function requires the item type (in the example above, QString) to implement \c operator<(). @@ -587,7 +587,7 @@ of \a value in the variable passed as a reference in argument \a n. example, \c{QWidget *}). Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 23 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 23 Notice that qDeleteAll() doesn't remove the items from the container; it merely calls \c delete on them. In the example @@ -618,7 +618,7 @@ of \a value in the variable passed as a reference in argument \a n. Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 24 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 24 \sa {qGreater()}{qGreater<T>()} */ @@ -631,7 +631,7 @@ of \a value in the variable passed as a reference in argument \a n. Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 25 + \snippet doc/src/snippets/code/doc_src_qalgorithms.cpp 25 \sa {qLess()}{qLess<T>()} */ diff --git a/src/corelib/tools/qbytearray.cpp b/src/corelib/tools/qbytearray.cpp index 4799abd..1c9b654 100644 --- a/src/corelib/tools/qbytearray.cpp +++ b/src/corelib/tools/qbytearray.cpp @@ -1387,7 +1387,7 @@ QByteArray::QByteArray(int size, Qt::Initialization) If \a size is less than the current size, bytes are removed from the end. - \sa size() + \sa size(), truncate() */ void QByteArray::resize(int size) diff --git a/src/corelib/tools/qcache.qdoc b/src/corelib/tools/qcache.qdoc index 991238b..9e12c92 100644 --- a/src/corelib/tools/qcache.qdoc +++ b/src/corelib/tools/qcache.qdoc @@ -39,11 +39,11 @@ definition of a cache that stores objects of type Employee associated with an integer key: - \snippet doc/src/snippets/code/doc_src_qcache.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qcache.cpp 0 Here's how to insert an object in the cache: - \snippet doc/src/snippets/code/doc_src_qcache.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qcache.cpp 1 The advantage of using QCache over some other key-based data structure (such as QMap or QHash) is that QCache automatically @@ -59,7 +59,7 @@ By default, QCache's maxCost() is 100. You can specify a different value in the QCache constructor: - \snippet doc/src/snippets/code/doc_src_qcache.qdoc 2 + \snippet doc/src/snippets/code/doc_src_qcache.cpp 2 Each time you call insert(), you can specify a cost as third argument (after the key and a pointer to the object to insert). diff --git a/src/corelib/tools/qiterator.qdoc b/src/corelib/tools/qiterator.qdoc index d651343..6830442 100644 --- a/src/corelib/tools/qiterator.qdoc +++ b/src/corelib/tools/qiterator.qdoc @@ -50,7 +50,7 @@ the list (before the first item). Here's how to iterate over all the elements sequentially: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 0 The next() function returns the next item in the list and advances the iterator. Unlike STL-style iterators, Java-style @@ -65,7 +65,7 @@ Here's how to iterate over the elements in reverse order: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 1 If you want to find all occurrences of a particular value, use findNext() or findPrevious() in a loop. @@ -98,7 +98,7 @@ beginning of the list (before the first item). Here's how to iterate over all the elements sequentially: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 2 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 2 The next() function returns the next item in the list and advances the iterator. Unlike STL-style iterators, Java-style @@ -113,7 +113,7 @@ Here's how to iterate over the elements in reverse order: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 3 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 3 If you want to find all occurrences of a particular value, use findNext() or findPrevious() in a loop. @@ -150,7 +150,7 @@ of the vector (before the first item). Here's how to iterate over all the elements sequentially: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 4 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 4 The next() function returns the next item in the vector and advances the iterator. Unlike STL-style iterators, Java-style @@ -165,7 +165,7 @@ Here's how to iterate over the elements in reverse order: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 5 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 5 If you want to find all occurrences of a particular value, use findNext() or findPrevious() in a loop. @@ -197,7 +197,7 @@ the first item). Here's how to iterate over all the elements sequentially: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 6 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 6 The next() function returns the next item in the set and advances the iterator. Unlike STL-style iterators, Java-style @@ -212,7 +212,7 @@ Here's how to iterate over the elements in reverse order: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 7 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 7 If you want to find all occurrences of a particular value, use findNext() or findPrevious() in a loop. @@ -251,7 +251,7 @@ of the list (before the first item). Here's how to iterate over all the elements sequentially: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 8 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 8 The next() function returns the next item in the list and advances the iterator. Unlike STL-style iterators, Java-style @@ -266,7 +266,7 @@ Here's how to iterate over the elements in reverse order: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 9 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 9 If you want to find all occurrences of a particular value, use findNext() or findPrevious() in a loop. @@ -277,7 +277,7 @@ insert(). Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 10 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 10 The example traverses a list, replacing negative numbers with their absolute values, and eliminating zeroes. @@ -312,7 +312,7 @@ beginning of the list (before the first item). Here's how to iterate over all the elements sequentially: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 11 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 11 The next() function returns the next item in the list and advances the iterator. Unlike STL-style iterators, Java-style @@ -327,7 +327,7 @@ Here's how to iterate over the elements in reverse order: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 12 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 12 If you want to find all occurrences of a particular value, use findNext() or findPrevious() in a loop. @@ -338,7 +338,7 @@ insert(). Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 13 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 13 The example traverses a list, replacing negative numbers with their absolute values, and eliminating zeroes. @@ -378,7 +378,7 @@ beginning of the list (before the first item). Here's how to iterate over all the elements sequentially: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 14 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 14 The next() function returns the next item in the vector and advances the iterator. Unlike STL-style iterators, Java-style @@ -393,7 +393,7 @@ Here's how to iterate over the elements in reverse order: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 15 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 15 If you want to find all occurrences of a particular value, use findNext() or findPrevious() in a loop. @@ -404,7 +404,7 @@ insert(). Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 16 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 16 The example traverses a vector, replacing negative numbers with their absolute values, and eliminating zeroes. @@ -440,7 +440,7 @@ of the set (before the first item). Here's how to iterate over all the elements sequentially: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 17 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 17 The next() function returns the next item in the set and advances the iterator. Unlike STL-style iterators, Java-style @@ -455,7 +455,7 @@ Here's how to iterate over the elements in reverse order: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 18 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 18 If you want to remove items as you iterate over the set, use remove(). @@ -755,7 +755,7 @@ traversal functions (next(), previous(), findNext(), findPrevious()). Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 19 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 19 \sa insert(), setValue() */ @@ -766,7 +766,7 @@ traversal functions (next(), previous(), findNext(), findPrevious()). Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 20 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 20 \sa insert(), setValue() */ @@ -777,7 +777,7 @@ traversal functions (next(), previous(), findNext(), findPrevious()). Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 21 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 21 \sa insert(), setValue() */ @@ -788,7 +788,7 @@ traversal functions (next(), previous(), findNext(), findPrevious()). Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 22 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 22 \sa value() */ @@ -802,7 +802,7 @@ findPrevious(). Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 23 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 23 \sa value(), remove(), insert() */ @@ -816,7 +816,7 @@ findPrevious(). Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 24 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 24 \sa value(), remove(), insert() */ @@ -830,7 +830,7 @@ findPrevious(). Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 25 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 25 \sa value(), remove(), insert() */ @@ -889,7 +889,7 @@ the map (before the first item). Here's how to iterate over all the elements sequentially: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 26 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 26 The next() function returns the next item in the map and advances the iterator. The key() and value() functions return the @@ -906,12 +906,12 @@ Here's how to iterate over the elements in reverse order: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 27 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 27 If you want to find all occurrences of a particular value, use findNext() or findPrevious() in a loop. For example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 28 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 28 Multiple iterators can be used on the same map. If the map is modified while a QMapIterator is active, the QMapIterator will @@ -941,7 +941,7 @@ the hash (before the first item). Here's how to iterate over all the elements sequentially: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 29 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 29 The next() function returns the next item in the hash and advances the iterator. The key() and value() functions return the @@ -958,12 +958,12 @@ Here's how to iterate over the elements in reverse order: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 30 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 30 If you want to find all occurrences of a particular value, use findNext() or findPrevious() in a loop. For example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 31 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 31 Multiple iterators can be used on the same hash. If the hash is modified while a QHashIterator is active, the QHashIterator will @@ -994,7 +994,7 @@ of the map (before the first item). Here's how to iterate over all the elements sequentially: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 32 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 32 The next() function returns the next item in the map and advances the iterator. The key() and value() functions return the @@ -1011,12 +1011,12 @@ Here's how to iterate over the elements in reverse order: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 33 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 33 If you want to find all occurrences of a particular value, use findNext() or findPrevious() in a loop. For example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 34 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 34 If you want to remove items as you iterate over the map, use remove(). If you want to modify the value of an item, use @@ -1024,7 +1024,7 @@ Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 35 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 35 The example removes all (key, value) pairs where the key and the value are the same. @@ -1059,7 +1059,7 @@ of the hash (before the first item). Here's how to iterate over all the elements sequentially: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 36 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 36 The next() function returns the next item in the hash and advances the iterator. The key() and value() functions return the @@ -1076,12 +1076,12 @@ Here's how to iterate over the elements in reverse order: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 37 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 37 If you want to find all occurrences of a particular value, use findNext() or findPrevious() in a loop. For example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 38 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 38 If you want to remove items as you iterate over the hash, use remove(). If you want to modify the value of an item, use @@ -1089,7 +1089,7 @@ Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 39 + \snippet doc/src/snippets/code/doc_src_qiterator.cpp 39 The example removes all (key, value) pairs where the key and the value are the same. diff --git a/src/corelib/tools/qmap.cpp b/src/corelib/tools/qmap.cpp index c548663..9e13fcc 100644 --- a/src/corelib/tools/qmap.cpp +++ b/src/corelib/tools/qmap.cpp @@ -1087,7 +1087,7 @@ void QMapData::dump() \overload - The prefix -- operator (\c{--i}) makes the preceding item + The postfix -- operator (\c{i--}) makes the preceding item current and returns an iterator pointing to the previously current item. */ diff --git a/src/corelib/tools/qpair.qdoc b/src/corelib/tools/qpair.qdoc index b900c4f..925100d 100644 --- a/src/corelib/tools/qpair.qdoc +++ b/src/corelib/tools/qpair.qdoc @@ -40,12 +40,12 @@ Here's an example of a QPair that stores one QString and one \c double value: - \snippet doc/src/snippets/code/doc_src_qpair.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qpair.cpp 0 The components are accessible as public data members called \l first and \l second. For example: - \snippet doc/src/snippets/code/doc_src_qpair.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qpair.cpp 1 QPair's template data types (T1 and T2) must be \l{assignable data types}. You cannot, for example, store a QWidget as a value; @@ -186,7 +186,7 @@ Returns a QPair\<T1, T2\> that contains \a value1 and \a value2. Example: - \snippet doc/src/snippets/code/doc_src_qpair.qdoc 2 + \snippet doc/src/snippets/code/doc_src_qpair.cpp 2 This is equivalent to QPair<T1, T2>(\a value1, \a value2), but usually requires less typing. diff --git a/src/corelib/tools/qset.qdoc b/src/corelib/tools/qset.qdoc index 30880d5..8748fd9 100644 --- a/src/corelib/tools/qset.qdoc +++ b/src/corelib/tools/qset.qdoc @@ -40,19 +40,19 @@ Here's an example QSet with QString values: - \snippet doc/src/snippets/code/doc_src_qset.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qset.cpp 0 To insert a value into the set, use insert(): - \snippet doc/src/snippets/code/doc_src_qset.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qset.cpp 1 Another way to insert items into the set is to use operator<<(): - \snippet doc/src/snippets/code/doc_src_qset.qdoc 2 + \snippet doc/src/snippets/code/doc_src_qset.cpp 2 To test whether an item belongs to the set or not, use contains(): - \snippet doc/src/snippets/code/doc_src_qset.qdoc 3 + \snippet doc/src/snippets/code/doc_src_qset.cpp 3 If you want to navigate through all the values stored in a QSet, you can use an iterator. QSet supports both \l{Java-style @@ -60,18 +60,18 @@ iterators} (QSet::iterator and QSet::const_iterator). Here's how to iterate over a QSet<QWidget *> using a Java-style iterator: - \snippet doc/src/snippets/code/doc_src_qset.qdoc 4 + \snippet doc/src/snippets/code/doc_src_qset.cpp 4 Here's the same code, but using an STL-style iterator: - \snippet doc/src/snippets/code/doc_src_qset.qdoc 5 + \snippet doc/src/snippets/code/doc_src_qset.cpp 5 QSet is unordered, so an iterator's sequence cannot be assumed to be predictable. If ordering by key is required, use a QMap. To navigate through a QSet, you can also use \l{foreach}: - \snippet doc/src/snippets/code/doc_src_qset.qdoc 6 + \snippet doc/src/snippets/code/doc_src_qset.cpp 6 Items can be removed from the set using remove(). There is also a clear() function that removes all items. @@ -194,7 +194,7 @@ This function is useful for code that needs to build a huge set and wants to avoid repeated reallocation. For example: - \snippet doc/src/snippets/code/doc_src_qset.qdoc 7 + \snippet doc/src/snippets/code/doc_src_qset.cpp 7 Ideally, \a size should be slightly more than the maximum number of elements expected in the set. \a size doesn't have to be prime, @@ -610,18 +610,18 @@ start iterating. Here's a typical loop that prints all the items stored in a set: - \snippet doc/src/snippets/code/doc_src_qset.qdoc 8 + \snippet doc/src/snippets/code/doc_src_qset.cpp 8 Here's a loop that removes certain items (all those that start with 'J') from a set while iterating: - \snippet doc/src/snippets/code/doc_src_qset.qdoc 9 + \snippet doc/src/snippets/code/doc_src_qset.cpp 9 STL-style iterators can be used as arguments to \l{generic algorithms}. For example, here's how to find an item in the set using the qFind() algorithm: - \snippet doc/src/snippets/code/doc_src_qset.qdoc 10 + \snippet doc/src/snippets/code/doc_src_qset.cpp 10 Multiple iterators can be used on the same set. However, you may not attempt to modify the container while iterating on it. @@ -653,13 +653,13 @@ start iterating. Here's a typical loop that prints all the items stored in a set: - \snippet doc/src/snippets/code/doc_src_qset.qdoc 11 + \snippet doc/src/snippets/code/doc_src_qset.cpp 11 STL-style iterators can be used as arguments to \l{generic algorithms}. For example, here's how to find an item in the set using the qFind() algorithm: - \snippet doc/src/snippets/code/doc_src_qset.qdoc 12 + \snippet doc/src/snippets/code/doc_src_qset.cpp 12 Multiple iterators can be used on the same set. However, you may not attempt to modify the container while iterating on it. @@ -893,7 +893,7 @@ Example: - \snippet doc/src/snippets/code/doc_src_qset.qdoc 13 + \snippet doc/src/snippets/code/doc_src_qset.cpp 13 \sa fromList(), QList::fromSet(), qSort() */ @@ -918,7 +918,7 @@ Example: - \snippet doc/src/snippets/code/doc_src_qset.qdoc 14 + \snippet doc/src/snippets/code/doc_src_qset.cpp 14 \sa toList(), QList::toSet() */ diff --git a/src/corelib/tools/qtextboundaryfinder.cpp b/src/corelib/tools/qtextboundaryfinder.cpp index c2bb094..34bc406 100644 --- a/src/corelib/tools/qtextboundaryfinder.cpp +++ b/src/corelib/tools/qtextboundaryfinder.cpp @@ -457,33 +457,23 @@ QTextBoundaryFinder::BoundaryReasons QTextBoundaryFinder::boundaryReasons() cons return NotAtBoundary; return StartWord; } - if (pos >= length - 1) { + if (pos == length) { if (d->attributes[length-1].whiteSpace) return NotAtBoundary; return EndWord; } - BoundaryReasons answer; - const bool nextIsSpace = d->attributes[pos + 1].whiteSpace; + const bool nextIsSpace = d->attributes[pos].whiteSpace; const bool prevIsSpace = d->attributes[pos - 1].whiteSpace; - if (d->attributes[pos].whiteSpace) - answer = EndWord; - else if (!prevIsSpace) { - answer = StartWord; - answer |= EndWord; - } - - if (prevIsSpace) - answer |= StartWord; - if (nextIsSpace) - answer |= EndWord; - if (answer == 0) { - answer = StartWord; - answer |= EndWord; - } - - return answer; + if (prevIsSpace && !nextIsSpace) + return StartWord; + else if (!prevIsSpace && nextIsSpace) + return EndWord; + else if (!prevIsSpace && !nextIsSpace) + return BoundaryReasons(StartWord | EndWord); + else + return NotAtBoundary; } QT_END_NAMESPACE diff --git a/src/corelib/tools/qvarlengtharray.qdoc b/src/corelib/tools/qvarlengtharray.qdoc index 957bca7..3c80c1c 100644 --- a/src/corelib/tools/qvarlengtharray.qdoc +++ b/src/corelib/tools/qvarlengtharray.qdoc @@ -35,12 +35,12 @@ The C++ language doesn't support variable-length arrays on the stack. For example, the following code won't compile: - \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qvarlengtharray.cpp 0 The alternative is to allocate the array on the heap (with \c{new}): - \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qvarlengtharray.cpp 1 However, if myfunc() is called very frequently from the application's inner loop, heap allocation can be a major source @@ -53,7 +53,7 @@ it is much faster than heap allocation. Example: - \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 2 + \snippet doc/src/snippets/code/doc_src_qvarlengtharray.cpp 2 In the example above, QVarLengthArray will preallocate 1024 elements on the stack and use them unless \c{n + 1} is greater @@ -223,7 +223,7 @@ be used to access and modify the items in the array. Example: - \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 3 + \snippet doc/src/snippets/code/doc_src_qvarlengtharray.cpp 3 The pointer remains valid as long as the array isn't reallocated. diff --git a/src/declarative/graphicsitems/qdeclarativeflickable.cpp b/src/declarative/graphicsitems/qdeclarativeflickable.cpp index bfebff6..f42e55a 100644 --- a/src/declarative/graphicsitems/qdeclarativeflickable.cpp +++ b/src/declarative/graphicsitems/qdeclarativeflickable.cpp @@ -399,7 +399,7 @@ void QDeclarativeFlickablePrivate::updateBeginningEnd() \section1 Example Usage - \div {float-right} + \div {class="float-right"} \inlineimage flickable.gif \enddiv diff --git a/src/declarative/graphicsitems/qdeclarativeflipable.cpp b/src/declarative/graphicsitems/qdeclarativeflipable.cpp index 5fda758..d23374b 100644 --- a/src/declarative/graphicsitems/qdeclarativeflipable.cpp +++ b/src/declarative/graphicsitems/qdeclarativeflipable.cpp @@ -86,13 +86,13 @@ public: The following example shows a Flipable item that flips whenever it is clicked, rotating about the y-axis. - This flipable item has a \c flipped boolean property that is toggled - whenever the MouseArea within the flipable is clicked. When - \c flipped is true, the item changes to the "back" state; in this + This flipable item has a \c flipped boolean property that is toggled + whenever the MouseArea within the flipable is clicked. When + \c flipped is true, the item changes to the "back" state; in this state, the \c angle of the \l Rotation item is changed to 180 degrees to produce the flipping effect. When \c flipped is false, the - item reverts to the default state, in which the \c angle value is 0. - + item reverts to the default state, in which the \c angle value is 0. + \snippet doc/src/snippets/declarative/flipable/flipable.qml 0 \image flipable.gif @@ -103,8 +103,8 @@ public: its old and new values. See \l {QML States} for details on state changes and the default - state, and \l {QML Animation} for more information on how animations - work within transitions. + state, and \l {QML Animation and Transitions} for more information on how + animations work within transitions. \sa {declarative/ui-components/flipable}{Flipable example} */ diff --git a/src/declarative/graphicsitems/qdeclarativegridview.cpp b/src/declarative/graphicsitems/qdeclarativegridview.cpp index 0cbe1ac..ce47d88 100644 --- a/src/declarative/graphicsitems/qdeclarativegridview.cpp +++ b/src/declarative/graphicsitems/qdeclarativegridview.cpp @@ -197,6 +197,7 @@ public: if (q->isComponentComplete()) { clear(); updateGrid(); + setPosition(0); q->refill(); updateCurrent(currentIndex); } @@ -689,7 +690,6 @@ void QDeclarativeGridViewPrivate::updateGrid() q->setContentHeight(endPosition() - startPosition()); else q->setContentWidth(lastPosition() - originPosition()); - setPosition(0); } } @@ -1246,7 +1246,7 @@ void QDeclarativeGridViewPrivate::flick(AxisData &data, qreal minExtent, qreal m \snippet doc/src/snippets/declarative/gridview/ContactModel.qml 0 - \div {float-right} + \div {class="float-right"} \inlineimage gridview-simple.png \enddiv @@ -1262,7 +1262,7 @@ void QDeclarativeGridViewPrivate::flick(AxisData &data, qreal minExtent, qreal m \codeline \snippet doc/src/snippets/declarative/gridview/gridview.qml classdocs simple - \div {float-right} + \div {class="float-right"} \inlineimage gridview-highlight.png \enddiv diff --git a/src/declarative/graphicsitems/qdeclarativeitem.cpp b/src/declarative/graphicsitems/qdeclarativeitem.cpp index 4af91ce..6602dda 100644 --- a/src/declarative/graphicsitems/qdeclarativeitem.cpp +++ b/src/declarative/graphicsitems/qdeclarativeitem.cpp @@ -2747,7 +2747,7 @@ QDeclarativeListProperty<QDeclarativeState> QDeclarativeItemPrivate::states() } \endqml - \sa {qdeclarativeanimation.html#transitions}{QML Transitions} + \sa {QML Animation and Transitions}{Transitions} */ @@ -3455,7 +3455,7 @@ qreal QDeclarativeItem::implicitHeight() const Setting the implicit size is useful for defining components that have a preferred size based on their content, for example: - \code + \qml // Label.qml import QtQuick 1.1 @@ -3472,7 +3472,7 @@ qreal QDeclarativeItem::implicitHeight() const anchors.verticalCenter: parent.verticalCenter } } - \endcode + \endqml \bold Note: using implicitWidth of Text or TextEdit and setting the width explicitly incurs a performance penalty as the text must be laid out twice. diff --git a/src/declarative/graphicsitems/qdeclarativemousearea.cpp b/src/declarative/graphicsitems/qdeclarativemousearea.cpp index da11b00..f5145d0 100644 --- a/src/declarative/graphicsitems/qdeclarativemousearea.cpp +++ b/src/declarative/graphicsitems/qdeclarativemousearea.cpp @@ -216,7 +216,7 @@ QDeclarativeMouseAreaPrivate::~QDeclarativeMouseAreaPrivate() \section1 Example Usage - \div {float-right} + \div {class="float-right"} \inlineimage qml-mousearea-snippet.png \enddiv @@ -315,7 +315,7 @@ QDeclarativeMouseAreaPrivate::~QDeclarativeMouseAreaPrivate() The \e accepted property of the MouseEvent parameter is ignored in this handler. - \sa onCanceled() + \sa onCanceled */ /*! diff --git a/src/declarative/graphicsitems/qdeclarativerectangle.cpp b/src/declarative/graphicsitems/qdeclarativerectangle.cpp index 8f59073..b3235ef 100644 --- a/src/declarative/graphicsitems/qdeclarativerectangle.cpp +++ b/src/declarative/graphicsitems/qdeclarativerectangle.cpp @@ -134,7 +134,7 @@ void QDeclarativeGradientStop::updateGradient() \section1 Example Usage - \div {float-right} + \div {class="float-right"} \inlineimage qml-gradient.png \enddiv @@ -220,7 +220,7 @@ void QDeclarativeGradient::doUpdate() \section1 Example Usage - \div {float-right} + \div {class="float-right"} \inlineimage declarative-rect.png \enddiv @@ -272,7 +272,7 @@ void QDeclarativeRectangle::doUpdate() rectangle (as documented for QRect rendering). This can cause unintended effects if \c border.width is 1 and the rectangle is \l{Item::clip}{clipped} by a parent item: - \div {float-right} + \div {class="float-right"} \inlineimage rect-border-width.png \enddiv @@ -296,7 +296,7 @@ QDeclarativePen *QDeclarativeRectangle::border() This property allows for the construction of simple vertical gradients. Other gradients may by formed by adding rotation to the rectangle. - \div {float-left} + \div {class="float-left"} \inlineimage declarative-rect_gradient.png \enddiv @@ -364,7 +364,7 @@ void QDeclarativeRectangle::setRadius(qreal radius) The default color is white. - \div {float-right} + \div {class="float-right"} \inlineimage rect-color.png \enddiv diff --git a/src/declarative/graphicsitems/qdeclarativevisualitemmodel.cpp b/src/declarative/graphicsitems/qdeclarativevisualitemmodel.cpp index a8082f8..97ce059 100644 --- a/src/declarative/graphicsitems/qdeclarativevisualitemmodel.cpp +++ b/src/declarative/graphicsitems/qdeclarativevisualitemmodel.cpp @@ -839,7 +839,8 @@ void QDeclarativeVisualDataModel::setDelegate(QDeclarativeComponent *delegate) QML only operates on list data. \c rootIndex allows the children of any node in a QAbstractItemModel to be provided by this model. - This property only affects models of type QAbstractItemModel. + This property only affects models of type QAbstractItemModel that + are hierarchical (e.g, a tree model). For example, here is a simple interactive file system browser. When a directory name is clicked, the view's \c rootIndex is set to the diff --git a/src/declarative/qml/qdeclarativecomponent.cpp b/src/declarative/qml/qdeclarativecomponent.cpp index fc393d1..c284307 100644 --- a/src/declarative/qml/qdeclarativecomponent.cpp +++ b/src/declarative/qml/qdeclarativecomponent.cpp @@ -137,7 +137,7 @@ class QByteArray; } \endcode - \sa {Using QML in C++ Applications}, {Integrating QML with existing Qt UI code} + \sa {Using QML Bindings in C++ Applications}, {Integrating QML Code with Existing Qt UI Code} */ /*! diff --git a/src/declarative/qml/qdeclarativecontext.cpp b/src/declarative/qml/qdeclarativecontext.cpp index dc6b085..7637b72 100644 --- a/src/declarative/qml/qdeclarativecontext.cpp +++ b/src/declarative/qml/qdeclarativecontext.cpp @@ -72,10 +72,10 @@ QDeclarativeContextPrivate::QDeclarativeContextPrivate() Contexts allow data to be exposed to the QML components instantiated by the QML engine. - Each QDeclarativeContext contains a set of properties, distinct from its QObject - properties, that allow data to be explicitly bound to a context by name. The - context properties are defined and updated by calling - QDeclarativeContext::setContextProperty(). The following example shows a Qt model + Each QDeclarativeContext contains a set of properties, distinct from its QObject + properties, that allow data to be explicitly bound to a context by name. The + context properties are defined and updated by calling + QDeclarativeContext::setContextProperty(). The following example shows a Qt model being bound to a context and then accessed from a QML file. \code @@ -97,8 +97,8 @@ QDeclarativeContextPrivate::QDeclarativeContextPrivate() To simplify binding and maintaining larger data sets, a context object can be set on a QDeclarativeContext. All the properties of the context object are available by name in the context, as though they were all individually added through calls - to QDeclarativeContext::setContextProperty(). Changes to the property's values are - detected through the property's notify signal. Setting a context object is both + to QDeclarativeContext::setContextProperty(). Changes to the property's values are + detected through the property's notify signal. Setting a context object is both faster and easier than manually adding and maintaing context property values. The following example has the same effect as the previous one, but it uses a context @@ -121,7 +121,7 @@ QDeclarativeContextPrivate::QDeclarativeContextPrivate() component.create(context); \endcode - All properties added explicitly by QDeclarativeContext::setContextProperty() take + All properties added explicitly by QDeclarativeContext::setContextProperty() take precedence over the context object's properties. \section2 The Context Hierarchy @@ -147,8 +147,8 @@ QDeclarativeContextPrivate::QDeclarativeContextPrivate() context2->setContextProperty("b", 15); \endcode - While QML objects instantiated in a context are not strictly owned by that - context, their bindings are. If a context is destroyed, the property bindings of + While QML objects instantiated in a context are not strictly owned by that + context, their bindings are. If a context is destroyed, the property bindings of outstanding QML objects will stop evaluating. \warning Setting the context object or adding new context properties after an object @@ -156,7 +156,7 @@ QDeclarativeContextPrivate::QDeclarativeContextPrivate() to reevaluate). Thus whenever possible you should complete "setup" of the context before using it to create any objects. - \sa {Using QML in C++ Applications} + \sa {Using QML Bindings in C++ Applications} */ /*! \internal */ @@ -223,7 +223,7 @@ QDeclarativeContext::~QDeclarativeContext() /*! Returns whether the context is valid. - To be valid, a context must have a engine, and it's contextObject(), if any, + To be valid, a context must have a engine, and it's contextObject(), if any, must not have been deleted. */ bool QDeclarativeContext::isValid() const @@ -384,7 +384,7 @@ QVariant QDeclarativeContext::contextProperty(const QString &name) const if (data->contextObject) { QObject *obj = data->contextObject; QDeclarativePropertyCache::Data local; - QDeclarativePropertyCache::Data *property = + QDeclarativePropertyCache::Data *property = QDeclarativePropertyCache::property(data->engine, obj, name, local); if (property) value = obj->metaObject()->property(property->coreIndex).read(obj); @@ -461,7 +461,7 @@ QUrl QDeclarativeContext::baseUrl() const { Q_D(const QDeclarativeContext); const QDeclarativeContextData* data = d->data; - while (data && data->url.isEmpty()) + while (data && data->url.isEmpty()) data = data->parent; if (data) @@ -515,7 +515,7 @@ QDeclarativeContextData::QDeclarativeContextData(QDeclarativeContext *ctxt) void QDeclarativeContextData::invalidate() { - while (childContexts) + while (childContexts) childContexts->invalidate(); while (componentAttached) { @@ -570,7 +570,7 @@ void QDeclarativeContextData::clearContext() void QDeclarativeContextData::destroy() { - if (linkedContext) + if (linkedContext) linkedContext->destroy(); if (engine) invalidate(); @@ -626,9 +626,9 @@ void QDeclarativeContextData::setParent(QDeclarativeContextData *p) } } -/* -Refreshes all expressions that could possibly depend on this context. Refreshing flushes all -context-tree dependent caches in the expressions, and should occur every time the context tree +/* +Refreshes all expressions that could possibly depend on this context. Refreshing flushes all +context-tree dependent caches in the expressions, and should occur every time the context tree *structure* (not values) changes. */ void QDeclarativeContextData::refreshExpressions() @@ -656,7 +656,7 @@ void QDeclarativeContextData::addObject(QObject *o) data->outerContext = this; data->nextContextObject = contextObjects; - if (data->nextContextObject) + if (data->nextContextObject) data->nextContextObject->prevContextObject = &data->nextContextObject; data->prevContextObject = &contextObjects; contextObjects = data; @@ -664,7 +664,7 @@ void QDeclarativeContextData::addObject(QObject *o) void QDeclarativeContextData::addImportedScript(const QDeclarativeParser::Object::ScriptBlock &script) { - if (!engine) + if (!engine) return; QDeclarativeEnginePrivate *enginePriv = QDeclarativeEnginePrivate::get(engine); @@ -684,7 +684,7 @@ void QDeclarativeContextData::addImportedScript(const QDeclarativeParser::Object scriptContext->pushScope(enginePriv->contextClass->newUrlContext(url)); scriptContext->pushScope(enginePriv->globalClass->staticGlobalObject()); - + QScriptValue scope = QScriptDeclarativeClass::newStaticScopeObject(scriptEngine); scriptContext->pushScope(scope); @@ -752,7 +752,7 @@ QString QDeclarativeContextData::findObjectId(const QObject *obj) const for (int i=0; i<idValueCount; i++) { if (idValues[i] == obj) return propertyNames->findId(i); - } + } if (linkedContext) return linkedContext->findObjectId(obj); @@ -761,7 +761,7 @@ QString QDeclarativeContextData::findObjectId(const QObject *obj) const QDeclarativeContext *QDeclarativeContextData::asQDeclarativeContext() { - if (!publicContext) + if (!publicContext) publicContext = new QDeclarativeContext(this); return publicContext; } diff --git a/src/declarative/qml/qdeclarativeengine.cpp b/src/declarative/qml/qdeclarativeengine.cpp index b7a02f1..9fde18c 100644 --- a/src/declarative/qml/qdeclarativeengine.cpp +++ b/src/declarative/qml/qdeclarativeengine.cpp @@ -2117,7 +2117,7 @@ QVariant QDeclarativeEnginePrivate::scriptValueToVariant(const QScriptValue &val The newly added \a path will be first in the importPathList(). - \sa setImportPathList(), \l {QML Modules} + \sa setImportPathList(), {QML Modules} */ void QDeclarativeEngine::addImportPath(const QString& path) { diff --git a/src/declarative/qml/qdeclarativetypeloader.cpp b/src/declarative/qml/qdeclarativetypeloader.cpp index 36cdde9..26f3996 100644 --- a/src/declarative/qml/qdeclarativetypeloader.cpp +++ b/src/declarative/qml/qdeclarativetypeloader.cpp @@ -629,7 +629,18 @@ QDeclarativeTypeLoader::~QDeclarativeTypeLoader() } /*! -Return a QDeclarativeTypeData for \a url. The QDeclarativeTypeData may be cached. +\enum QDeclarativeTypeLoader::Option + +This enum defines the options that control the way type data is handled. + +\value None The default value, indicating that no other options + are enabled. +\value PreserveParser The parser used to handle the type data is preserved + after the data has been parsed. +*/ + +/*! +Returns a QDeclarativeTypeData for the specified \a url. The QDeclarativeTypeData may be cached. */ QDeclarativeTypeData *QDeclarativeTypeLoader::get(const QUrl &url) { @@ -650,8 +661,10 @@ QDeclarativeTypeData *QDeclarativeTypeLoader::get(const QUrl &url) } /*! -Return a QDeclarativeTypeData for \a data with the provided base \a url. The +Returns a QDeclarativeTypeData for the given \a data with the provided base \a url. The QDeclarativeTypeData will not be cached. + +The specified \a options control how the loader handles type data. */ QDeclarativeTypeData *QDeclarativeTypeLoader::get(const QByteArray &data, const QUrl &url, Options options) { diff --git a/src/declarative/util/qdeclarativeanimation.cpp b/src/declarative/util/qdeclarativeanimation.cpp index dc6d524..b3bf84b 100644 --- a/src/declarative/util/qdeclarativeanimation.cpp +++ b/src/declarative/util/qdeclarativeanimation.cpp @@ -74,7 +74,7 @@ QT_BEGIN_NAMESPACE /*! \qmlclass Animation QDeclarativeAbstractAnimation - \ingroup qml-animation-transition + \ingroup qml-animation-transition \since 4.7 \brief The Animation element is the base of all QML animations. @@ -554,7 +554,7 @@ void QDeclarativeAbstractAnimation::timelineComplete() /*! \qmlclass PauseAnimation QDeclarativePauseAnimation - \ingroup qml-animation-transition + \ingroup qml-animation-transition \since 4.7 \inherits Animation \brief The PauseAnimation element provides a pause for an animation. @@ -571,7 +571,7 @@ void QDeclarativeAbstractAnimation::timelineComplete() } \endcode - \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} + \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} */ QDeclarativePauseAnimation::QDeclarativePauseAnimation(QObject *parent) : QDeclarativeAbstractAnimation(*(new QDeclarativePauseAnimationPrivate), parent) @@ -630,27 +630,27 @@ QAbstractAnimation *QDeclarativePauseAnimation::qtAnimation() \inherits PropertyAnimation \brief The ColorAnimation element animates changes in color values. - ColorAnimation is a specialized PropertyAnimation that defines an + ColorAnimation is a specialized PropertyAnimation that defines an animation to be applied when a color value changes. - Here is a ColorAnimation applied to the \c color property of a \l Rectangle - as a property value source. It animates the \c color property's value from + Here is a ColorAnimation applied to the \c color property of a \l Rectangle + as a property value source. It animates the \c color property's value from its current value to a value of "red", over 1000 milliseconds: \snippet doc/src/snippets/declarative/coloranimation.qml 0 Like any other animation element, a ColorAnimation can be applied in a - number of ways, including transitions, behaviors and property value - sources. The \l {QML Animation} documentation shows a variety of methods - for creating animations. - - For convenience, when a ColorAnimation is used in a \l Transition, it will - animate any \c color properties that have been modified during the state - change. If a \l{PropertyAnimation::}{property} or - \l{PropertyAnimation::}{properties} are explicitly set for the animation, + number of ways, including transitions, behaviors and property value + sources. The \l {QML Animation and Transitions} documentation shows a + variety of methods for creating animations. + + For convenience, when a ColorAnimation is used in a \l Transition, it will + animate any \c color properties that have been modified during the state + change. If a \l{PropertyAnimation::}{property} or + \l{PropertyAnimation::}{properties} are explicitly set for the animation, then those are used instead. - \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} + \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} */ QDeclarativeColorAnimation::QDeclarativeColorAnimation(QObject *parent) : QDeclarativePropertyAnimation(parent) @@ -686,10 +686,10 @@ QDeclarativeColorAnimation::~QDeclarativeColorAnimation() If the ColorAnimation is defined within a \l Transition or \l Behavior, this value defaults to the value defined in the starting state of the - \l Transition, or the current value of the property at the moment the + \l Transition, or the current value of the property at the moment the \l Behavior is triggered. - \sa {QML Animation} + \sa {QML Animation and Transitions} */ QColor QDeclarativeColorAnimation::from() const { @@ -712,7 +712,7 @@ void QDeclarativeColorAnimation::setFrom(const QColor &f) \l Transition, or the value of the property change that triggered the \l Behavior. - \sa {QML Animation} + \sa {QML Animation and Transitions} */ QColor QDeclarativeColorAnimation::to() const { @@ -868,7 +868,7 @@ QAbstractAnimation *QDeclarativeScriptAction::qtAnimation() \inherits Animation \brief The PropertyAction element allows immediate property changes during animation. - PropertyAction is used to specify an immediate property change during an + PropertyAction is used to specify an immediate property change during an animation. The property change is not animated. It is useful for setting non-animated property values during an animation. @@ -879,9 +879,9 @@ QAbstractAnimation *QDeclarativeScriptAction::qtAnimation() \snippet doc/src/snippets/declarative/propertyaction.qml standalone - PropertyAction is also useful for setting the exact point at which a property - change should occur during a \l Transition. For example, if PropertyChanges - was used in a \l State to rotate an item around a particular + PropertyAction is also useful for setting the exact point at which a property + change should occur during a \l Transition. For example, if PropertyChanges + was used in a \l State to rotate an item around a particular \l {Item::}{transformOrigin}, it might be implemented like this: \snippet doc/src/snippets/declarative/propertyaction.qml transition @@ -893,13 +893,13 @@ QAbstractAnimation *QDeclarativeScriptAction::qtAnimation() before the RotationAnimation begins: \snippet doc/src/snippets/declarative/propertyaction-sequential.qml sequential - + This immediately sets the \c transformOrigin property to the value defined - in the end state of the \l Transition (i.e. the value defined in the + in the end state of the \l Transition (i.e. the value defined in the PropertyAction object) so that the rotation animation begins with the correct transform origin. - \sa {QML Animation}, QtDeclarative + \sa {QML Animation and Transitions}, QtDeclarative */ QDeclarativePropertyAction::QDeclarativePropertyAction(QObject *parent) : QDeclarativeAbstractAnimation(*(new QDeclarativePropertyActionPrivate), parent) @@ -1129,25 +1129,25 @@ void QDeclarativePropertyAction::transition(QDeclarativeStateActions &actions, \inherits PropertyAnimation \brief The NumberAnimation element animates changes in qreal-type values. - NumberAnimation is a specialized PropertyAnimation that defines an + NumberAnimation is a specialized PropertyAnimation that defines an animation to be applied when a numerical value changes. - Here is a NumberAnimation applied to the \c x property of a \l Rectangle - as a property value source. It animates the \c x value from its current + Here is a NumberAnimation applied to the \c x property of a \l Rectangle + as a property value source. It animates the \c x value from its current value to a value of 50, over 1000 milliseconds: \snippet doc/src/snippets/declarative/numberanimation.qml 0 Like any other animation element, a NumberAnimation can be applied in a - number of ways, including transitions, behaviors and property value - sources. The \l {QML Animation} documentation shows a variety of methods - for creating animations. + number of ways, including transitions, behaviors and property value + sources. The \l {QML Animation and Transitions} documentation shows a + variety of methods for creating animations. Note that NumberAnimation may not animate smoothly if there are irregular changes in the number value that it is tracking. If this is the case, use SmoothedAnimation instead. - \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} + \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} */ QDeclarativeNumberAnimation::QDeclarativeNumberAnimation(QObject *parent) : QDeclarativePropertyAnimation(parent) @@ -1193,10 +1193,10 @@ void QDeclarativeNumberAnimation::init() If the NumberAnimation is defined within a \l Transition or \l Behavior, this value defaults to the value defined in the starting state of the - \l Transition, or the current value of the property at the moment the + \l Transition, or the current value of the property at the moment the \l Behavior is triggered. - \sa {QML Animation} + \sa {QML Animation and Transitions} */ qreal QDeclarativeNumberAnimation::from() const @@ -1219,7 +1219,7 @@ void QDeclarativeNumberAnimation::setFrom(qreal f) \l Transition, or the value of the property change that triggered the \l Behavior. - \sa {QML Animation} + \sa {QML Animation and Transitions} */ qreal QDeclarativeNumberAnimation::to() const { @@ -1241,15 +1241,15 @@ void QDeclarativeNumberAnimation::setTo(qreal t) \inherits PropertyAnimation \brief The Vector3dAnimation element animates changes in QVector3d values. - Vector3dAnimation is a specialized PropertyAnimation that defines an + Vector3dAnimation is a specialized PropertyAnimation that defines an animation to be applied when a Vector3d value changes. Like any other animation element, a Vector3dAnimation can be applied in a - number of ways, including transitions, behaviors and property value - sources. The \l {QML Animation} documentation shows a variety of methods - for creating animations. + number of ways, including transitions, behaviors and property value + sources. The \l {QML Animation and Transitions} documentation shows a + variety of methods for creating animations. - \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} + \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} */ QDeclarativeVector3dAnimation::QDeclarativeVector3dAnimation(QObject *parent) : QDeclarativePropertyAnimation(parent) @@ -1270,10 +1270,10 @@ QDeclarativeVector3dAnimation::~QDeclarativeVector3dAnimation() If the Vector3dAnimation is defined within a \l Transition or \l Behavior, this value defaults to the value defined in the starting state of the - \l Transition, or the current value of the property at the moment the + \l Transition, or the current value of the property at the moment the \l Behavior is triggered. - \sa {QML Animation} + \sa {QML Animation and Transitions} */ QVector3D QDeclarativeVector3dAnimation::from() const { @@ -1295,7 +1295,7 @@ void QDeclarativeVector3dAnimation::setFrom(QVector3D f) \l Transition, or the value of the property change that triggered the \l Behavior. - \sa {QML Animation} + \sa {QML Animation and Transitions} */ QVector3D QDeclarativeVector3dAnimation::to() const { @@ -1318,7 +1318,7 @@ void QDeclarativeVector3dAnimation::setTo(QVector3D t) \brief The RotationAnimation element animates changes in rotation values. RotationAnimation is a specialized PropertyAnimation that gives control - over the direction of rotation during an animation. + over the direction of rotation during an animation. By default, it rotates in the direction of the numerical change; a rotation from 0 to 240 will rotate 240 degrees @@ -1334,7 +1334,7 @@ void QDeclarativeVector3dAnimation::setTo(QVector3D t) Notice the RotationAnimation did not need to set a \l target value. As a convenience, when used in a transition, RotationAnimation will rotate all properties named "rotation" or "angle". You can override this by providing - your own properties via \l {PropertyAnimation::properties}{properties} or + your own properties via \l {PropertyAnimation::properties}{properties} or \l {PropertyAnimation::property}{property}. Also, note the \l Rectangle will be rotated around its default @@ -1344,11 +1344,11 @@ void QDeclarativeVector3dAnimation::setTo(QVector3D t) PropertyAction documentation for more details. Like any other animation element, a RotationAnimation can be applied in a - number of ways, including transitions, behaviors and property value - sources. The \l {QML Animation} documentation shows a variety of methods - for creating animations. + number of ways, including transitions, behaviors and property value + sources. The \l {QML Animation and Transitions} documentation shows a + variety of methods for creating animations. - \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} + \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} */ QVariant _q_interpolateShortestRotation(qreal &f, qreal &t, qreal progress) { @@ -1421,10 +1421,10 @@ QDeclarativeRotationAnimation::~QDeclarativeRotationAnimation() If the RotationAnimation is defined within a \l Transition or \l Behavior, this value defaults to the value defined in the starting state of the - \l Transition, or the current value of the property at the moment the + \l Transition, or the current value of the property at the moment the \l Behavior is triggered. - \sa {QML Animation} + \sa {QML Animation and Transitions} */ qreal QDeclarativeRotationAnimation::from() const { @@ -1446,7 +1446,7 @@ void QDeclarativeRotationAnimation::setFrom(qreal f) \l Transition, or the value of the property change that triggered the \l Behavior. - \sa {QML Animation} + \sa {QML Animation and Transitions} */ qreal QDeclarativeRotationAnimation::to() const { @@ -1572,15 +1572,15 @@ QDeclarativeListProperty<QDeclarativeAbstractAnimation> QDeclarativeAnimationGro if this is the preferred behavior. Like any other animation element, a SequentialAnimation can be applied in a - number of ways, including transitions, behaviors and property value - sources. The \l {QML Animation} documentation shows a variety of methods - for creating animations. + number of ways, including transitions, behaviors and property value + sources. The \l {QML Animation and Transitions} documentation shows a + variety of methods for creating animations. - \note Once an animation has been grouped into a SequentialAnimation or + \note Once an animation has been grouped into a SequentialAnimation or ParallelAnimation, it cannot be individually started and stopped; the SequentialAnimation or ParallelAnimation must be started and stopped as a group. - - \sa ParallelAnimation, {QML Animation}, {declarative/animation/basics}{Animation basics example} + + \sa ParallelAnimation, {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} */ QDeclarativeSequentialAnimation::QDeclarativeSequentialAnimation(QObject *parent) : @@ -1642,15 +1642,15 @@ void QDeclarativeSequentialAnimation::transition(QDeclarativeStateActions &actio \snippet doc/src/snippets/declarative/parallelanimation.qml 0 Like any other animation element, a ParallelAnimation can be applied in a - number of ways, including transitions, behaviors and property value - sources. The \l {QML Animation} documentation shows a variety of methods - for creating animations. + number of ways, including transitions, behaviors and property value + sources. The \l {QML Animation and Transitions} documentation shows a + variety of methods for creating animations. - \note Once an animation has been grouped into a SequentialAnimation or + \note Once an animation has been grouped into a SequentialAnimation or ParallelAnimation, it cannot be individually started and stopped; the SequentialAnimation or ParallelAnimation must be started and stopped as a group. - \sa SequentialAnimation, {QML Animation}, {declarative/animation/basics}{Animation basics example} + \sa SequentialAnimation, {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} */ QDeclarativeParallelAnimation::QDeclarativeParallelAnimation(QObject *parent) : QDeclarativeAnimationGroup(parent) @@ -1745,14 +1745,14 @@ void QDeclarativePropertyAnimationPrivate::convertVariant(QVariant &variant, int \inherits Animation \brief The PropertyAnimation element animates changes in property values. - PropertyAnimation provides a way to animate changes to a property's value. + PropertyAnimation provides a way to animate changes to a property's value. It can be used to define animations in a number of ways: - + \list \o In a \l Transition - For example, to animate any objects that have changed their \c x or \c y properties + For example, to animate any objects that have changed their \c x or \c y properties as a result of a state change, using an \c InOutQuad easing curve: \snippet doc/src/snippets/declarative/propertyanimation.qml transition @@ -1792,12 +1792,12 @@ void QDeclarativePropertyAnimationPrivate::convertVariant(QVariant &variant, int Depending on how the animation is used, the set of properties normally used will be different. For more information see the individual property documentation, as well - as the \l{QML Animation} introduction. + as the \l{QML Animation and Transitions} introduction. Note that PropertyAnimation inherits the abstract \l Animation element. This includes additional properties and methods for controlling the animation. - \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} + \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} */ QDeclarativePropertyAnimation::QDeclarativePropertyAnimation(QObject *parent) @@ -1857,10 +1857,10 @@ void QDeclarativePropertyAnimation::setDuration(int duration) If the PropertyAnimation is defined within a \l Transition or \l Behavior, this value defaults to the value defined in the starting state of the - \l Transition, or the current value of the property at the moment the + \l Transition, or the current value of the property at the moment the \l Behavior is triggered. - \sa {QML Animation} + \sa {QML Animation and Transitions} */ QVariant QDeclarativePropertyAnimation::from() const { @@ -1887,7 +1887,7 @@ void QDeclarativePropertyAnimation::setFrom(const QVariant &f) \l Transition, or the value of the property change that triggered the \l Behavior. - \sa {QML Animation} + \sa {QML Animation and Transitions} */ QVariant QDeclarativePropertyAnimation::to() const { @@ -2254,7 +2254,7 @@ void QDeclarativePropertyAnimation::setProperties(const QString &prop) As seen in the above example, properties is specified as a comma-separated string of property names to animate. - \sa exclude, {QML Animation} + \sa exclude, {QML Animation and Transitions} */ QDeclarativeListProperty<QObject> QDeclarativePropertyAnimation::targets() { @@ -2437,7 +2437,7 @@ void QDeclarativePropertyAnimation::transition(QDeclarativeStateActions &actions ParentAnimation is used to animate a parent change for an \l Item. For example, the following ParentChange changes \c blueRect to become - a child of \c redRect when it is clicked. The inclusion of the + a child of \c redRect when it is clicked. The inclusion of the ParentAnimation, which defines a NumberAnimation to be applied during the transition, ensures the item animates smoothly as it moves to its new parent: @@ -2452,17 +2452,17 @@ void QDeclarativePropertyAnimation::transition(QDeclarativeStateActions &actions to animate the parent change via another item that does not have clipping enabled. Such an item can be set using the \l via property. - For convenience, when a ParentAnimation is used in a \l Transition, it will - animate any ParentChange that has occurred during the state change. + For convenience, when a ParentAnimation is used in a \l Transition, it will + animate any ParentChange that has occurred during the state change. This can be overridden by setting a specific target item using the \l target property. Like any other animation element, a ParentAnimation can be applied in a - number of ways, including transitions, behaviors and property value - sources. The \l {QML Animation} documentation shows a variety of methods - for creating animations. + number of ways, including transitions, behaviors and property value + sources. The \l {QML Animation and Transitions} documentation shows a + variety of methods for creating animations. - \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} + \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} */ QDeclarativeParentAnimation::QDeclarativeParentAnimation(QObject *parent) : QDeclarativeAnimationGroup(*(new QDeclarativeParentAnimationPrivate), parent) @@ -2765,6 +2765,8 @@ void QDeclarativeParentAnimation::transition(QDeclarativeStateActions &actions, d->endAction->setAnimAction(d->via ? viaData : data, QActionAnimation::DeleteWhenStopped); d->startAction->setAnimAction(d->via ? data : 0, QActionAnimation::DeleteWhenStopped); } + if (!d->via) + delete viaData; } else { delete data; delete viaData; @@ -2793,23 +2795,23 @@ QAbstractAnimation *QDeclarativeParentAnimation::qtAnimation() \inherits Animation \brief The AnchorAnimation element animates changes in anchor values. - AnchorAnimation is used to animate an anchor change. + AnchorAnimation is used to animate an anchor change. In the following snippet we animate the addition of a right anchor to a \l Rectangle: \snippet doc/src/snippets/declarative/anchoranimation.qml 0 - For convenience, when an AnchorAnimation is used in a \l Transition, it will - animate any AnchorChanges that have occurred during the state change. + For convenience, when an AnchorAnimation is used in a \l Transition, it will + animate any AnchorChanges that have occurred during the state change. This can be overridden by setting a specific target item using the \l target property. Like any other animation element, an AnchorAnimation can be applied in a - number of ways, including transitions, behaviors and property value - sources. The \l {QML Animation} documentation shows a variety of methods - for creating animations. + number of ways, including transitions, behaviors and property value + sources. The \l {QML Animation and Transitions} documentation shows a + variety of methods for creating animations. - \sa {QML Animation}, AnchorChanges + \sa {QML Animation and Transitions}, AnchorChanges */ QDeclarativeAnchorAnimation::QDeclarativeAnchorAnimation(QObject *parent) diff --git a/src/declarative/util/qdeclarativebehavior.cpp b/src/declarative/util/qdeclarativebehavior.cpp index e584476..41f8fe5 100644 --- a/src/declarative/util/qdeclarativebehavior.cpp +++ b/src/declarative/util/qdeclarativebehavior.cpp @@ -76,7 +76,7 @@ public: \since 4.7 \brief The Behavior element allows you to specify a default animation for a property change. - A Behavior defines the default animation to be applied whenever a + A Behavior defines the default animation to be applied whenever a particular property value changes. For example, the following Behavior defines a NumberAnimation to be run @@ -93,7 +93,7 @@ public: Behavior, the \l Transition animation overrides the Behavior for that state change. - \sa {QML Animation}, {declarative/animation/behaviors}{Behavior example}, QtDeclarative + \sa {QML Animation and Transitions}, {declarative/animation/behaviors}{Behavior example}, QtDeclarative */ @@ -205,7 +205,7 @@ void QDeclarativeBehavior::write(const QVariant &value) d->animation->qtAnimation()->start(); d->blockRunningChanged = false; if (!after.contains(d->property)) - QDeclarativePropertyPrivate::write(d->property, value, QDeclarativePropertyPrivate::BypassInterceptor | QDeclarativePropertyPrivate::DontRemoveBinding); + QDeclarativePropertyPrivate::write(d->property, value, QDeclarativePropertyPrivate::BypassInterceptor | QDeclarativePropertyPrivate::DontRemoveBinding); } void QDeclarativeBehavior::setTarget(const QDeclarativeProperty &property) diff --git a/src/declarative/util/qdeclarativeconnections.cpp b/src/declarative/util/qdeclarativeconnections.cpp index 5a66aab..83a7d83 100644 --- a/src/declarative/util/qdeclarativeconnections.cpp +++ b/src/declarative/util/qdeclarativeconnections.cpp @@ -117,6 +117,8 @@ public: id: area } // ... + \endqml + \qml Connections { target: area onClicked: foo(parameters) diff --git a/src/declarative/util/qdeclarativelistmodel.cpp b/src/declarative/util/qdeclarativelistmodel.cpp index 80b52fd..fb77ec3 100644 --- a/src/declarative/util/qdeclarativelistmodel.cpp +++ b/src/declarative/util/qdeclarativelistmodel.cpp @@ -108,7 +108,7 @@ QDeclarativeListModelParser::ListInstruction *QDeclarativeListModelParser::ListM The following example shows a ListModel containing three elements, with the roles "name" and "cost". - \div {float-right} + \div {class="float-right"} \inlineimage listmodel.png \enddiv @@ -133,7 +133,7 @@ QDeclarativeListModelParser::ListInstruction *QDeclarativeListModelParser::ListM The delegate displays all the fruit attributes: - \div {float-right} + \div {class="float-right"} \inlineimage listmodel-nested.png \enddiv @@ -143,7 +143,7 @@ QDeclarativeListModelParser::ListInstruction *QDeclarativeListModelParser::ListM \section1 Modifying List Models The content of a ListModel may be created and modified using the clear(), - append(), set() and setProperty() methods. For example: + append(), set(), insert() and setProperty() methods. For example: \snippet doc/src/snippets/declarative/listmodel-modify.qml delegate diff --git a/src/declarative/util/qdeclarativepropertychanges.cpp b/src/declarative/util/qdeclarativepropertychanges.cpp index 9bcb263..b03630d 100644 --- a/src/declarative/util/qdeclarativepropertychanges.cpp +++ b/src/declarative/util/qdeclarativepropertychanges.cpp @@ -118,12 +118,13 @@ QT_BEGIN_NAMESPACE \section2 Immediate property changes in transitions - When \l Transitions are used to animate state changes, they animate - properties from their values in the current state to those defined in the - new state (as defined by PropertyChanges objects). However, - it is sometimes desirable to set a property value \e immediately during a - \l Transition, without animation; in these cases, the PropertyAction - element can be used to force an immediate property change. + When \l{QML Animation and Transitions}{Transitions} are used to animate + state changes, they animate properties from their values in the current + state to those defined in the new state (as defined by PropertyChanges + objects). However, it is sometimes desirable to set a property value + \e immediately during a \l Transition, without animation; in these cases, + the PropertyAction element can be used to force an immediate property + change. See the PropertyAction documentation for more details. diff --git a/src/declarative/util/qdeclarativesmoothedanimation.cpp b/src/declarative/util/qdeclarativesmoothedanimation.cpp index e2f6e3c..9def5b4 100644 --- a/src/declarative/util/qdeclarativesmoothedanimation.cpp +++ b/src/declarative/util/qdeclarativesmoothedanimation.cpp @@ -257,8 +257,8 @@ void QSmoothedAnimation::init() A SmoothedAnimation animates a property's value to a set target value using an ease in/out quad easing curve. When the target value changes, - the easing curves used to animate between the old and new target values - are smoothly spliced together to create a smooth movement to the new + the easing curves used to animate between the old and new target values + are smoothly spliced together to create a smooth movement to the new target value that maintains the current velocity. The follow example shows one \l Rectangle tracking the position of another @@ -288,11 +288,11 @@ void QSmoothedAnimation::init() of 0.5 will take 2000 ms to complete. Like any other animation element, a SmoothedAnimation can be applied in a - number of ways, including transitions, behaviors and property value - sources. The \l {QML Animation} documentation shows a variety of methods - for creating animations. + number of ways, including transitions, behaviors and property value + sources. The \l {QML Animation and Transitions} documentation shows a + variety of methods for creating animations. - \sa SpringAnimation, NumberAnimation, {QML Animation}, {declarative/animation/basics}{Animation basics example} + \sa SpringAnimation, NumberAnimation, {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} */ QDeclarativeSmoothedAnimation::QDeclarativeSmoothedAnimation(QObject *parent) diff --git a/src/declarative/util/qdeclarativespringanimation.cpp b/src/declarative/util/qdeclarativespringanimation.cpp index 1212a1c..bb58b0a 100644 --- a/src/declarative/util/qdeclarativespringanimation.cpp +++ b/src/declarative/util/qdeclarativespringanimation.cpp @@ -246,19 +246,19 @@ void QDeclarativeSpringAnimationPrivate::updateMode() You can also limit the maximum \l velocity of the animation. - The following \l Rectangle moves to the position of the mouse using a + The following \l Rectangle moves to the position of the mouse using a SpringAnimation when the mouse is clicked. The use of the \l Behavior - on the \c x and \c y values indicates that whenever these values are + on the \c x and \c y values indicates that whenever these values are changed, a SpringAnimation should be applied. \snippet doc/src/snippets/declarative/springanimation.qml 0 Like any other animation element, a SpringAnimation can be applied in a - number of ways, including transitions, behaviors and property value - sources. The \l {QML Animation} documentation shows a variety of methods - for creating animations. + number of ways, including transitions, behaviors and property value + sources. The \l {QML Animation and Transitions} documentation shows a + variety of methods for creating animations. - \sa SmoothedAnimation, {QML Animation}, {declarative/animation/basics}{Animation basics example}, {declarative/toys/clocks}{Clocks example} + \sa SmoothedAnimation, {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example}, {declarative/toys/clocks}{Clocks example} */ QDeclarativeSpringAnimation::QDeclarativeSpringAnimation(QObject *parent) @@ -299,7 +299,7 @@ void QDeclarativeSpringAnimation::setVelocity(qreal velocity) This property describes how strongly the target is pulled towards the source. The default value is 0 (that is, the spring-like motion is disabled). - + The useful value range is 0 - 5.0. When this property is set and the \l velocity value is greater than 0, @@ -394,9 +394,9 @@ void QDeclarativeSpringAnimation::setModulus(qreal modulus) \qmlproperty real SpringAnimation::mass This property holds the "mass" of the property being moved. - The value is 1.0 by default. - - A greater mass causes slower movement and a greater spring-like + The value is 1.0 by default. + + A greater mass causes slower movement and a greater spring-like motion when an item comes to rest. */ qreal QDeclarativeSpringAnimation::mass() const diff --git a/src/declarative/util/qdeclarativestate.cpp b/src/declarative/util/qdeclarativestate.cpp index 5a4e2b1..5718e29 100644 --- a/src/declarative/util/qdeclarativestate.cpp +++ b/src/declarative/util/qdeclarativestate.cpp @@ -152,14 +152,14 @@ QDeclarativeStateOperation::QDeclarativeStateOperation(QObjectPrivate &dd, QObje Notice the default state is referred to using an empty string (""). - States are commonly used together with \l {Transitions} to provide + States are commonly used together with \l{QML Animation and Transitions}{Transitions} to provide animations when state changes occur. \note Setting the state of an object from within another state of the same object is not allowed. \sa {declarative/animation/states}{states example}, {qmlstates}{States}, - {qdeclarativeanimation.html#transitions}{QML Transitions}, QtDeclarative + {QML Animation and Transitions}{Transitions}, QtDeclarative */ QDeclarativeState::QDeclarativeState(QObject *parent) : QObject(*(new QDeclarativeStatePrivate), parent) diff --git a/src/declarative/util/qdeclarativestategroup.cpp b/src/declarative/util/qdeclarativestategroup.cpp index f1d0997..6459bf9 100644 --- a/src/declarative/util/qdeclarativestategroup.cpp +++ b/src/declarative/util/qdeclarativestategroup.cpp @@ -88,7 +88,7 @@ public: /*! \qmlclass StateGroup QDeclarativeStateGroup - \ingroup qml-state-elements + \ingroup qml-state-elements \since 4.7 \brief The StateGroup element provides state support for non-Item elements. @@ -113,7 +113,7 @@ public: } \endqml - \sa {qmlstate}{States} {Transitions}, {QtDeclarative} + \sa {qmlstate}{States} {QML Animation and Transitions}{Transitions}, {QtDeclarative} */ QDeclarativeStateGroup::QDeclarativeStateGroup(QObject *parent) @@ -213,7 +213,7 @@ void QDeclarativeStateGroupPrivate::clear_states(QDeclarativeListProperty<QDecla } \endqml - \sa {Transitions} + \sa {QML Animation and Transitions}{Transitions} */ QDeclarativeListProperty<QDeclarativeTransition> QDeclarativeStateGroup::transitionsProperty() { diff --git a/src/declarative/util/qdeclarativetransition.cpp b/src/declarative/util/qdeclarativetransition.cpp index 063ec3e..1a574b8 100644 --- a/src/declarative/util/qdeclarativetransition.cpp +++ b/src/declarative/util/qdeclarativetransition.cpp @@ -60,24 +60,24 @@ QT_BEGIN_NAMESPACE A Transition defines the animations to be applied when a \l State change occurs. For example, the following \l Rectangle has two states: the default state, and - an added "moved" state. In the "moved state, the rectangle's position changes + an added "moved" state. In the "moved state, the rectangle's position changes to (50, 50). The added Transition specifies that when the rectangle changes between the default and the "moved" state, any changes to the \c x and \c y properties should be animated, using an \c Easing.InOutQuad. \snippet doc/src/snippets/declarative/transition.qml 0 - Notice the example does not require \l{PropertyAnimation::}{to} and + Notice the example does not require \l{PropertyAnimation::}{to} and \l{PropertyAnimation::}{from} values for the NumberAnimation. As a convenience, these properties are automatically set to the values of \c x and \c y before and after the state change; the \c from values are provided by the current values of \c x and \c y, and the \c to values are provided by - the PropertyChanges object. If you wish, you can provide \l{PropertyAnimation::}{to} and + the PropertyChanges object. If you wish, you can provide \l{PropertyAnimation::}{to} and \l{PropertyAnimation::}{from} values anyway to override the default values. - By default, a Transition's animations are applied for any state change in the - parent item. The Transition \l {Transition::}{from} and \l {Transition::}{to} - values can be set to restrict the animations to only be applied when changing + By default, a Transition's animations are applied for any state change in the + parent item. The Transition \l {Transition::}{from} and \l {Transition::}{to} + values can be set to restrict the animations to only be applied when changing from one particular state to another. To define multiple transitions, specify \l Item::transitions as a list: @@ -92,7 +92,7 @@ QT_BEGIN_NAMESPACE \l Behavior, the Transition animation overrides the \l Behavior for that state change. - \sa {QML Animation}, {declarative/animation/states}{states example}, {qmlstates}{States}, {QtDeclarative} + \sa {QML Animation and Transitions}, {declarative/animation/states}{states example}, {qmlstates}{States}, {QtDeclarative} */ //ParallelAnimationWrapper allows us to do a "callback" when the animation finishes, rather than connecting @@ -111,8 +111,8 @@ class QDeclarativeTransitionPrivate : public QObjectPrivate { Q_DECLARE_PUBLIC(QDeclarativeTransition) public: - QDeclarativeTransitionPrivate() - : fromState(QLatin1String("*")), toState(QLatin1String("*")), + QDeclarativeTransitionPrivate() + : fromState(QLatin1String("*")), toState(QLatin1String("*")), reversed(false), reversible(false), endState(0) { group.trans = this; @@ -249,7 +249,7 @@ void QDeclarativeTransition::setFromState(const QString &f) is reversed, and it is not necessary to set this property to reverse the transition. - However, if a SequentialAnimation is used, or if the \l from or \l to + However, if a SequentialAnimation is used, or if the \l from or \l to properties have been set, this property will need to be set to reverse a transition when a state change is reverted. For example, the following transition applies a sequential animation when the mouse is pressed, @@ -257,7 +257,7 @@ void QDeclarativeTransition::setFromState(const QString &f) \snippet doc/src/snippets/declarative/transition-reversible.qml 0 - If the transition did not set the \c to and \c reversible values, then + If the transition did not set the \c to and \c reversible values, then on the mouse release, the transition would play the PropertyAnimation before the ColorAnimation instead of reversing the sequence. */ diff --git a/src/declarative/util/qdeclarativeview.cpp b/src/declarative/util/qdeclarativeview.cpp index 1b50a56..065b171 100644 --- a/src/declarative/util/qdeclarativeview.cpp +++ b/src/declarative/util/qdeclarativeview.cpp @@ -194,9 +194,9 @@ void QDeclarativeViewPrivate::itemGeometryChanged(QDeclarativeItem *resizeItem, \since 4.7 \brief The QDeclarativeView class provides a widget for displaying a Qt Declarative user interface. - QDeclarativeItem objects can be placed on a standard QGraphicsScene and - displayed with QGraphicsView. QDeclarativeView is a QGraphicsView subclass - provided as a convenience for displaying QML files, and connecting between + QDeclarativeItem objects can be placed on a standard QGraphicsScene and + displayed with QGraphicsView. QDeclarativeView is a QGraphicsView subclass + provided as a convenience for displaying QML files, and connecting between QML and C++ Qt objects. QDeclarativeView provides: @@ -236,7 +236,7 @@ void QDeclarativeViewPrivate::itemGeometryChanged(QDeclarativeItem *resizeItem, If you're using your own QGraphicsScene-based scene with QDeclarativeView, remember to enable scene's sticky focus mode and to set itemIndexMethod to QGraphicsScene::NoIndex. - \sa {Integrating QML with existing Qt UI code}, {Using QML in C++ Applications} + \sa {Integrating QML Code with Existing Qt UI Code}, {Using QML Bindings in C++ Applications} */ @@ -250,7 +250,7 @@ void QDeclarativeViewPrivate::itemGeometryChanged(QDeclarativeItem *resizeItem, /*! \fn QDeclarativeView::QDeclarativeView(QWidget *parent) - + Constructs a QDeclarativeView with the given \a parent. */ QDeclarativeView::QDeclarativeView(QWidget *parent) @@ -704,7 +704,7 @@ void QDeclarativeView::paintEvent(QPaintEvent *event) QDeclarativeDebugTrace::startRange(QDeclarativeDebugTrace::Painting); int time = 0; - if (frameRateDebug()) + if (frameRateDebug()) time = d->frameTimer.restart(); #ifdef Q_WS_MAC diff --git a/src/gui/dialogs/qabstractprintdialog.cpp b/src/gui/dialogs/qabstractprintdialog.cpp index 3317018..ef46697 100644 --- a/src/gui/dialogs/qabstractprintdialog.cpp +++ b/src/gui/dialogs/qabstractprintdialog.cpp @@ -381,19 +381,11 @@ void QAbstractPrintDialogPrivate::setPrinter(QPrinter *newPrinter) If the dialog is accepted by the user, the QPrinter object is correctly configured for printing. - \raw HTML - <table align="center"> - <tr><td> - \endraw - \inlineimage plastique-printdialog.png - \raw HTML - </td><td> - \endraw - \inlineimage plastique-printdialog-properties.png - \raw HTML - </td></tr> - </table> - \endraw + \table + \row + \o \inlineimage plastique-printdialog.png + \o \inlineimage plastique-printdialog-properties.png + \endtable The printer dialog (shown above in Plastique style) enables access to common printing properties. On X11 platforms that use the CUPS printing system, the diff --git a/src/gui/dialogs/qmessagebox.cpp b/src/gui/dialogs/qmessagebox.cpp index 09bb56c..d6dbcf6 100644 --- a/src/gui/dialogs/qmessagebox.cpp +++ b/src/gui/dialogs/qmessagebox.cpp @@ -1536,10 +1536,12 @@ static QMessageBox::StandardButton showNewMessageBox(QWidget *parent, /*! \since 4.2 - Opens an information message box with the specified \a title and - \a text. The standard \a buttons are added to the message box. \a - defaultButton specifies the button used when \key Enter is - pressed. \a defaultButton must refer to a button that was given in \a buttons. + Opens an information message box with the given \a title and + \a text in front of the specified \a parent widget. + + The standard \a buttons are added to the message box. + \a defaultButton specifies the button used when \key Enter is pressed. + \a defaultButton must refer to a button that was given in \a buttons. If \a defaultButton is QMessageBox::NoButton, QMessageBox chooses a suitable default automatically. @@ -1547,9 +1549,13 @@ static QMessageBox::StandardButton showNewMessageBox(QWidget *parent, \key Esc was pressed instead, the \l{Default and Escape Keys} {escape button} is returned. - The message box is an \l{Qt::ApplicationModal} {application modal} + The message box is an \l{Qt::ApplicationModal}{application modal} dialog box. + \warning Do not delete \a parent during the execution of the dialog. + If you want to do this, you should create the dialog + yourself using one of the QMessageBox constructors. + \sa question(), warning(), critical() */ QMessageBox::StandardButton QMessageBox::information(QWidget *parent, const QString &title, @@ -1564,8 +1570,10 @@ QMessageBox::StandardButton QMessageBox::information(QWidget *parent, const QStr /*! \since 4.2 - Opens a question message box with the specified \a title and \a - text. The standard \a buttons are added to the message box. \a + Opens a question message box with the given \a title and \a + text in front of the specified \a parent widget. + + The standard \a buttons are added to the message box. \a defaultButton specifies the button used when \key Enter is pressed. \a defaultButton must refer to a button that was given in \a buttons. If \a defaultButton is QMessageBox::NoButton, QMessageBox @@ -1578,6 +1586,10 @@ QMessageBox::StandardButton QMessageBox::information(QWidget *parent, const QStr The message box is an \l{Qt::ApplicationModal} {application modal} dialog box. + \warning Do not delete \a parent during the execution of the dialog. + If you want to do this, you should create the dialog + yourself using one of the QMessageBox constructors. + \sa information(), warning(), critical() */ QMessageBox::StandardButton QMessageBox::question(QWidget *parent, const QString &title, @@ -1590,8 +1602,10 @@ QMessageBox::StandardButton QMessageBox::question(QWidget *parent, const QString /*! \since 4.2 - Opens a warning message box with the specified \a title and \a - text. The standard \a buttons are added to the message box. \a + Opens a warning message box with the given \a title and \a + text in front of the specified \a parent widget. + + The standard \a buttons are added to the message box. \a defaultButton specifies the button used when \key Enter is pressed. \a defaultButton must refer to a button that was given in \a buttons. If \a defaultButton is QMessageBox::NoButton, QMessageBox @@ -1604,6 +1618,10 @@ QMessageBox::StandardButton QMessageBox::question(QWidget *parent, const QString The message box is an \l{Qt::ApplicationModal} {application modal} dialog box. + \warning Do not delete \a parent during the execution of the dialog. + If you want to do this, you should create the dialog + yourself using one of the QMessageBox constructors. + \sa question(), information(), critical() */ QMessageBox::StandardButton QMessageBox::warning(QWidget *parent, const QString &title, @@ -1616,8 +1634,10 @@ QMessageBox::StandardButton QMessageBox::warning(QWidget *parent, const QString /*! \since 4.2 - Opens a critical message box with the specified \a title and \a - text. The standard \a buttons are added to the message box. \a + Opens a critical message box with the given \a title and \a + text in front of the specified \a parent widget. + + The standard \a buttons are added to the message box. \a defaultButton specifies the button used when \key Enter is pressed. \a defaultButton must refer to a button that was given in \a buttons. If \a defaultButton is QMessageBox::NoButton, QMessageBox @@ -1630,9 +1650,9 @@ QMessageBox::StandardButton QMessageBox::warning(QWidget *parent, const QString The message box is an \l{Qt::ApplicationModal} {application modal} dialog box. - \warning Do not delete \a parent during the execution of the dialog. - If you want to do this, you should create the dialog - yourself using one of the QMessageBox constructors. + \warning Do not delete \a parent during the execution of the dialog. + If you want to do this, you should create the dialog + yourself using one of the QMessageBox constructors. \sa question(), warning(), information() */ diff --git a/src/gui/graphicsview/qgraphicsanchorlayout.cpp b/src/gui/graphicsview/qgraphicsanchorlayout.cpp index 014b61b..9bb5424 100644 --- a/src/gui/graphicsview/qgraphicsanchorlayout.cpp +++ b/src/gui/graphicsview/qgraphicsanchorlayout.cpp @@ -56,7 +56,7 @@ Items that are anchored are automatically added to the layout, and if items are removed, all their anchors will be automatically removed. - \div {float-left} + \div {class="float-left"} \inlineimage simpleanchorlayout-example.png Using an anchor layout to align simple colored widgets. \enddiv diff --git a/src/gui/graphicsview/qgraphicsitem.cpp b/src/gui/graphicsview/qgraphicsitem.cpp index 0af36ac..e342783 100644 --- a/src/gui/graphicsview/qgraphicsitem.cpp +++ b/src/gui/graphicsview/qgraphicsitem.cpp @@ -579,19 +579,21 @@ QGraphicsItem pointer). The return value is unused; you cannot adjust anything in this notification. - \value ItemSceneChange The item is moved to a new scene. This notification - is also sent when the item is added to its initial scene, and when it is - removed. The value argument is the new scene (i.e., a QGraphicsScene + \value ItemSceneChange The item is moved to a new scene. This notification is + also sent when the item is added to its initial scene, and when it is removed. + The item's scene() is the old scene (or 0 if the item has not been added to a + scene yet). The value argument is the new scene (i.e., a QGraphicsScene pointer), or a null pointer if the item is removed from a scene. Do not - override this change by passing this item to QGraphicsScene::addItem() as - this notification is delivered; instead, you can return the new scene from + override this change by passing this item to QGraphicsScene::addItem() as this + notification is delivered; instead, you can return the new scene from itemChange(). Use this feature with caution; objecting to a scene change can quickly lead to unwanted recursion. - \value ItemSceneHasChanged The item's scene has changed. The value - argument is the new scene (i.e., a pointer to a QGraphicsScene). Do not - call setScene() in itemChange() as this notification is delivered. The - return value is ignored. + \value ItemSceneHasChanged The item's scene has changed. The item's scene() is + the new scene. This notification is also sent when the item is added to its + initial scene, and when it is removed.The value argument is the new scene + (i.e., a pointer to a QGraphicsScene). Do not call setScene() in itemChange() + as this notification is delivered. The return value is ignored. \value ItemCursorChange The item's cursor changes. The value argument is the new cursor (i.e., a QCursor). Do not call setCursor() in itemChange() diff --git a/src/gui/image/qicon.cpp b/src/gui/image/qicon.cpp index 158f9ab..7182062 100644 --- a/src/gui/image/qicon.cpp +++ b/src/gui/image/qicon.cpp @@ -972,12 +972,15 @@ QString QIcon::themeName() Returns the QIcon corresponding to \a name in the current icon theme. If no such icon is found in the current theme - \a fallback is return instead. + \a fallback is returned instead. - The lastest version of the freedesktop icon specification and naming - spesification can be obtained here: - http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html - http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html + The latest version of the freedesktop icon specification and naming + specification can be obtained here: + + \list + \o \l{http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html} + \o \l{http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html} + \endlist To fetch an icon from the current icon theme: diff --git a/src/gui/image/qimage.cpp b/src/gui/image/qimage.cpp index d992dd5..62116f3 100644 --- a/src/gui/image/qimage.cpp +++ b/src/gui/image/qimage.cpp @@ -797,6 +797,8 @@ QImage::QImage() Constructs an image with the given \a width, \a height and \a format. + A \l{isNull()}{null} image will be returned if memory cannot be allocated. + \warning This will create a QImage with uninitialized data. Call fill() to fill the image with an appropriate pixel value before drawing onto it with QPainter. @@ -810,6 +812,8 @@ QImage::QImage(int width, int height, Format format) /*! Constructs an image with the given \a size and \a format. + A \l{isNull()}{null} image is returned if memory cannot be allocated. + \warning This will create a QImage with uninitialized data. Call fill() to fill the image with an appropriate pixel value before drawing onto it with QPainter. diff --git a/src/gui/inputmethod/qcoefepinputcontext_s60.cpp b/src/gui/inputmethod/qcoefepinputcontext_s60.cpp index 41abe95..2c70ade 100644 --- a/src/gui/inputmethod/qcoefepinputcontext_s60.cpp +++ b/src/gui/inputmethod/qcoefepinputcontext_s60.cpp @@ -416,7 +416,8 @@ void QCoeFepInputContext::resetSplitViewWidget(bool keepInputWidget) int index = gv->scene()->focusItem()->toGraphicsObject()->metaObject()->indexOfSignal(signal.right(signal.length() - 1)); if (index != -1) disconnect(gv->scene()->focusItem()->toGraphicsObject(), SIGNAL(cursorPositionChanged()), this, SLOT(translateInputWidget())); - QGraphicsItem *rootItem; + + QGraphicsItem *rootItem = 0; foreach (QGraphicsItem *item, gv->scene()->items()) { if (!item->parentItem()) { rootItem = item; @@ -828,7 +829,7 @@ void QCoeFepInputContext::translateInputWidget() return; // Fetch root item (i.e. graphicsitem with no parent) - QGraphicsItem *rootItem; + QGraphicsItem *rootItem = 0; foreach (QGraphicsItem *item, gv->scene()->items()) { if (!item->parentItem()) { rootItem = item; diff --git a/src/gui/inputmethod/qinputcontext.cpp b/src/gui/inputmethod/qinputcontext.cpp index 063aefd..f083e51 100644 --- a/src/gui/inputmethod/qinputcontext.cpp +++ b/src/gui/inputmethod/qinputcontext.cpp @@ -355,9 +355,10 @@ void QInputContext::widgetDestroyed(QWidget *widget) in complex input method. In the case, call QInputContext::reset() to ensure proper termination of inputting. - You must not send any QInputMethodEvent except empty InputMethodEnd event using - QInputContext::reset() at reimplemented reset(). It will break - input state consistency. + In a reimplementation of reset(), you must not send any + QInputMethodEvent containing preedit text. You can only commit + string and attributes; otherwise, you risk breaking input state + consistency. */ diff --git a/src/gui/itemviews/qheaderview.cpp b/src/gui/itemviews/qheaderview.cpp index d6d9536..471c199 100644 --- a/src/gui/itemviews/qheaderview.cpp +++ b/src/gui/itemviews/qheaderview.cpp @@ -643,8 +643,12 @@ int QHeaderView::sectionSize(int logicalIndex) const } /*! - Returns the section position of the given \a logicalIndex, or -1 if the - section is hidden. + + Returns the section position of the given \a logicalIndex, or -1 + if the section is hidden. The position is measured in pixels from + the first visible item's top-left corner to the top-left corner of + the item with \a logicalIndex. The measurement is along the x-axis + for horizontal headers and along the y-axis for vertical headers. \sa sectionViewportPosition() */ diff --git a/src/gui/itemviews/qlistwidget.cpp b/src/gui/itemviews/qlistwidget.cpp index 94e3b76..61a935f 100644 --- a/src/gui/itemviews/qlistwidget.cpp +++ b/src/gui/itemviews/qlistwidget.cpp @@ -1500,7 +1500,9 @@ void QListWidget::setCurrentRow(int row, QItemSelectionModel::SelectionFlags com } /*! - Returns a pointer to the item at the coordinates \a p. + Returns a pointer to the item at the coordinates \a p. The coordinates + are relative to the list widget's \l{QAbstractScrollArea::}{viewport()}. + */ QListWidgetItem *QListWidget::itemAt(const QPoint &p) const { @@ -1514,6 +1516,9 @@ QListWidgetItem *QListWidget::itemAt(const QPoint &p) const \overload Returns a pointer to the item at the coordinates (\a x, \a y). + The coordinates are relative to the list widget's + \l{QAbstractScrollArea::}{viewport()}. + */ diff --git a/src/gui/itemviews/qtreewidget.cpp b/src/gui/itemviews/qtreewidget.cpp index 4db29d6..2ea9a43 100644 --- a/src/gui/itemviews/qtreewidget.cpp +++ b/src/gui/itemviews/qtreewidget.cpp @@ -2830,7 +2830,8 @@ void QTreeWidget::setCurrentItem(QTreeWidgetItem *item, int column, /*! - Returns a pointer to the item at the coordinates \a p. + Returns a pointer to the item at the coordinates \a p. The coordinates + are relative to the tree widget's \l{QAbstractScrollArea::}{viewport()}. \sa visualItemRect() */ @@ -2844,7 +2845,8 @@ QTreeWidgetItem *QTreeWidget::itemAt(const QPoint &p) const \fn QTreeWidgetItem *QTreeWidget::itemAt(int x, int y) const \overload - Returns a pointer to the item at the coordinates (\a x, \a y). + Returns a pointer to the item at the coordinates (\a x, \a y). The coordinates + are relative to the tree widget's \l{QAbstractScrollArea::}{viewport()}. */ /*! diff --git a/src/gui/kernel/qapplication_s60.cpp b/src/gui/kernel/qapplication_s60.cpp index 3d642d0..769b136 100644 --- a/src/gui/kernel/qapplication_s60.cpp +++ b/src/gui/kernel/qapplication_s60.cpp @@ -1271,15 +1271,36 @@ void QSymbianControl::FocusChanged(TDrawNow /* aDrawNow */) qwidget->d_func()->setWindowIcon_sys(true); qwidget->d_func()->setWindowTitle_sys(qwidget->windowTitle()); #ifdef Q_WS_S60 - // If widget is fullscreen/minimized, hide status pane and button container otherwise show them. - QWidget *const window = qwidget->window(); - if (!window->parentWidget()) { // Only top level native windows have control over cba/status pane - const bool decorationsVisible = !(window->windowState() & (Qt::WindowFullScreen | Qt::WindowMinimized)); - const bool statusPaneVisibility = decorationsVisible; - const bool isFullscreen = window->windowState() & Qt::WindowFullScreen; - const bool cbaVisibilityHint = window->windowFlags() & Qt::WindowSoftkeysVisibleHint; - const bool buttonGroupVisibility = (decorationsVisible || (isFullscreen && cbaVisibilityHint)); - S60->setStatusPaneAndButtonGroupVisibility(statusPaneVisibility, buttonGroupVisibility); + if (qwidget->isWindow()) { + QWidget *const window = qwidget->window(); + QWidget *parentWindow = window->parentWidget(); + if (parentWindow) { + while (parentWindow->parentWidget()) + parentWindow = parentWindow->parentWidget(); + } else { + parentWindow = window; + } + + const bool parentDecorationsVisible = !(parentWindow->windowState() & (Qt::WindowFullScreen | Qt::WindowMinimized)); + const bool parentIsFullscreen = parentWindow->windowState() & Qt::WindowFullScreen; + const bool parentCbaVisibilityHint = parentWindow->windowFlags() & Qt::WindowSoftkeysVisibleHint; + bool buttonGroupVisibility = (parentDecorationsVisible || (parentIsFullscreen && parentCbaVisibilityHint)); + + // For non-toplevel normal and maximized windows, show cba if window has softkey + // actions even if topmost parent is not showing cba. Do the same for fullscreen + // windows that request it. + if (!buttonGroupVisibility + && window->parentWidget() + && !(window->windowState() & Qt::WindowMinimized) + && ((window->windowFlags() & Qt::WindowSoftkeysVisibleHint) || !(window->windowState() & Qt::WindowFullScreen))) { + for (int i = 0; i < window->actions().size(); ++i) { + if (window->actions().at(i)->softKeyRole() != QAction::NoSoftKey) { + buttonGroupVisibility = true; + break; + } + } + } + S60->setStatusPaneAndButtonGroupVisibility(parentDecorationsVisible, buttonGroupVisibility); } #endif } else if (QApplication::activeWindow() == qwidget->window()) { @@ -1455,6 +1476,35 @@ bool QSymbianControl::isControlActive() return IsActivated() ? true : false; } +void QSymbianControl::ensureFixNativeOrientation() +{ +#if defined(Q_SYMBIAN_SUPPORTS_FIXNATIVEORIENTATION) + // Call FixNativeOrientation() for fullscreen QDeclarativeViews that + // have a locked orientation matching the native orientation of the device. + // This avoids unnecessary window rotation on wserv level. + if (!qwidget->isWindow() || qwidget->windowType() == Qt::Desktop + || !qwidget->inherits("QDeclarativeView") + || S60->screenNumberForWidget(qwidget) > 0) + return; + const bool isFullScreen = qwidget->windowState().testFlag(Qt::WindowFullScreen); + const bool isFixed = qwidget->d_func()->fixNativeOrientationCalled; + const bool matchesNative = qwidget->testAttribute( + S60->nativeOrientationIsPortrait ? Qt::WA_LockPortraitOrientation + : Qt::WA_LockLandscapeOrientation); + if (isFullScreen && matchesNative) { + if (!isFixed) { + Window().FixNativeOrientation(); + qwidget->d_func()->fixNativeOrientationCalled = true; + } + } else if (isFixed) { + qwidget->d_func()->fixNativeOrientationCalled = false; + qwidget->hide(); + qwidget->d_func()->create_sys(0, false, true); + qwidget->show(); + } +#endif +} + /*! \typedef QApplication::QS60MainApplicationFactory \since 4.6 diff --git a/src/gui/kernel/qsoftkeymanager_s60.cpp b/src/gui/kernel/qsoftkeymanager_s60.cpp index 3496297..09e2b5f 100644 --- a/src/gui/kernel/qsoftkeymanager_s60.cpp +++ b/src/gui/kernel/qsoftkeymanager_s60.cpp @@ -113,12 +113,20 @@ void QSoftKeyManagerPrivateS60::ensureCbaVisibilityAndResponsiviness(CEikButtonG void QSoftKeyManagerPrivateS60::clearSoftkeys(CEikButtonGroupContainer &cba) { +#ifdef SYMBIAN_VERSION_SYMBIAN3 + QT_TRAP_THROWING( + //EAknSoftkeyEmpty is used, because using -1 adds softkeys without actions on Symbian3 + cba.SetCommandL(0, EAknSoftkeyEmpty, KNullDesC); + cba.SetCommandL(2, EAknSoftkeyEmpty, KNullDesC); + ); +#else QT_TRAP_THROWING( //Using -1 instead of EAknSoftkeyEmpty to avoid flickering. cba.SetCommandL(0, -1, KNullDesC); // TODO: Should we clear also middle SK? cba.SetCommandL(2, -1, KNullDesC); ); +#endif realSoftKeyActions.clear(); } diff --git a/src/gui/kernel/qt_s60_p.h b/src/gui/kernel/qt_s60_p.h index 3bb27c3..102c0ca 100644 --- a/src/gui/kernel/qt_s60_p.h +++ b/src/gui/kernel/qt_s60_p.h @@ -189,6 +189,8 @@ public: int screenHeightInPixelsForScreen[qt_symbian_max_screens]; int screenWidthInTwipsForScreen[qt_symbian_max_screens]; int screenHeightInTwipsForScreen[qt_symbian_max_screens]; + + bool nativeOrientationIsPortrait; }; Q_AUTOTEST_EXPORT QS60Data* qGlobalS60Data(); @@ -233,6 +235,8 @@ public: bool isControlActive(); + void ensureFixNativeOrientation(); + #ifdef Q_WS_S60 void FadeBehindPopup(bool fade){ popupFader.FadeBehindPopup( this, this, fade); } void HandleStatusPaneSizeChange(); @@ -327,9 +331,11 @@ inline QS60Data::QS60Data() inline void QS60Data::updateScreenSize() { + CWsScreenDevice *dev = S60->screenDevice(); + int screenModeCount = dev->NumScreenModes(); + int mode = dev->CurrentScreenMode(); TPixelsTwipsAndRotation params; - int mode = S60->screenDevice()->CurrentScreenMode(); - S60->screenDevice()->GetScreenModeSizeAndRotation(mode, params); + dev->GetScreenModeSizeAndRotation(mode, params); S60->screenWidthInPixels = params.iPixelSize.iWidth; S60->screenHeightInPixels = params.iPixelSize.iHeight; S60->screenWidthInTwips = params.iTwipsSize.iWidth; @@ -352,6 +358,21 @@ inline void QS60Data::updateScreenSize() S60->screenWidthInTwipsForScreen[i] = params.iTwipsSize.iWidth; S60->screenHeightInTwipsForScreen[i] = params.iTwipsSize.iHeight; } + + // Look for a screen mode with rotation 0 + // in order to decide what the native orientation is. + int nativeScreenWidthInPixels = 0; + int nativeScreenHeightInPixels = 0; + for (mode = 0; mode < screenModeCount; ++mode) { + TPixelsAndRotation sizeAndRotation; + dev->GetScreenModeSizeAndRotation(mode, sizeAndRotation); + if (sizeAndRotation.iRotation == CFbsBitGc::EGraphicsOrientationNormal) { + nativeScreenWidthInPixels = sizeAndRotation.iPixelSize.iWidth; + nativeScreenHeightInPixels = sizeAndRotation.iPixelSize.iHeight; + break; + } + } + S60->nativeOrientationIsPortrait = nativeScreenWidthInPixels <= nativeScreenHeightInPixels; } inline RWsSession& QS60Data::wsSession() diff --git a/src/gui/kernel/qwidget.cpp b/src/gui/kernel/qwidget.cpp index 4b7349b..3cc3e65 100644 --- a/src/gui/kernel/qwidget.cpp +++ b/src/gui/kernel/qwidget.cpp @@ -312,6 +312,7 @@ QWidgetPrivate::QWidgetPrivate(int version) , qd_hd(0) #elif defined(Q_OS_SYMBIAN) , symbianScreenNumber(0) + , fixNativeOrientationCalled(false) #endif { if (!qApp) { @@ -10970,6 +10971,9 @@ void QWidget::setAttribute(Qt::WidgetAttribute attribute, bool on) } QT_TRAP_THROWING(appUi->SetOrientationL(s60orientation)); S60->orientationSet = true; + QSymbianControl *window = static_cast<QSymbianControl *>(internalWinId()); + if (window) + window->ensureFixNativeOrientation(); #endif break; } diff --git a/src/gui/kernel/qwidget_p.h b/src/gui/kernel/qwidget_p.h index e5a2c35..919f8bc 100644 --- a/src/gui/kernel/qwidget_p.h +++ b/src/gui/kernel/qwidget_p.h @@ -908,6 +908,7 @@ public: static QWidget *mouseGrabber; static QWidget *keyboardGrabber; int symbianScreenNumber; // only valid for desktop widget and top-levels + bool fixNativeOrientationCalled; void s60UpdateIsOpaque(); void reparentChildren(); void registerTouchWindow(); diff --git a/src/gui/kernel/qwidget_s60.cpp b/src/gui/kernel/qwidget_s60.cpp index b031936..d4eadaa 100644 --- a/src/gui/kernel/qwidget_s60.cpp +++ b/src/gui/kernel/qwidget_s60.cpp @@ -278,6 +278,8 @@ void QWidgetPrivate::setGeometry_sys(int x, int y, int w, int h, bool isMove) q->internalWinId()->SetRect(TRect(TPoint(x, y), TSize(w, h))); topData()->normalGeometry = data.crect; } + QSymbianControl *window = static_cast<QSymbianControl *>(q->internalWinId()); + window->ensureFixNativeOrientation(); } else { data.crect.setRect(x, y, w, h); @@ -1208,17 +1210,41 @@ void QWidget::setWindowState(Qt::WindowStates newstate) } #ifdef Q_WS_S60 - bool decorationsVisible(false); - if (!parentWidget()) { // Only top level native windows have control over cba/status pane - // Hide window decoration when switching to fullscreen / minimized otherwise show decoration. - // The window decoration visibility has to be changed before doing actual window state - // change since in that order the availableGeometry will return directly the right size and - // we will avoid unnecessary redraws - decorationsVisible = !(newstate & (Qt::WindowFullScreen | Qt::WindowMinimized)); - const bool statusPaneVisibility = decorationsVisible; - const bool buttonGroupVisibility = (decorationsVisible || (isFullscreen && cbaRequested)); - S60->setStatusPaneAndButtonGroupVisibility(statusPaneVisibility, buttonGroupVisibility); + // Hide window decoration when switching to fullscreen / minimized otherwise show decoration. + // The window decoration visibility has to be changed before doing actual window state + // change since in that order the availableGeometry will return directly the right size and + // we will avoid unnecessary redraws + Qt::WindowStates comparisonState = newstate; + QWidget *parentWindow = parentWidget(); + if (parentWindow) { + while (parentWindow->parentWidget()) + parentWindow = parentWindow->parentWidget(); + comparisonState = parentWindow->windowState(); + } else { + parentWindow = this; + } + + const bool decorationsVisible = !(comparisonState & (Qt::WindowFullScreen | Qt::WindowMinimized)); + const bool parentIsFullscreen = comparisonState & Qt::WindowFullScreen; + const bool parentCbaVisibilityHint = parentWindow->windowFlags() & Qt::WindowSoftkeysVisibleHint; + bool buttonGroupVisibility = (decorationsVisible || (parentIsFullscreen && parentCbaVisibilityHint)); + + // For non-toplevel normal and maximized windows, show cba if window has softkey + // actions even if topmost parent is not showing cba. Do the same for fullscreen + // windows that request it. + if (!buttonGroupVisibility + && parentWidget() + && !(newstate & Qt::WindowMinimized) + && ((windowFlags() & Qt::WindowSoftkeysVisibleHint) || !(newstate & Qt::WindowFullScreen))) { + for (int i = 0; i < actions().size(); ++i) { + if (actions().at(i)->softKeyRole() != QAction::NoSoftKey) { + buttonGroupVisibility = true; + break; + } + } } + S60->setStatusPaneAndButtonGroupVisibility(decorationsVisible, buttonGroupVisibility); + #endif // Q_WS_S60 // Ensure the initial size is valid, since we store it as normalGeometry below. @@ -1277,6 +1303,12 @@ void QWidget::setWindowState(Qt::WindowStates newstate) if (newstate & Qt::WindowActive) activateWindow(); + if (isWindow()) { + // Now that the new state is set, fix the display memory layout, if needed. + QSymbianControl *window = static_cast<QSymbianControl *>(effectiveWinId()); + window->ensureFixNativeOrientation(); + } + QWindowStateChangeEvent e(oldstate); QApplication::sendEvent(this, &e); } diff --git a/src/gui/painting/qpaintengine_mac.cpp b/src/gui/painting/qpaintengine_mac.cpp index 2f35dcd..8aab7c7 100644 --- a/src/gui/painting/qpaintengine_mac.cpp +++ b/src/gui/painting/qpaintengine_mac.cpp @@ -972,7 +972,7 @@ void QCoreGraphicsPaintEngine::drawPixmap(const QRectF &r, const QPixmap &pm, co return; bool differentSize = (QRectF(0, 0, pm.width(), pm.height()) != sr), doRestore = false; - CGRect rect = CGRectMake(qRound(r.x()), qRound(r.y()), qRound(r.width()), qRound(r.height())); + CGRect rect = CGRectMake(r.x(), r.y(), r.width(), r.height()); QCFType<CGImageRef> image; bool isBitmap = (pm.depth() == 1); if (isBitmap) { diff --git a/src/gui/painting/qpainterpath.cpp b/src/gui/painting/qpainterpath.cpp index 49f1a5f..2058040 100644 --- a/src/gui/painting/qpainterpath.cpp +++ b/src/gui/painting/qpainterpath.cpp @@ -1897,39 +1897,39 @@ static bool qt_painterpath_isect_line_rect(qreal x1, qreal y1, qreal x2, qreal y return false; } -static bool qt_isect_curve_horizontal(const QBezier &bezier, qreal y, qreal x1, qreal x2) +static bool qt_isect_curve_horizontal(const QBezier &bezier, qreal y, qreal x1, qreal x2, int depth = 0) { QRectF bounds = bezier.bounds(); if (y >= bounds.top() && y < bounds.bottom() && bounds.right() >= x1 && bounds.left() < x2) { const qreal lower_bound = qreal(.01); - if (bounds.width() < lower_bound && bounds.height() < lower_bound) + if (depth == 32 || bounds.width() < lower_bound && bounds.height() < lower_bound) return true; QBezier first_half, second_half; bezier.split(&first_half, &second_half); - if (qt_isect_curve_horizontal(first_half, y, x1, x2) - || qt_isect_curve_horizontal(second_half, y, x1, x2)) + if (qt_isect_curve_horizontal(first_half, y, x1, x2, depth + 1) + || qt_isect_curve_horizontal(second_half, y, x1, x2, depth + 1)) return true; } return false; } -static bool qt_isect_curve_vertical(const QBezier &bezier, qreal x, qreal y1, qreal y2) +static bool qt_isect_curve_vertical(const QBezier &bezier, qreal x, qreal y1, qreal y2, int depth = 0) { QRectF bounds = bezier.bounds(); if (x >= bounds.left() && x < bounds.right() && bounds.bottom() >= y1 && bounds.top() < y2) { const qreal lower_bound = qreal(.01); - if (bounds.width() < lower_bound && bounds.height() < lower_bound) + if (depth == 32 || bounds.width() < lower_bound && bounds.height() < lower_bound) return true; QBezier first_half, second_half; bezier.split(&first_half, &second_half); - if (qt_isect_curve_vertical(first_half, x, y1, y2) - || qt_isect_curve_vertical(second_half, x, y1, y2)) + if (qt_isect_curve_vertical(first_half, x, y1, y2, depth + 1) + || qt_isect_curve_vertical(second_half, x, y1, y2, depth + 1)) return true; } return false; diff --git a/src/gui/styles/qs60style.cpp b/src/gui/styles/qs60style.cpp index ac897b5..2d9b6cd 100644 --- a/src/gui/styles/qs60style.cpp +++ b/src/gui/styles/qs60style.cpp @@ -107,8 +107,8 @@ const short QS60StylePrivate::data[][MAX_PIXELMETRICS] = { // *** generated pixel metrics *** {5,0,-909,0,0,2,0,2,-1,7,12,22,15,15,7,198,-909,-909,-909,20,13,2,0,0,21,7,18,30,3,3,1,-909,-909,0,1,0,0,12,20,15,15,18,18,1,115,18,0,-909,-909,-909,-909,0,0,16,2,-909,0,0,-909,16,-909,-909,-909,-909,32,18,55,24,55,4,4,4,9,13,-909,5,51,11,5,0,3,3,6,8,3,3,-909,2,-909,-909,-909,-909,5,5,3,1,106}, {5,0,-909,0,0,1,0,2,-1,8,14,22,15,15,7,164,-909,-909,-909,19,15,2,0,0,21,8,27,28,4,4,1,-909,-909,0,7,6,0,13,23,17,17,21,21,7,115,21,0,-909,-909,-909,-909,0,0,15,1,-909,0,0,-909,15,-909,-909,-909,-909,32,21,65,27,65,3,3,5,10,15,-909,5,58,13,5,0,4,4,7,9,4,4,-909,2,-909,-909,-909,-909,6,6,3,1,106}, -{7,0,-909,0,0,2,0,5,-1,25,69,46,37,37,9,258,-909,-909,-909,23,19,26,0,0,32,25,72,44,5,5,2,-909,-909,0,7,21,0,17,29,22,22,27,27,7,173,29,0,-909,-909,-909,-909,0,0,25,2,-909,0,0,-909,25,-909,-909,-909,-909,87,27,77,35,77,13,3,6,8,19,-909,7,74,19,7,0,5,5,8,12,5,5,-909,3,-909,-909,-909,-909,7,7,3,1,135}, -{7,0,-909,0,0,2,0,5,-1,25,68,46,37,37,9,258,-909,-909,-909,31,19,6,0,0,32,25,60,52,5,5,2,-909,-909,0,7,32,0,17,29,22,22,27,27,7,173,29,0,-909,-909,-909,-909,0,0,26,2,-909,0,0,-909,26,-909,-909,-909,-909,87,27,96,35,96,12,3,6,8,19,-909,7,74,22,7,0,5,5,8,12,5,5,-909,3,-909,-909,-909,-909,7,7,3,1,135}, +{7,0,-909,0,0,2,0,5,-1,25,69,46,37,37,9,258,-909,-909,-909,23,19,11,0,0,32,25,72,44,5,5,2,-909,-909,0,7,21,0,17,29,22,22,27,27,7,173,29,0,-909,-909,-909,-909,0,0,25,2,-909,0,0,-909,25,-909,-909,-909,-909,87,27,77,35,77,13,3,6,8,19,-909,7,74,19,7,0,5,5,8,12,5,5,-909,3,-909,-909,-909,-909,7,7,3,1,135}, +{7,0,-909,0,0,2,0,5,-1,25,68,46,37,37,9,258,-909,-909,-909,31,19,13,0,0,32,25,60,52,5,5,2,-909,-909,0,7,32,0,17,29,22,22,27,27,7,173,29,0,-909,-909,-909,-909,0,0,26,2,-909,0,0,-909,26,-909,-909,-909,-909,87,27,96,35,96,12,3,6,8,19,-909,7,74,22,7,0,5,5,8,12,5,5,-909,3,-909,-909,-909,-909,7,7,3,1,135}, {7,0,-909,0,0,2,0,2,-1,10,20,27,18,18,9,301,-909,-909,-909,29,18,5,0,0,35,7,32,30,5,5,2,-909,-909,0,2,8,0,16,28,21,21,26,26,2,170,26,0,-909,-909,-909,-909,0,0,21,6,-909,0,0,-909,-909,-909,-909,-909,-909,54,26,265,34,265,5,5,6,3,18,-909,7,72,19,7,0,5,6,8,11,6,5,-909,2,-909,-909,-909,-909,5,5,3,1,106}, {9,0,-909,0,0,2,0,5,-1,34,99,76,51,51,25,352,-909,-909,-909,29,25,7,0,0,43,34,42,76,7,7,2,-909,-909,0,9,14,0,23,39,30,30,37,37,9,391,40,0,-909,-909,-909,-909,0,0,29,2,-909,0,0,-909,29,-909,-909,-909,-909,115,37,96,48,96,19,19,9,1,25,-909,9,101,24,9,0,7,7,7,16,7,7,-909,3,-909,-909,-909,-909,9,9,3,1,184} // *** End of generated data *** @@ -1743,16 +1743,26 @@ void QS60Style::drawControl(ControlElement element, const QStyleOption *option, QStyleOptionMenuItem optionMenuItem = *menuItem; bool drawSubMenuIndicator = false; + bool drawSeparator = false; switch(menuItem->menuItemType) { - case QStyleOptionMenuItem::Scroller: case QStyleOptionMenuItem::Separator: - return; // no separators or scrollers in S60 menus + drawSeparator = true; + break; + case QStyleOptionMenuItem::Scroller: + return; // no scrollers in S60 menus case QStyleOptionMenuItem::SubMenu: drawSubMenuIndicator = true; break; default: break; } + if (drawSeparator) { + painter->save(); + painter->setPen(QS60StylePrivate::s60Color(QS60StyleEnums::CL_QsnLineColors, 10, 0)); + painter->drawLine(optionMenuItem.rect.topLeft(), optionMenuItem.rect.bottomRight()); + painter->restore(); + return; + } const bool enabled = optionMenuItem.state & State_Enabled; const bool checkable = optionMenuItem.checkType != QStyleOptionMenuItem::NotCheckable; bool ignoreCheckMark = false; @@ -1856,20 +1866,26 @@ void QS60Style::drawControl(ControlElement element, const QStyleOption *option, //In Sym^3, native menu items have "lines" between them if (QS60StylePrivate::isSingleClickUi()) { - const QColor lineColorAlpha = QS60StylePrivate::s60Color(QS60StyleEnums::CL_QsnLineColors, 15, 0); - const int spacing = QS60StylePrivate::pixelMetric(PM_FrameCornerWidth); - //native platform sets each color byte to same value for "line 16" which just defines alpha for - //menuitem lines; lets use first byte "red". - QColor lineColor = optionMenuItem.palette.text().color(); - if (lineColorAlpha.isValid()) - lineColor.setAlpha(lineColorAlpha.red()); - painter->save(); - painter->setPen(lineColor); - - const int lineStartX = optionMenuItem.rect.left() + (QS60StylePrivate::pixelMetric(PM_FrameCornerWidth) - 2) + spacing; - const int lineEndX = optionMenuItem.rect.right() - (QS60StylePrivate::pixelMetric(PM_FrameCornerWidth) - 2) - spacing; - painter->drawLine(QPoint(lineStartX, optionMenuItem.rect.bottom()), QPoint(lineEndX, optionMenuItem.rect.bottom())); - painter->restore(); + int diff = widget->geometry().bottom() - optionMenuItem.rect.bottom(); + if (const QComboBox *cb = qobject_cast<const QComboBox*>(widget)) + diff = cb->view()->geometry().bottom() - optionMenuItem.rect.bottom(); + + // Skip drawing the horizontal line for the last menu item. + if (diff > optionMenuItem.rect.height()) { + const QColor lineColorAlpha = QS60StylePrivate::s60Color(QS60StyleEnums::CL_QsnLineColors, 15, 0); + //native platform sets each color byte to same value for "line 16" which just defines alpha for + //menuitem lines; lets use first byte "red". + QColor lineColor = optionMenuItem.palette.text().color(); + if (lineColorAlpha.isValid()) + lineColor.setAlpha(lineColorAlpha.red()); + painter->save(); + painter->setPen(lineColor); + const int horizontalMargin = 2 * QS60StylePrivate::pixelMetric(PM_FrameCornerWidth) - QS60StylePrivate::pixelMetric(PM_DefaultFrameWidth); + const int lineStartX = optionMenuItem.rect.left() + horizontalMargin; + const int lineEndX = optionMenuItem.rect.right() - horizontalMargin; + painter->drawLine(QPoint(lineStartX, optionMenuItem.rect.bottom()), QPoint(lineEndX, optionMenuItem.rect.bottom())); + painter->restore(); + } } if (!enabled) painter->restore(); @@ -2264,13 +2280,15 @@ void QS60Style::drawPrimitive(PrimitiveElement element, const QStyleOption *opti #endif //QT_NO_MENU ) { //Need extra check since dialogs have their own theme background - if (QS60StylePrivate::canDrawThemeBackground(option->palette.base(), widget) && - QS60StylePrivate::equalToThemePalette(option->palette.window().texture().cacheKey(), QPalette::Window)) - //todo: for combobox listviews, the background should include area for menu scrollers, - //but this produces drawing issues as we need to turn clipping off. - QS60StylePrivate::drawSkinElement(QS60StylePrivate::SE_PopupBackground, painter, option->rect, flags); - else + if (QS60StylePrivate::canDrawThemeBackground(option->palette.base(), widget) + && QS60StylePrivate::equalToThemePalette(option->palette.window().texture().cacheKey(), QPalette::Window)) { + // Add margin area to the background, to avoid background being cut for first and last item. + const int verticalMenuAdjustment = QS60StylePrivate::pixelMetric(PM_MenuVMargin); + const QRect adjustedMenuRect = option->rect.adjusted(0, -verticalMenuAdjustment, 0, verticalMenuAdjustment); + QS60StylePrivate::drawSkinElement(QS60StylePrivate::SE_PopupBackground, painter, adjustedMenuRect, flags); + } else { commonStyleDraws = true; + } } break; case PE_FrameWindow: @@ -2538,17 +2556,16 @@ QSize QS60Style::sizeFromContents(ContentsType ct, const QStyleOption *opt, tb->sizePolicy().horizontalPolicy() == QSizePolicy::Maximum) && tb->orientation() == Qt::Horizontal; if (parentCanGrowHorizontally) { - int visibleButtons = 0; + int buttons = 0; //Make the auto-stretch to happen only for horizontal orientation if (tb && tb->orientation() == Qt::Horizontal) { QList<QAction*> actionList = tb->actions(); for (int i = 0; i < actionList.count(); i++) { - if (actionList.at(i)->isVisible()) - visibleButtons++; + buttons++; } } - if (widget->parentWidget() && visibleButtons > 0) { + if (widget->parentWidget() && buttons > 0) { QWidget *w = const_cast<QWidget *>(widget); int toolBarMaxWidth = 0; int totalMargin = 0; @@ -2571,7 +2588,7 @@ QSize QS60Style::sizeFromContents(ContentsType ct, const QStyleOption *opt, toolBarMaxWidth -= totalMargin; //ensure that buttons are side-by-side and not on top of each other - const int toolButtonWidth = (toolBarMaxWidth / visibleButtons) + const int toolButtonWidth = (toolBarMaxWidth / buttons) - pixelMetric(QStyle::PM_ToolBarItemSpacing) - pixelMetric(QStyle::PM_ToolBarItemMargin) //toolbar frame needs to be reduced again, since QToolBarLayout adds it for each toolbar action @@ -2604,10 +2621,7 @@ QSize QS60Style::sizeFromContents(ContentsType ct, const QStyleOption *opt, sz += QSize(2 * f->lineWidth, 4 * f->lineWidth); break; case CT_TabBarTab: { - const QSize naviPaneSize = QS60StylePrivate::naviPaneSize(); sz = QCommonStyle::sizeFromContents(ct, opt, csz, widget); - if (naviPaneSize.height() > sz.height()) - sz.setHeight(naviPaneSize.height()); // Adjust beginning tabbar item size, if scrollbuttons are used. This is to ensure that the // tabbar item content fits, since scrollbuttons are making beginning tabbar item smaller. int scrollButtonSize = 0; @@ -2627,7 +2641,7 @@ QSize QS60Style::sizeFromContents(ContentsType ct, const QStyleOption *opt, case CT_ItemViewItem: if (const QStyleOptionMenuItem *menuItem = qstyleoption_cast<const QStyleOptionMenuItem *>(opt)) { if (menuItem->menuItemType == QStyleOptionMenuItem::Separator) { - sz = QSize(); + sz = QSize(menuItem->rect.width(), 1); break; } } diff --git a/src/gui/styles/qs60style_p.h b/src/gui/styles/qs60style_p.h index 3628b27..e146a4e 100644 --- a/src/gui/styles/qs60style_p.h +++ b/src/gui/styles/qs60style_p.h @@ -562,8 +562,6 @@ public: void handleSkinChange(); #endif // Q_WS_S60 - static QSize naviPaneSize(); - //Checks that the current brush is transparent or has BrushStyle NoBrush, //so that theme graphic background can be drawn. static bool canDrawThemeBackground(const QBrush &backgroundBrush, const QWidget *widget); diff --git a/src/gui/styles/qs60style_s60.cpp b/src/gui/styles/qs60style_s60.cpp index 64d2ad2..6a7158c 100644 --- a/src/gui/styles/qs60style_s60.cpp +++ b/src/gui/styles/qs60style_s60.cpp @@ -158,7 +158,6 @@ public: static bool disabledPartGraphic(QS60StyleEnums::SkinParts &part); static bool disabledFrameGraphic(QS60StylePrivate::SkinFrameElements &frame); static QPixmap generateMissingThemeGraphic(QS60StyleEnums::SkinParts &part, const QSize &size, QS60StylePrivate::SkinElementFlags flags); - static QSize naviPaneSize(); static TAknsItemID partSpecificThemeId(int part); static QVariant themeDefinition(QS60StyleEnums::ThemeDefinitions definition, QS60StyleEnums::SkinParts part); @@ -1478,23 +1477,6 @@ void QS60StylePrivate::handleSkinChange() #endif } -QSize QS60StylePrivate::naviPaneSize() -{ - return QS60StyleModeSpecifics::naviPaneSize(); -} - -QSize QS60StyleModeSpecifics::naviPaneSize() -{ - CAknNavigationControlContainer* naviContainer; - if (S60->statusPane()) { - TRAPD(err, naviContainer = static_cast<CAknNavigationControlContainer*> - (S60->statusPane()->ControlL(TUid::Uid(EEikStatusPaneUidNavi)))); - if (err==KErrNone) - return QSize(naviContainer->Size().iWidth, naviContainer->Size().iHeight); - } - return QSize(0,0); -} - int QS60StylePrivate::currentAnimationFrame(QS60StyleEnums::SkinParts part) { QS60StyleAnimation *animation = animationDefinition(part); diff --git a/src/gui/styles/qs60style_simulated.cpp b/src/gui/styles/qs60style_simulated.cpp index 7223c6b..a5aeac3 100644 --- a/src/gui/styles/qs60style_simulated.cpp +++ b/src/gui/styles/qs60style_simulated.cpp @@ -318,11 +318,6 @@ QPixmap QS60StylePrivate::backgroundTexture(bool /*skipCreation*/) return *m_background; } -QSize QS60StylePrivate::naviPaneSize() -{ - return QSize(0, 0); -} - bool QS60StylePrivate::isTouchSupported() { #ifdef QT_KEYPAD_NAVIGATION diff --git a/src/gui/text/qtextcontrol.cpp b/src/gui/text/qtextcontrol.cpp index b7a2697..66ce64b 100644 --- a/src/gui/text/qtextcontrol.cpp +++ b/src/gui/text/qtextcontrol.cpp @@ -1552,7 +1552,7 @@ void QTextControlPrivate::mousePressEvent(QEvent *e, Qt::MouseButton button, con extendBlockwiseSelection(cursorPos); else if (selectedWordOnDoubleClick.hasSelection()) extendWordwiseSelection(cursorPos, pos.x()); - else if (wordSelectionEnabled) + else if (!wordSelectionEnabled) setCursorPosition(cursorPos, QTextCursor::KeepAnchor); } else { diff --git a/src/gui/widgets/qabstractscrollarea.cpp b/src/gui/widgets/qabstractscrollarea.cpp index f948af9..dabfec0 100644 --- a/src/gui/widgets/qabstractscrollarea.cpp +++ b/src/gui/widgets/qabstractscrollarea.cpp @@ -511,7 +511,7 @@ QAbstractScrollArea::QAbstractScrollArea(QAbstractScrollAreaPrivate &dd, QWidget /*! Constructs a viewport. - The \a parent arguments is sent to the QWidget constructor. + The \a parent argument is sent to the QWidget constructor. */ QAbstractScrollArea::QAbstractScrollArea(QWidget *parent) :QFrame(*new QAbstractScrollAreaPrivate, parent) diff --git a/src/gui/widgets/qabstractslider.cpp b/src/gui/widgets/qabstractslider.cpp index cb36398..2570496 100644 --- a/src/gui/widgets/qabstractslider.cpp +++ b/src/gui/widgets/qabstractslider.cpp @@ -265,7 +265,7 @@ void QAbstractSliderPrivate::setSteps(int single, int page) /*! Constructs an abstract slider. - The \a parent arguments is sent to the QWidget constructor. + The \a parent argument is sent to the QWidget constructor. The \l minimum defaults to 0, the \l maximum to 99, with a \l singleStep size of 1 and a \l pageStep size of 10, and an initial diff --git a/src/gui/widgets/qcombobox.cpp b/src/gui/widgets/qcombobox.cpp index d63ccfb..7b4ef50 100644 --- a/src/gui/widgets/qcombobox.cpp +++ b/src/gui/widgets/qcombobox.cpp @@ -947,7 +947,10 @@ QComboBox::QComboBox(bool rw, QWidget *parent, const char *name) to set and get item data (e.g., setItemData() and itemText()). You can also set a new model and view (with setModel() and setView()). For the text and icon in the combobox label, the data in the model - that has the Qt::DisplayRole and Qt::DecorationRole is used. + that has the Qt::DisplayRole and Qt::DecorationRole is used. Note + that you cannot alter the \l{QAbstractItemView::}{SelectionMode} + of the view(), e.g., by using + \l{QAbstractItemView::}{setSelectionMode()}. \image qstyle-comboboxes.png Comboboxes in the different built-in styles. @@ -2465,12 +2468,7 @@ void QComboBox::showPopup() // available screen geometry.This may override the vertical position, but it is more // important to show as much as possible of the popup. const int height = !boundToScreen ? listRect.height() : qMin(listRect.height(), screen.height()); -#ifdef Q_WS_S60 - //popup needs to be stretched with screen minimum dimension - listRect.setHeight(qMin(screen.height(), screen.width())); -#else listRect.setHeight(height); -#endif if (boundToScreen) { if (listRect.top() < screen.top()) diff --git a/src/gui/widgets/qmenu.cpp b/src/gui/widgets/qmenu.cpp index c09b5a4..b12e5c5 100644 --- a/src/gui/widgets/qmenu.cpp +++ b/src/gui/widgets/qmenu.cpp @@ -1247,37 +1247,15 @@ void QMenu::initStyleOption(QStyleOptionMenuItem *option, const QAction *action) response to button presses; these are just like context menus except for how they are invoked. - \raw HTML - <table align="center" cellpadding="0"> - <tr> - <td> - \endraw - \inlineimage plastique-menu.png - \raw HTML - </td> - <td> - \endraw - \inlineimage windowsxp-menu.png - \raw HTML - </td> - <td> - \endraw - \inlineimage macintosh-menu.png - \raw HTML - </td> - - </tr> - <tr> - <td colspan="3"> - \endraw - A menu shown in \l{Plastique Style Widget Gallery}{Plastique widget style}, + \table 100% + \row + \o \inlineimage plastique-menu.png + \o \inlineimage windowsxp-menu.png + \o \inlineimage macintosh-menu.png + \endtable + \caption Fig. A menu shown in \l{Plastique Style Widget Gallery}{Plastique widget style}, \l{Windows XP Style Widget Gallery}{Windows XP widget style}, and \l{Macintosh Style Widget Gallery}{Macintosh widget style}. - \raw HTML - </td> - </tr> - </table> - \endraw \section1 Actions diff --git a/src/gui/widgets/qscrollbar.cpp b/src/gui/widgets/qscrollbar.cpp index c895b1b..87738a0 100644 --- a/src/gui/widgets/qscrollbar.cpp +++ b/src/gui/widgets/qscrollbar.cpp @@ -330,7 +330,7 @@ void QScrollBar::initStyleOption(QStyleOptionSlider *option) const /*! Constructs a vertical scroll bar. - The \a parent arguments is sent to the QWidget constructor. + The \a parent argument is sent to the QWidget constructor. The \l {QAbstractSlider::minimum} {minimum} defaults to 0, the \l {QAbstractSlider::maximum} {maximum} to 99, with a diff --git a/src/gui/widgets/qsplitter.cpp b/src/gui/widgets/qsplitter.cpp index 964a6e1..ca8fc37 100644 --- a/src/gui/widgets/qsplitter.cpp +++ b/src/gui/widgets/qsplitter.cpp @@ -1016,7 +1016,7 @@ QSplitterLayoutStruct *QSplitterPrivate::insertWidget(int index, QWidget *w) /*! Constructs a horizontal splitter with the \a parent - arguments is passed on to the QFrame constructor. + argument passed on to the QFrame constructor. \sa setOrientation() */ diff --git a/src/imports/gestures/qdeclarativegesturearea.cpp b/src/imports/gestures/qdeclarativegesturearea.cpp index c2a2e98..aae6a01 100644 --- a/src/imports/gestures/qdeclarativegesturearea.cpp +++ b/src/imports/gestures/qdeclarativegesturearea.cpp @@ -136,7 +136,7 @@ public: GestureArea is an invisible item: it is never painted. - \sa MouseArea, {declarative/touchinteraction/gestures}{Gestures example} + \sa MouseArea */ /*! diff --git a/src/network/access/qftp.cpp b/src/network/access/qftp.cpp index ccc20e6..69e59d1 100644 --- a/src/network/access/qftp.cpp +++ b/src/network/access/qftp.cpp @@ -363,9 +363,9 @@ qint64 QFtpDTP::read(char *data, qint64 maxlen) if (socket && socket->state() == QTcpSocket::ConnectedState) { read = socket->read(data, maxlen); } else { - read = bytesFromSocket.size(); + read = qMin(maxlen, qint64(bytesFromSocket.size())); memcpy(data, bytesFromSocket.data(), read); - bytesFromSocket.clear(); + bytesFromSocket.remove(0, read); } bytesDone += read; diff --git a/src/network/ssl/qsslcertificate.cpp b/src/network/ssl/qsslcertificate.cpp index 618ac79..a5cdf01 100644 --- a/src/network/ssl/qsslcertificate.cpp +++ b/src/network/ssl/qsslcertificate.cpp @@ -219,17 +219,19 @@ bool QSslCertificate::isNull() const Returns true if this certificate is valid; otherwise returns false. - Note: Currently, this function only checks that the current + Note: Currently, this function checks that the current data-time is within the date-time range during which the - certificate is considered valid. No other checks are - currently performed. + certificate is considered valid, and checks that the + certificate is not in a blacklist of fraudulent certificates. \sa isNull() */ bool QSslCertificate::isValid() const { const QDateTime currentTime = QDateTime::currentDateTime(); - return currentTime >= d->notValidBefore && currentTime <= d->notValidAfter; + return currentTime >= d->notValidBefore && + currentTime <= d->notValidAfter && + ! QSslCertificatePrivate::isBlacklisted(*this); } /*! @@ -798,6 +800,30 @@ QList<QSslCertificate> QSslCertificatePrivate::certificatesFromDer(const QByteAr return certificates; } +// These certificates are known to be fraudulent and were created during the comodo +// compromise. See http://www.comodo.com/Comodo-Fraud-Incident-2011-03-23.html +static const char *certificate_blacklist[] = { + "04:7e:cb:e9:fc:a5:5f:7b:d0:9e:ae:36:e1:0c:ae:1e", + "f5:c8:6a:f3:61:62:f1:3a:64:f5:4f:6d:c9:58:7c:06", + "d7:55:8f:da:f5:f1:10:5b:b2:13:28:2b:70:77:29:a3", + "39:2a:43:4f:0e:07:df:1f:8a:a3:05:de:34:e0:c2:29", + "3e:75:ce:d4:6b:69:30:21:21:88:30:ae:86:a8:2a:71", + "e9:02:8b:95:78:e4:15:dc:1a:71:0a:2b:88:15:44:47", + "92:39:d5:34:8f:40:d1:69:5a:74:54:70:e1:f2:3f:43", + "b0:b7:13:3e:d0:96:f9:b5:6f:ae:91:c8:74:bd:3a:c0", + "d8:f3:5f:4e:b7:87:2b:2d:ab:06:92:e3:15:38:2f:b0", + 0 +}; + +bool QSslCertificatePrivate::isBlacklisted(const QSslCertificate &certificate) +{ + for (int a = 0; certificate_blacklist[a] != 0; a++) { + if (certificate.serialNumber() == certificate_blacklist[a]) + return true; + } + return false; +} + #ifndef QT_NO_DEBUG_STREAM QDebug operator<<(QDebug debug, const QSslCertificate &certificate) { diff --git a/src/network/ssl/qsslcertificate_p.h b/src/network/ssl/qsslcertificate_p.h index cdceb0f..1ce33d3 100644 --- a/src/network/ssl/qsslcertificate_p.h +++ b/src/network/ssl/qsslcertificate_p.h @@ -96,6 +96,7 @@ public: static QSslCertificate QSslCertificate_from_X509(X509 *x509); static QList<QSslCertificate> certificatesFromPem(const QByteArray &pem, int count = -1); static QList<QSslCertificate> certificatesFromDer(const QByteArray &der, int count = -1); + static bool isBlacklisted(const QSslCertificate &certificate); friend class QSslSocketBackendPrivate; diff --git a/src/network/ssl/qsslsocket_openssl.cpp b/src/network/ssl/qsslsocket_openssl.cpp index c1b1712..10f1f30 100644 --- a/src/network/ssl/qsslsocket_openssl.cpp +++ b/src/network/ssl/qsslsocket_openssl.cpp @@ -1237,6 +1237,13 @@ bool QSslSocketBackendPrivate::startHandshake() X509 *x509 = q_SSL_get_peer_certificate(ssl); configuration.peerCertificate = QSslCertificatePrivate::QSslCertificate_from_X509(x509); q_X509_free(x509); + if (QSslCertificatePrivate::isBlacklisted(configuration.peerCertificate)) { + q->setErrorString(QSslSocket::tr("The peer certificate is blacklisted")); + q->setSocketError(QAbstractSocket::SslHandshakeFailedError); + emit q->error(QAbstractSocket::SslHandshakeFailedError); + plainSocket->disconnectFromHost(); + return false; + } // Start translating errors. QList<QSslError> errors; diff --git a/src/opengl/qgl.cpp b/src/opengl/qgl.cpp index 4698a5c..684116c 100644 --- a/src/opengl/qgl.cpp +++ b/src/opengl/qgl.cpp @@ -69,6 +69,7 @@ #if !defined(QT_OPENGL_ES_1) #include "gl2paintengineex/qpaintengineex_opengl2_p.h" +#include <private/qwindowsurface_gl_p.h> #endif #ifndef QT_OPENGL_ES_2 @@ -90,7 +91,6 @@ #include <private/qpixmapdata_p.h> #include <private/qpixmapdata_gl_p.h> #include <private/qglpixelbuffer_p.h> -#include <private/qwindowsurface_gl_p.h> #include <private/qimagepixmapcleanuphooks_p.h> #include "qcolormap.h" #include "qfile.h" diff --git a/src/opengl/qgl_symbian.cpp b/src/opengl/qgl_symbian.cpp index 7caaabd..1b41db4 100644 --- a/src/opengl/qgl_symbian.cpp +++ b/src/opengl/qgl_symbian.cpp @@ -48,6 +48,7 @@ #include <private/qgl_p.h> #include <private/qpaintengine_opengl_p.h> #include <private/qwidget_p.h> // to access QWExtra +#include <private/qnativeimagehandleprovider_p.h> #include "qgl_egl_p.h" #include "qpixmapdata_gl_p.h" #include "qgltexturepool_p.h" @@ -411,6 +412,11 @@ void QGLPixmapData::fromNativeType(void* pixmap, NativeType type) m_hasAlpha = m_source.hasAlphaChannel(); m_hasFillColor = false; m_dirty = true; + } else if (type == QPixmapData::NativeImageHandleProvider && pixmap) { + destroyTexture(); + nativeImageHandleProvider = static_cast<QNativeImageHandleProvider *>(pixmap); + // Cannot defer the retrieval, we need at least the size right away. + createFromNativeImageHandleProvider(); } } @@ -425,4 +431,42 @@ void* QGLPixmapData::toNativeType(NativeType type) return 0; } +bool QGLPixmapData::initFromNativeImageHandle(void *handle, const QString &type) +{ + if (type == QLatin1String("RSgImage")) { + fromNativeType(handle, QPixmapData::SgImage); + return true; + } else if (type == QLatin1String("CFbsBitmap")) { + fromNativeType(handle, QPixmapData::FbsBitmap); + return true; + } + return false; +} + +void QGLPixmapData::createFromNativeImageHandleProvider() +{ + void *handle = 0; + QString type; + nativeImageHandleProvider->get(&handle, &type); + if (handle) { + if (initFromNativeImageHandle(handle, type)) { + nativeImageHandle = handle; + nativeImageType = type; + } else { + qWarning("QGLPixmapData: Unknown native image type '%s'", qPrintable(type)); + } + } else { + qWarning("QGLPixmapData: Native handle is null"); + } +} + +void QGLPixmapData::releaseNativeImageHandle() +{ + if (nativeImageHandleProvider && nativeImageHandle) { + nativeImageHandleProvider->release(nativeImageHandle, nativeImageType); + nativeImageHandle = 0; + nativeImageType = QString(); + } +} + QT_END_NAMESPACE diff --git a/src/opengl/qglpaintdevice.cpp b/src/opengl/qglpaintdevice.cpp index 7d0eb5b..61d8f26 100644 --- a/src/opengl/qglpaintdevice.cpp +++ b/src/opengl/qglpaintdevice.cpp @@ -43,13 +43,13 @@ #include <private/qgl_p.h> #include <private/qglpixelbuffer_p.h> #include <private/qglframebufferobject_p.h> -#include <private/qwindowsurface_gl_p.h> #ifdef Q_WS_X11 #include <private/qpixmapdata_x11gl_p.h> #endif #if !defined(QT_OPENGL_ES_1) #include <private/qpixmapdata_gl_p.h> +#include <private/qwindowsurface_gl_p.h> #endif QT_BEGIN_NAMESPACE diff --git a/src/opengl/qpixmapdata_gl_p.h b/src/opengl/qpixmapdata_gl_p.h index 41740dd..8855c20 100644 --- a/src/opengl/qpixmapdata_gl_p.h +++ b/src/opengl/qpixmapdata_gl_p.h @@ -76,6 +76,10 @@ void qt_gl_unregister_pixmap(QGLPixmapData *pd); void qt_gl_hibernate_pixmaps(); #endif +#ifdef Q_OS_SYMBIAN +class QNativeImageHandleProvider; +#endif + class QGLFramebufferObjectPool { public: @@ -160,6 +164,9 @@ public: QImage::Format idealFormat(QImage &image, Qt::ImageConversionFlags flags); void* toNativeType(NativeType type); void fromNativeType(void* pixmap, NativeType type); + bool initFromNativeImageHandle(void *handle, const QString &type); + void createFromNativeImageHandleProvider(); + void releaseNativeImageHandle(); #endif private: @@ -191,6 +198,9 @@ private: mutable QGLContext *m_ctx; #ifdef Q_OS_SYMBIAN mutable QVolatileImage m_source; + mutable QNativeImageHandleProvider *nativeImageHandleProvider; + void *nativeImageHandle; + QString nativeImageType; #else mutable QImage m_source; #endif diff --git a/src/opengl/qpixmapdata_poolgl.cpp b/src/opengl/qpixmapdata_poolgl.cpp index 64de29e..44d9c84 100644 --- a/src/opengl/qpixmapdata_poolgl.cpp +++ b/src/opengl/qpixmapdata_poolgl.cpp @@ -49,6 +49,7 @@ #include <private/qgl_p.h> #include <private/qdrawhelper_p.h> #include <private/qimage_p.h> +#include <private/qnativeimagehandleprovider_p.h> #include <private/qpaintengineex_opengl2_p.h> @@ -254,6 +255,8 @@ QGLPixmapData::QGLPixmapData(PixelType type) , m_renderFbo(0) , m_engine(0) , m_ctx(0) + , nativeImageHandleProvider(0) + , nativeImageHandle(0) , m_dirty(false) , m_hasFillColor(false) , m_hasAlpha(false) @@ -292,6 +295,8 @@ void QGLPixmapData::destroyTexture() } m_texture.id = 0; inTexturePool = false; + + releaseNativeImageHandle(); } QPixmapData *QGLPixmapData::createCompatiblePixmapData() const @@ -342,6 +347,9 @@ void QGLPixmapData::ensureCreated() const m_dirty = false; + if (nativeImageHandleProvider && !nativeImageHandle) + const_cast<QGLPixmapData *>(this)->createFromNativeImageHandleProvider(); + QGLShareContextScope ctx(qt_gl_share_widget()->context()); m_ctx = ctx; @@ -860,9 +868,16 @@ void QGLPixmapData::detachTextureFromPool() void QGLPixmapData::hibernate() { - // If the texture was imported (e.g, from an SgImage under Symbian), - // then we cannot copy it back to main memory for storage. - if (m_texture.id && m_source.isNull()) + // If the image was imported (e.g, from an SgImage under Symbian), then + // skip the hibernation, there is no sense in copying it back to main + // memory because the data is most likely shared between several processes. + bool skipHibernate = (m_texture.id && m_source.isNull()); +#if defined(Q_OS_SYMBIAN) + // However we have to proceed normally if the image was retrieved via + // a handle provider. + skipHibernate &= !nativeImageHandleProvider; +#endif + if (skipHibernate) return; forceToImage(); diff --git a/src/openvg/qpixmapdata_vg.cpp b/src/openvg/qpixmapdata_vg.cpp index 3f67c79..80f5b2f 100644 --- a/src/openvg/qpixmapdata_vg.cpp +++ b/src/openvg/qpixmapdata_vg.cpp @@ -458,7 +458,7 @@ void QVGPixmapData::hibernate() if (skipHibernate) return; - forceToImage(); + forceToImage(false); // no readback allowed here destroyImageAndContext(); } @@ -502,12 +502,13 @@ int QVGPixmapData::metric(QPaintDevice::PaintDeviceMetric metric) const // Ensures that the pixmap is backed by some valid data and forces the data to // be re-uploaded to the VGImage when toVGImage() is called next time. -void QVGPixmapData::forceToImage() +void QVGPixmapData::forceToImage(bool allowReadback) { if (!isValid()) return; - ensureReadback(false); + if (allowReadback) + ensureReadback(false); if (source.isNull()) source = QVolatileImage(w, h, sourceFormat()); diff --git a/src/openvg/qpixmapdata_vg_p.h b/src/openvg/qpixmapdata_vg_p.h index 15ff889..c284596 100644 --- a/src/openvg/qpixmapdata_vg_p.h +++ b/src/openvg/qpixmapdata_vg_p.h @@ -188,7 +188,7 @@ protected: QString nativeImageType; #endif - void forceToImage(); + void forceToImage(bool allowReadback = true); QImage::Format sourceFormat() const; QImage::Format idealFormat(QImage *image, Qt::ImageConversionFlags flags) const; void updateSerial(); diff --git a/src/plugins/gfxdrivers/directfb/qdirectfbpaintengine.cpp b/src/plugins/gfxdrivers/directfb/qdirectfbpaintengine.cpp index dc74c4e..6d6fb02 100644 --- a/src/plugins/gfxdrivers/directfb/qdirectfbpaintengine.cpp +++ b/src/plugins/gfxdrivers/directfb/qdirectfbpaintengine.cpp @@ -1025,11 +1025,10 @@ void QDirectFBPaintEnginePrivate::setCompositionMode(QPainter::CompositionMode m case QPainter::CompositionMode_DestinationOut: surface->SetPorterDuff(surface, DSPD_DST_OUT); break; -#if (Q_DIRECTFB_VERSION >= 0x010209) case QPainter::CompositionMode_Destination: - surface->SetPorterDuff(surface, DSPD_DST); + surface->SetSrcBlendFunction(surface, DSBF_ZERO); + surface->SetDstBlendFunction(surface, DSBF_ONE); break; -#endif #if (Q_DIRECTFB_VERSION >= 0x010000) case QPainter::CompositionMode_SourceAtop: surface->SetPorterDuff(surface, DSPD_SRC_ATOP); diff --git a/src/plugins/graphicssystems/meego/qmeegographicssystem.cpp b/src/plugins/graphicssystems/meego/qmeegographicssystem.cpp index c904c3c..69a6922 100644 --- a/src/plugins/graphicssystems/meego/qmeegographicssystem.cpp +++ b/src/plugins/graphicssystems/meego/qmeegographicssystem.cpp @@ -170,7 +170,7 @@ bool QMeeGoGraphicsSystemSwitchHandler::eventFilter(QObject *object, QEvent *eve if (visibleWidgets() == 0) QMeeGoGraphicsSystem::switchToRaster(); } else { - if (visibleWidgets() == 1) + if (visibleWidgets() > 0) QMeeGoGraphicsSystem::switchToMeeGo(); } } diff --git a/src/plugins/graphicssystems/meego/qmeegolivepixmapdata.cpp b/src/plugins/graphicssystems/meego/qmeegolivepixmapdata.cpp index 0970b89..b6ba7ec 100644 --- a/src/plugins/graphicssystems/meego/qmeegolivepixmapdata.cpp +++ b/src/plugins/graphicssystems/meego/qmeegolivepixmapdata.cpp @@ -194,6 +194,8 @@ QImage* QMeeGoLivePixmapData::lock(EGLSyncKHR fenceSync) void *data = 0; int pitch = 0; + int surfaceWidth = 0; + int surfaceHeight = 0; EGLSurface surface = 0; QImage::Format format; lockedImage = QImage(); @@ -206,9 +208,11 @@ QImage* QMeeGoLivePixmapData::lock(EGLSyncKHR fenceSync) eglQuerySurface(QEgl::display(), surface, EGL_BITMAP_POINTER_KHR, (EGLint*) &data); eglQuerySurface(QEgl::display(), surface, EGL_BITMAP_PITCH_KHR, (EGLint*) &pitch); + eglQuerySurface(QEgl::display(), surface, EGL_WIDTH, (EGLint*) &surfaceWidth); + eglQuerySurface(QEgl::display(), surface, EGL_HEIGHT, (EGLint*) &surfaceHeight); // Ok, here we know we just support those two formats. Real solution would be: - // uqery also the format. + // query also the format. if (backingX11Pixmap->depth() > 16) format = QImage::Format_ARGB32_Premultiplied; else @@ -219,6 +223,12 @@ QImage* QMeeGoLivePixmapData::lock(EGLSyncKHR fenceSync) return &lockedImage; } + if (width() != surfaceWidth || height() != surfaceHeight) { + qWarning("Live texture dimensions don't match!"); + QMeeGoExtensions::eglUnlockSurfaceKHR(QEgl::display(), surface); + return &lockedImage; + } + lockedImage = QImage((uchar *) data, width(), height(), pitch, format); return &lockedImage; } diff --git a/src/qt3support/tools/q3asciidict.qdoc b/src/qt3support/tools/q3asciidict.qdoc index e744633..c276682 100644 --- a/src/qt3support/tools/q3asciidict.qdoc +++ b/src/qt3support/tools/q3asciidict.qdoc @@ -43,7 +43,7 @@ performace as a Q3AsciiDict. Example: - \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 0 + \snippet doc/src/snippets/code/doc_src_q3asciidict.cpp 0 In this example we use a dictionary to keep track of the line edits we're using. We insert each line edit into the dictionary with a unique name and then access the line edits via the @@ -164,7 +164,7 @@ \a item may not be 0. Equivalent to: - \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 1 + \snippet doc/src/snippets/code/doc_src_q3asciidict.cpp 1 If there are two or more items with equal keys, then the most recently inserted item will be replaced. @@ -295,7 +295,7 @@ iterator that operates on Q3AsciiDict\<X\> (dictionary of X*). Example: - \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 2 + \snippet doc/src/snippets/code/doc_src_q3asciidict.cpp 2 In the example we insert some line edits into a dictionary, then iterate over the dictionary printing the strings associated with those line edits. diff --git a/src/qt3support/tools/q3dict.qdoc b/src/qt3support/tools/q3dict.qdoc index 6b221f1..8fcbba4 100644 --- a/src/qt3support/tools/q3dict.qdoc +++ b/src/qt3support/tools/q3dict.qdoc @@ -192,7 +192,7 @@ \a item may not be 0. Equivalent to: - \snippet doc/src/snippets/code/doc_src_q3dict.qdoc 0 + \snippet doc/src/snippets/code/doc_src_q3dict.cpp 0 If there are two or more items with equal keys, then the last item that was inserted will be replaced. @@ -326,7 +326,7 @@ point to the next item in the (arbitrary) traversal order. Example: - \snippet doc/src/snippets/code/doc_src_q3dict.qdoc 1 + \snippet doc/src/snippets/code/doc_src_q3dict.cpp 1 In the example we insert some pointers to line edits into a dictionary, then iterate over the dictionary printing the strings associated with the line edits. diff --git a/src/qt3support/tools/q3intdict.qdoc b/src/qt3support/tools/q3intdict.qdoc index 684fc63..f108f30 100644 --- a/src/qt3support/tools/q3intdict.qdoc +++ b/src/qt3support/tools/q3intdict.qdoc @@ -39,7 +39,7 @@ pointer. Dictionaries provide very fast insertion and lookup. Example: - \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 0 + \snippet doc/src/snippets/code/doc_src_q3intdict.cpp 0 See Q3Dict for full details, including the choice of dictionary size, and how deletions are handled. @@ -145,7 +145,7 @@ \a item may not be 0. Equivalent to: - \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 1 + \snippet doc/src/snippets/code/doc_src_q3intdict.cpp 1 If there are two or more items with equal keys, then the most recently inserted item will be replaced. @@ -270,7 +270,7 @@ iterator that operates on Q3IntDict\<X\> (dictionary of X*). Example: - \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 2 + \snippet doc/src/snippets/code/doc_src_q3intdict.cpp 2 Note that the traversal order is arbitrary; you are not guaranteed the order shown above. diff --git a/src/qt3support/tools/q3memarray.qdoc b/src/qt3support/tools/q3memarray.qdoc index f05f433..5d6f9b2 100644 --- a/src/qt3support/tools/q3memarray.qdoc +++ b/src/qt3support/tools/q3memarray.qdoc @@ -51,7 +51,7 @@ and less copying of data. Example: - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 0 + \snippet doc/src/snippets/code/doc_src_q3memarray.cpp 0 Program output: \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 1 @@ -63,7 +63,7 @@ the remaining bytes will typically be uninitialized, this can cause find() etc. to fail to find the element. Example: - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 2 + \snippet doc/src/snippets/code/doc_src_q3memarray.cpp 2 To work around this, make sure that you use a struct where sizeof() returns the same as the sum of the sizes of the members @@ -352,10 +352,10 @@ allocating memory or copying data. Example I (intended use): - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 3 + \snippet doc/src/snippets/code/doc_src_q3memarray.cpp 3 Example II (you don't want to do this): - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 4 + \snippet doc/src/snippets/code/doc_src_q3memarray.cpp 4 \warning If you do not call resetRawData(), Q3MemArray will attempt to deallocate or reallocate the raw data, which might not be too diff --git a/src/qt3support/tools/q3ptrdict.qdoc b/src/qt3support/tools/q3ptrdict.qdoc index 8831a55..21dcdfd 100644 --- a/src/qt3support/tools/q3ptrdict.qdoc +++ b/src/qt3support/tools/q3ptrdict.qdoc @@ -39,7 +39,7 @@ pointer. Dictionaries provide very fast insertion and lookup. Example: - \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 0 + \snippet doc/src/snippets/code/doc_src_q3ptrdict.cpp 0 In this example we use a dictionary to add an extra property (a char*) to the line edits we're using. @@ -147,7 +147,7 @@ \a item may not be 0. Equivalent to - \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 1 + \snippet doc/src/snippets/code/doc_src_q3ptrdict.cpp 1 If there are two or more items with equal keys, then the most recently inserted item will be replaced. @@ -272,7 +272,7 @@ iterator that operates on Q3PtrDict\<X\> (dictionary of X*). Example: - \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 2 + \snippet doc/src/snippets/code/doc_src_q3ptrdict.cpp 2 In the example we insert some line edits into a dictionary, associating a string with each. We then iterate over the dictionary printing the associated strings. diff --git a/src/qt3support/tools/q3ptrlist.qdoc b/src/qt3support/tools/q3ptrlist.qdoc index 13e478e..e19d6bf 100644 --- a/src/qt3support/tools/q3ptrlist.qdoc +++ b/src/qt3support/tools/q3ptrlist.qdoc @@ -54,10 +54,10 @@ \target example Example: - \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 0 + \snippet doc/src/snippets/code/doc_src_q3ptrlist.cpp 0 The output is - \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 1 + \snippet doc/src/snippets/code/doc_src_q3ptrlist.cpp 1 Q3PtrList has several member functions for traversing the list, but using a Q3PtrListIterator can be more practical. Multiple list @@ -353,7 +353,7 @@ auto-deletion\endlink is enabled. Equivalent to: - \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 2 + \snippet doc/src/snippets/code/doc_src_q3ptrlist.cpp 2 The item after the removed item becomes the new current list item if the removed item is not the last item in the list. If the last @@ -785,10 +785,10 @@ but it uses Q3PtrListIterator. The class Employee is defined there. - \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 3 + \snippet doc/src/snippets/code/doc_src_q3ptrlist.cpp 3 The output is - \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 4 + \snippet doc/src/snippets/code/doc_src_q3ptrlist.cpp 4 Using a list iterator is a more robust way of traversing the list than using the Q3PtrList member functions \link Q3PtrList::first() diff --git a/src/qt3support/tools/q3valuelist.qdoc b/src/qt3support/tools/q3valuelist.qdoc index 99f1634..a5ebf60 100644 --- a/src/qt3support/tools/q3valuelist.qdoc +++ b/src/qt3support/tools/q3valuelist.qdoc @@ -71,7 +71,7 @@ prefer to use the STL-compatible functions. Example: - \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 0 + \snippet doc/src/snippets/code/doc_src_q3valuelist.cpp 0 Notice that the latest changes to Mary's salary did not affect the @@ -99,7 +99,7 @@ (your application will crash or do unpredictable things). Use last() and first() with caution, for example: - \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 1 + \snippet doc/src/snippets/code/doc_src_q3valuelist.cpp 1 Because Q3ValueList is value-based there is no need to be careful about deleting items in the list. The list holds its own copies @@ -352,7 +352,7 @@ Use the end() function instead. For example: - \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 2 + \snippet doc/src/snippets/code/doc_src_q3valuelist.cpp 2 */ @@ -364,7 +364,7 @@ Use the end() function instead. For example: - \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 3 + \snippet doc/src/snippets/code/doc_src_q3valuelist.cpp 3 */ @@ -443,7 +443,7 @@ iterator. Example (see Q3ValueList for the complete code): - \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 4 + \snippet doc/src/snippets/code/doc_src_q3valuelist.cpp 4 Q3ValueList is highly optimized for performance and memory usage. This means that you must be careful: Q3ValueList does not know diff --git a/src/qt3support/tools/q3valuestack.qdoc b/src/qt3support/tools/q3valuestack.qdoc index 4ad0d7d..6c2c57b 100644 --- a/src/qt3support/tools/q3valuestack.qdoc +++ b/src/qt3support/tools/q3valuestack.qdoc @@ -44,7 +44,7 @@ without removing it. Example: - \snippet doc/src/snippets/code/doc_src_q3valuestack.qdoc 0 + \snippet doc/src/snippets/code/doc_src_q3valuestack.cpp 0 Q3ValueStack is a specialized Q3ValueList provided for convenience. All of Q3ValueList's functionality also applies to Q3PtrStack, for diff --git a/src/qt3support/tools/q3valuevector.qdoc b/src/qt3support/tools/q3valuevector.qdoc index 58bd8e3..960bbac 100644 --- a/src/qt3support/tools/q3valuevector.qdoc +++ b/src/qt3support/tools/q3valuevector.qdoc @@ -70,10 +70,10 @@ objects it contains. Example: - \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 0 + \snippet doc/src/snippets/code/doc_src_q3valuevector.cpp 0 Program output: - \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 1 + \snippet doc/src/snippets/code/doc_src_q3valuevector.cpp 1 As you can see, the most recent change to Joe's salary did not affect the value in the vector because the vector created a copy @@ -102,13 +102,13 @@ an element that does not exist (your application will probably crash). For example: - \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 2 + \snippet doc/src/snippets/code/doc_src_q3valuevector.cpp 2 Whenever inserting, removing or referencing elements in a vector, always make sure you are referring to valid positions. For example: - \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 3 + \snippet doc/src/snippets/code/doc_src_q3valuevector.cpp 3 The iterators provided by vector are random access iterators, therefore you can use them with many generic algorithms, for @@ -127,7 +127,7 @@ application will crash or do unpredictable things). Use back() and front() with caution, for example: - \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 4 + \snippet doc/src/snippets/code/doc_src_q3valuevector.cpp 4 Because Q3ValueVector manages memory dynamically, it is recommended that you contruct a vector with an initial size. Inserting and diff --git a/src/s60installs/bwins/QtOpenVGu.def b/src/s60installs/bwins/QtOpenVGu.def index 18f576b..f2433d6 100644 --- a/src/s60installs/bwins/QtOpenVGu.def +++ b/src/s60installs/bwins/QtOpenVGu.def @@ -134,7 +134,7 @@ EXPORTS ?drawTextItem@QVGPaintEngine@@UAEXABVQPointF@@ABVQTextItem@@@Z @ 133 NONAME ; void QVGPaintEngine::drawTextItem(class QPointF const &, class QTextItem const &) ?clearScissor@QVGCompositionHelper@@QAEXXZ @ 134 NONAME ; void QVGCompositionHelper::clearScissor(void) ?fill@QVGPaintEngine@@UAEXABVQVectorPath@@ABVQBrush@@@Z @ 135 NONAME ; void QVGPaintEngine::fill(class QVectorPath const &, class QBrush const &) - ?forceToImage@QVGPixmapData@@IAEXXZ @ 136 NONAME ; void QVGPixmapData::forceToImage(void) + ?forceToImage@QVGPixmapData@@IAEXXZ @ 136 NONAME ABSENT ; void QVGPixmapData::forceToImage(void) ?drawPoints@QVGPaintEngine@@UAEXPBVQPoint@@H@Z @ 137 NONAME ; void QVGPaintEngine::drawPoints(class QPoint const *, int) ??_EQVGPaintEngine@@UAE@I@Z @ 138 NONAME ; QVGPaintEngine::~QVGPaintEngine(unsigned int) ?clip@QVGPaintEngine@@UAEXABVQPainterPath@@W4ClipOperation@Qt@@@Z @ 139 NONAME ; void QVGPaintEngine::clip(class QPainterPath const &, enum Qt::ClipOperation) @@ -183,4 +183,5 @@ EXPORTS ?initFromNativeImageHandle@QVGPixmapData@@QAE_NPAXABVQString@@@Z @ 182 NONAME ; bool QVGPixmapData::initFromNativeImageHandle(void *, class QString const &) ?createFromNativeImageHandleProvider@QVGPixmapData@@QAEXXZ @ 183 NONAME ; void QVGPixmapData::createFromNativeImageHandleProvider(void) ?releaseNativeImageHandle@QVGPixmapData@@QAEXXZ @ 184 NONAME ; void QVGPixmapData::releaseNativeImageHandle(void) + ?forceToImage@QVGPixmapData@@IAEX_N@Z @ 185 NONAME ; void QVGPixmapData::forceToImage(bool) diff --git a/src/s60installs/s60installs.pro b/src/s60installs/s60installs.pro index 1b5a5ce..02c3da0 100644 --- a/src/s60installs/s60installs.pro +++ b/src/s60installs/s60installs.pro @@ -42,7 +42,7 @@ symbian: { contains(S60_VERSION, 3.1)|contains(S60_VERSION, 3.2)|contains(S60_VERSION, 5.0) { qts60plugindeployment = \ - "IF package(0x20022E6D)" \ + "IF package(0x2003A678) OR package(0x20022E6D)" \ " \"$$pluginLocations/qts60plugin_5_0$${QT_LIBINFIX}.dll\" - \"c:\\sys\\bin\\qts60plugin_5_0$${QT_LIBINFIX}.dll\"" \ " \"$$bearerPluginLocation/qsymbianbearer$${QT_LIBINFIX}.dll\" - \"c:\\sys\\bin\\qsymbianbearer$${QT_LIBINFIX}.dll\"" \ "ELSEIF package(0x1028315F)" \ diff --git a/src/testlib/qsignalspy.qdoc b/src/testlib/qsignalspy.qdoc index 298b2b7..0c22868 100644 --- a/src/testlib/qsignalspy.qdoc +++ b/src/testlib/qsignalspy.qdoc @@ -38,7 +38,7 @@ The following example records all signal emissions for the \c clicked() signal of a QCheckBox: - \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qsignalspy.cpp 0 \c{spy.takeFirst()} returns the arguments for the first emitted signal, as a list of QVariant objects. The \c clicked() signal has a single bool argument, @@ -46,17 +46,17 @@ The example below catches a signal from a custom object: - \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qsignalspy.cpp 1 \bold {Note:} Non-standard data types need to be registered, using the qRegisterMetaType() function, before you can create a QSignalSpy. For example: - \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 2 + \snippet doc/src/snippets/code/doc_src_qsignalspy.cpp 2 To retrieve the \c QModelIndex, you can use qvariant_cast: - \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 3 + \snippet doc/src/snippets/code/doc_src_qsignalspy.cpp 3 */ /*! \fn QSignalSpy::QSignalSpy(QObject *object, const char *signal) @@ -65,7 +65,7 @@ from the QObject \a object. Neither \a signal nor \a object can be null. Example: - \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 4 + \snippet doc/src/snippets/code/doc_src_qsignalspy.cpp 4 */ /*! \fn QSignalSpy::isValid() const diff --git a/src/testlib/qtestevent.qdoc b/src/testlib/qtestevent.qdoc index 84e874b..4c695c2 100644 --- a/src/testlib/qtestevent.qdoc +++ b/src/testlib/qtestevent.qdoc @@ -39,7 +39,7 @@ QWidget. Example: - \snippet doc/src/snippets/code/doc_src_qtestevent.qdoc 0 + \snippet doc/src/snippets/code/doc_src_qtestevent.cpp 0 The example above simulates the user entering the character \c a followed by a backspace, waiting for 200 milliseconds and diff --git a/tests/auto/declarative/qdeclarativelanguage/tst_qdeclarativelanguage.cpp b/tests/auto/declarative/qdeclarativelanguage/tst_qdeclarativelanguage.cpp index 5a2591f..2ce493b 100644 --- a/tests/auto/declarative/qdeclarativelanguage/tst_qdeclarativelanguage.cpp +++ b/tests/auto/declarative/qdeclarativelanguage/tst_qdeclarativelanguage.cpp @@ -174,7 +174,7 @@ private: QVERIFY(component.errors().isEmpty()); \ } else { \ QFile file(QLatin1String(SRCDIR) + QLatin1String("/data/") + QLatin1String(errorfile)); \ - QVERIFY(file.open(QIODevice::ReadOnly)); \ + QVERIFY(file.open(QIODevice::ReadOnly | QIODevice::Text)); \ QByteArray data = file.readAll(); \ file.close(); \ QList<QByteArray> expected = data.split('\n'); \ diff --git a/tests/auto/declarative/qdeclarativemoduleplugin/tst_qdeclarativemoduleplugin.cpp b/tests/auto/declarative/qdeclarativemoduleplugin/tst_qdeclarativemoduleplugin.cpp index dc104e2..9d1c609 100644 --- a/tests/auto/declarative/qdeclarativemoduleplugin/tst_qdeclarativemoduleplugin.cpp +++ b/tests/auto/declarative/qdeclarativemoduleplugin/tst_qdeclarativemoduleplugin.cpp @@ -85,7 +85,7 @@ private slots: QVERIFY(component.errors().isEmpty()); \ } else { \ QFile file(QLatin1String("data/") + QLatin1String(errorfile)); \ - QVERIFY(file.open(QIODevice::ReadOnly)); \ + QVERIFY(file.open(QIODevice::ReadOnly | QIODevice::Text)); \ QByteArray data = file.readAll(); \ file.close(); \ QList<QByteArray> expected = data.split('\n'); \ diff --git a/tests/auto/declarative/qdeclarativetextedit/tst_qdeclarativetextedit.cpp b/tests/auto/declarative/qdeclarativetextedit/tst_qdeclarativetextedit.cpp index f62c2c5..04ecf91 100644 --- a/tests/auto/declarative/qdeclarativetextedit/tst_qdeclarativetextedit.cpp +++ b/tests/auto/declarative/qdeclarativetextedit/tst_qdeclarativetextedit.cpp @@ -1340,6 +1340,12 @@ void tst_qdeclarativetextedit::mouseSelection() else QVERIFY(str.isEmpty()); + // Clicking and shift to clicking between the same points should select the same text. + textEditObject->setCursorPosition(0); + QTest::mouseClick(canvas->viewport(), Qt::LeftButton, Qt::NoModifier, canvas->mapFromScene(QPoint(x1,y))); + QTest::mouseClick(canvas->viewport(), Qt::LeftButton, Qt::ShiftModifier, canvas->mapFromScene(QPoint(x2,y))); + QCOMPARE(textEditObject->selectedText(), str); + delete canvas; } @@ -1436,6 +1442,12 @@ void tst_qdeclarativetextedit::mouseSelectionMode() QVERIFY(str != text); } + // Clicking and shift to clicking between the same points should select the same text. + textEditObject->setCursorPosition(0); + QTest::mouseClick(canvas->viewport(), Qt::LeftButton, Qt::NoModifier, canvas->mapFromScene(QPoint(x1,y))); + QTest::mouseClick(canvas->viewport(), Qt::LeftButton, Qt::ShiftModifier, canvas->mapFromScene(QPoint(x2,y))); + QCOMPARE(textEditObject->selectedText(), str); + delete canvas; } diff --git a/tests/auto/declarative/qdeclarativetextinput/tst_qdeclarativetextinput.cpp b/tests/auto/declarative/qdeclarativetextinput/tst_qdeclarativetextinput.cpp index 45f38a4..a35a2c9 100644 --- a/tests/auto/declarative/qdeclarativetextinput/tst_qdeclarativetextinput.cpp +++ b/tests/auto/declarative/qdeclarativetextinput/tst_qdeclarativetextinput.cpp @@ -604,10 +604,8 @@ void tst_qdeclarativetextinput::moveCursorSelection_data() << standard[2] << 13 << 6 << QDeclarativeTextInput::SelectWords << 6 << 13 << false; QTest::newRow("Hello<(, world!)>|words") << standard[2] << 5 << 13 << QDeclarativeTextInput::SelectWords << 5 << 13 << true; - // Fails due to an issue with QTextBoundaryFinder and punctuation at the end of strings. - // QTBUG-11365 - // QTest::newRow("world<(!)>|words") - // << standard[2] << 12 << 13 << QDeclarativeTextInput::SelectWords << 12 << 13 << true; + QTest::newRow("world<(!)>|words") + << standard[2] << 12 << 13 << QDeclarativeTextInput::SelectWords << 12 << 13 << true; QTest::newRow("world!<()>)|words") << standard[2] << 13 << 13 << QDeclarativeTextInput::SelectWords << 13 << 13 << true; QTest::newRow("world<()>!)|words") @@ -653,16 +651,15 @@ void tst_qdeclarativetextinput::moveCursorSelection_data() QTest::newRow(" <s(pac)ey> text |words") << standard[4] << 1 << 4 << QDeclarativeTextInput::SelectWords << 1 << 7 << true; QTest::newRow(" spacey <t(ex)t> |words") - << standard[4] << 11 << 13 << QDeclarativeTextInput::SelectWords << 10 << 14 << false; // Should be reversible. QTBUG-11365 + << standard[4] << 11 << 13 << QDeclarativeTextInput::SelectWords << 10 << 14 << true; QTest::newRow("<( )>spacey text |words|ltr") << standard[4] << 0 << 1 << QDeclarativeTextInput::SelectWords << 0 << 1 << false; QTest::newRow("<( )spacey> text |words|rtl") << standard[4] << 1 << 0 << QDeclarativeTextInput::SelectWords << 0 << 7 << false; QTest::newRow("spacey <text( )>|words|ltr") << standard[4] << 14 << 15 << QDeclarativeTextInput::SelectWords << 10 << 15 << false; -// QTBUG-11365 -// QTest::newRow("spacey text<( )>|words|rtl") -// << standard[4] << 15 << 14 << QDeclarativeTextInput::SelectWords << 14 << 15 << false; + QTest::newRow("spacey text<( )>|words|rtl") + << standard[4] << 15 << 14 << QDeclarativeTextInput::SelectWords << 14 << 15 << false; QTest::newRow("<()> spacey text |words") << standard[4] << 0 << 0 << QDeclarativeTextInput::SelectWords << 0 << 0 << false; QTest::newRow(" spacey text <()>|words") @@ -857,23 +854,21 @@ void tst_qdeclarativetextinput::moveCursorSelectionSequence_data() << 15 << 12 << 15 << 10 << 15 << 15 << 15; -// QTBUG-11365 -// QTest::newRow(" spacey <te(xt{^ )>}|rtl") -// << standard[4] -// << 15 << 12 << 14 -// << 10 << 15 -// << 14 << 15; + QTest::newRow(" spacey <te(xt{^ )>}|rtl") + << standard[4] + << 15 << 12 << 14 + << 10 << 15 + << 14 << 15; QTest::newRow(" spacey {<te(x^t} )>|ltr") << standard[4] << 12 << 15 << 13 << 10 << 15 << 10 << 14; -// QTBUG-11365 -// QTest::newRow(" spacey {<te(xt^} )>|ltr") -// << standard[4] -// << 12 << 15 << 14 -// << 10 << 15 -// << 10 << 14; + QTest::newRow(" spacey {<te(xt^} )>|ltr") + << standard[4] + << 12 << 15 << 14 + << 10 << 15 + << 10 << 14; } void tst_qdeclarativetextinput::moveCursorSelectionSequence() diff --git a/tests/auto/qdir/qdir.pro b/tests/auto/qdir/qdir.pro index 472e646..384c048 100644 --- a/tests/auto/qdir/qdir.pro +++ b/tests/auto/qdir/qdir.pro @@ -4,7 +4,7 @@ RESOURCES += qdir.qrc QT = core wince*|symbian { - DirFiles.files = testdir testdata searchdir resources entrylist types tst_qdir.cpp + DirFiles.files = testdir testData searchdir resources entrylist types tst_qdir.cpp DirFiles.path = . DEPLOYMENT += DirFiles } diff --git a/tests/auto/qpainterpath/tst_qpainterpath.cpp b/tests/auto/qpainterpath/tst_qpainterpath.cpp index 86adabb..c2e64e0 100644 --- a/tests/auto/qpainterpath/tst_qpainterpath.cpp +++ b/tests/auto/qpainterpath/tst_qpainterpath.cpp @@ -426,6 +426,10 @@ void tst_QPainterPath::intersects_QRectF_data() QTest::newRow("horizontal line") << linePath(0, 0, 10, 0) << QRectF(1, -1, 2, 2) << true; QTest::newRow("vertical line") << linePath(0, 0, 0, 10) << QRectF(-1, 1, 2, 2) << true; + + path = QPainterPath(); + path.addEllipse(QRectF(-5000.0, -5000.0, 1500000.0, 1500000.0)); + QTest::newRow("huge ellipse, qreal=float crash") << path << QRectF(1100000.35, 1098000.2, 1500000.0, 1500000.0) << true; } void tst_QPainterPath::intersects_QRectF() diff --git a/tests/auto/qsoftkeymanager/tst_qsoftkeymanager.cpp b/tests/auto/qsoftkeymanager/tst_qsoftkeymanager.cpp index 910d437..bd19afb 100644 --- a/tests/auto/qsoftkeymanager/tst_qsoftkeymanager.cpp +++ b/tests/auto/qsoftkeymanager/tst_qsoftkeymanager.cpp @@ -179,8 +179,8 @@ void tst_QSoftKeyManager::handleCommand() // QTest::keyPress(&w, Qt::Key_Context1); // QTest::keyPress(&w, Qt::Key_Context2); - simulateSymbianCommand(6000); - simulateSymbianCommand(6001); + simulateSymbianCommand(s60CommandStart); //0 = LSK position + simulateSymbianCommand(s60CommandStart + 2); //2 = RSK position QApplication::processEvents(); @@ -205,28 +205,32 @@ void tst_QSoftKeyManager::checkSoftkeyEnableStates() w.show(); QApplication::processEvents(); - QSignalSpy spy0(w.actions()[0], SIGNAL(triggered())); //restore defaults action - QSignalSpy spy1(w.actions()[1], SIGNAL(triggered())); //disabled help action + //According to StandardButton enum in QDialogButtonBox the Help action + //is inserted before RestoreDefaults and thus help action is in index 0 + QSignalSpy spy0(w.actions()[0], SIGNAL(triggered())); //disabled help action + QSignalSpy spy1(w.actions()[1], SIGNAL(triggered())); //restore defaults action //Verify that enabled button gets all the action trigger signals and //disabled button gets none. for (int i = 0; i < 10; i++) { - //simulate "Restore Defaults" softkey press - simulateSymbianCommand(s60CommandStart); //simulate "help" softkey press - simulateSymbianCommand(s60CommandStart + 1); + simulateSymbianCommand(s60CommandStart); + //simulate "Restore Defaults" softkey press + simulateSymbianCommand(s60CommandStart + 2); } QApplication::processEvents(); - QCOMPARE(spy0.count(), 10); - QCOMPARE(spy1.count(), 0); + //Restore defaults button is enabled and its signals are recorded to spy1 + QCOMPARE(spy0.count(), 0); + QCOMPARE(spy1.count(), 10); + spy0.clear(); spy1.clear(); for (int i = 0; i < 10; i++) { - //simulate "Restore Defaults" softkey press - simulateSymbianCommand(s60CommandStart); //simulate "help" softkey press - simulateSymbianCommand(s60CommandStart + 1); + simulateSymbianCommand(s60CommandStart); + //simulate "Restore Defaults" softkey press + simulateSymbianCommand(s60CommandStart + 2); //switch enabled button to disabled and vice versa pBHelp->setEnabled(!pBHelp->isEnabled()); pBDefaults->setEnabled(!pBDefaults->isEnabled()); @@ -261,7 +265,7 @@ void tst_QSoftKeyManager::noMergingOverWindowBoundary() //Verify that both base softkeys emit triggered signals simulateSymbianCommand(s60CommandStart); - simulateSymbianCommand(s60CommandStart + 1); + simulateSymbianCommand(s60CommandStart + 2); QCOMPARE(baseLeftSpy.count(), 1); QCOMPARE(baseRightSpy.count(), 1); @@ -275,7 +279,7 @@ void tst_QSoftKeyManager::noMergingOverWindowBoundary() QApplication::processEvents(); simulateSymbianCommand(s60CommandStart); - simulateSymbianCommand(s60CommandStart + 1); + simulateSymbianCommand(s60CommandStart + 2); QCOMPARE(baseLeftSpy.count(), 0); QCOMPARE(baseRightSpy.count(), 0); @@ -291,7 +295,7 @@ void tst_QSoftKeyManager::noMergingOverWindowBoundary() QApplication::processEvents(); simulateSymbianCommand(s60CommandStart); - simulateSymbianCommand(s60CommandStart + 1); + simulateSymbianCommand(s60CommandStart + 2); QCOMPARE(baseLeftSpy.count(), 0); QCOMPARE(baseRightSpy.count(), 0); diff --git a/tests/auto/qsslcertificate/more-certificates/blacklisted1.pem b/tests/auto/qsslcertificate/more-certificates/blacklisted1.pem new file mode 100644 index 0000000..3945aea --- /dev/null +++ b/tests/auto/qsslcertificate/more-certificates/blacklisted1.pem @@ -0,0 +1,19 @@ +-----BEGIN CERTIFICATE----- +MIIDDzCCAnigAwIBAgIQBH7L6fylX3vQnq424QyuHjANBgkqhkiG9w0BAQUFADBf +MQswCQYDVQQGEwJBVTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50 +ZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMRgwFgYDVQQDEw9tYWlsLmdvb2dsZS5jb20w +HhcNMTEwMzI0MTMwNjI1WhcNMTEwNDIzMTMwNjI1WjBfMQswCQYDVQQGEwJBVTET +MBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50ZXJuZXQgV2lkZ2l0cyBQ +dHkgTHRkMRgwFgYDVQQDEw9tYWlsLmdvb2dsZS5jb20wgZ8wDQYJKoZIhvcNAQEB +BQADgY0AMIGJAoGBAOeAGV2FbGnT4rLjTvCNEEDjj0/iIUATa6RT8WKF2PVaOzbE +oceiODx6hTStvBnCgs+h/d3eVKgp+uAyBde5sW/HlOwHrNgKF3ZDvxegzIOEHaVI +ndNtBpFS3UyOEkO0NxfioBatNRYpeTRU/DVmazu3yvzgrV1V2mDsrNngVWxJAgMB +AAGjgcswgcgwHQYDVR0OBBYEFHcF1eqRpm7B78aY8ZjseN6zSYbvMIGYBgNVHSME +gZAwgY2AFHcF1eqRpm7B78aY8ZjseN6zSYbvoWOkYTBfMQswCQYDVQQGEwJBVTET +MBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50ZXJuZXQgV2lkZ2l0cyBQ +dHkgTHRkMRgwFgYDVQQDEw9tYWlsLmdvb2dsZS5jb22CEAR+y+n8pV970J6uNuEM +rh4wDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOBgQBEb1iF+EbhAJli5Sj2 ++iEdJ5xMP8R6FtgqAYknqXD8+tyEyXxJXdN186qdAWuTD9N22AUqi61BPWxUkufW +xH8FYMEHdFCkitvYE0321+GT5pJz6ON/d5Co+wusumt7T5oSjzj8Ax9V+nmo3Nkb +dSANM4/Lnc6moijcpJZq+GC1ng== +-----END CERTIFICATE----- diff --git a/tests/auto/qsslcertificate/more-certificates/blacklisted2.pem b/tests/auto/qsslcertificate/more-certificates/blacklisted2.pem new file mode 100644 index 0000000..4b8d059 --- /dev/null +++ b/tests/auto/qsslcertificate/more-certificates/blacklisted2.pem @@ -0,0 +1,19 @@ +-----BEGIN CERTIFICATE----- +MIIDDjCCAnegAwIBAgIRAPXIavNhYvE6ZPVPbclYfAYwDQYJKoZIhvcNAQEFBQAw +XjELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNVBAoTGElu +dGVybmV0IFdpZGdpdHMgUHR5IEx0ZDEXMBUGA1UEAxMOd3d3Lmdvb2dsZS5jb20w +HhcNMTEwMzI0MTMwNzExWhcNMTEwNDIzMTMwNzExWjBeMQswCQYDVQQGEwJBVTET +MBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50ZXJuZXQgV2lkZ2l0cyBQ +dHkgTHRkMRcwFQYDVQQDEw53d3cuZ29vZ2xlLmNvbTCBnzANBgkqhkiG9w0BAQEF +AAOBjQAwgYkCgYEAy1fNDFl65Njfcd1EUJeaxvyiKln+JKlqUmk1x4mrE1BQoa0C +QZaiXAF21rDhivWejZWBiEQ4IWbg3b12ANY74G1KqAfLC4BNKS9UP94hy18vezRA +pFc+m/HAClwc8AdACpl8eZpQW8cMgdvnMBMZTrQkgV0JYykX+uDD9Tb+QNUCAwEA +AaOByzCByDAdBgNVHQ4EFgQUSelG6IVRj2ZQbp049zkQ0X/Po9wwgZgGA1UdIwSB +kDCBjYAUSelG6IVRj2ZQbp049zkQ0X/Po9yhYqRgMF4xCzAJBgNVBAYTAkFVMRMw +EQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBXaWRnaXRzIFB0 +eSBMdGQxFzAVBgNVBAMTDnd3dy5nb29nbGUuY29tghEA9chq82Fi8Tpk9U9tyVh8 +BjAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUAA4GBALQyDC/AMQMNj2fa6E8L +umILCklWJwG1K1p/1bUAgm0CB8zm94n1xrh/ZK4+HS+k2a9OQmvLRbFyJn8Wua8p +3UU0267UNkCanA1FKHuO3Mo18wLvjMLWjjCQ4g1C9IvJx6P+8EFDQFG+MJBV/w2k +gJXXVl3q1T1dvahIgfav9QBL +-----END CERTIFICATE----- diff --git a/tests/auto/qsslcertificate/more-certificates/blacklisted3.pem b/tests/auto/qsslcertificate/more-certificates/blacklisted3.pem new file mode 100644 index 0000000..e47ece6 --- /dev/null +++ b/tests/auto/qsslcertificate/more-certificates/blacklisted3.pem @@ -0,0 +1,19 @@ +-----BEGIN CERTIFICATE----- +MIIDETCCAnqgAwIBAgIRANdVj9r18RBbshMoK3B3KaMwDQYJKoZIhvcNAQEFBQAw +XzELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNVBAoTGElu +dGVybmV0IFdpZGdpdHMgUHR5IEx0ZDEYMBYGA1UEAxMPbG9naW4ueWFob28uY29t +MB4XDTExMDMyNDEzMDg0MloXDTExMDQyMzEzMDg0MlowXzELMAkGA1UEBhMCQVUx +EzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNVBAoTGEludGVybmV0IFdpZGdpdHMg +UHR5IEx0ZDEYMBYGA1UEAxMPbG9naW4ueWFob28uY29tMIGfMA0GCSqGSIb3DQEB +AQUAA4GNADCBiQKBgQCosFLKRvGtxjvdAjWdEAHYycFTa4VtdpXmCNhNHf2xbeLn +xzde10KjEe44pQxNI+UUD1rJkyuH6wUfloyefn0D2Mu+MvusmvOEzFosa4EDbK9s +BAAlsSiyJgrp/GgbEPq/XOl4XJRBIVP1WC6LllduNbskFCipDqS+HQwifXmmwQID +AQABo4HMMIHJMB0GA1UdDgQWBBSEgWnsoYtd5GEx/MGJvKxuIuROJzCBmQYDVR0j +BIGRMIGOgBSEgWnsoYtd5GEx/MGJvKxuIuROJ6FjpGEwXzELMAkGA1UEBhMCQVUx +EzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNVBAoTGEludGVybmV0IFdpZGdpdHMg +UHR5IEx0ZDEYMBYGA1UEAxMPbG9naW4ueWFob28uY29tghEA11WP2vXxEFuyEygr +cHcpozAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUAA4GBAKNpIrzTOxIykKZt +EE6HU2nW1lrWUkIMjwjL8ntw7QI4JLMDN1ADVIxWaGTeQ+U/eXFou6dDNAYVAijK +ONDXgOItxW2YvSw0wOZsZj6INX2x88/0yRH+19TqaL/r+Y1D1h/0zefkHgfXufnY +Ex7BHju/rGBTp6R1mr+Tlh1tewva +-----END CERTIFICATE----- diff --git a/tests/auto/qsslcertificate/more-certificates/blacklisted4.pem b/tests/auto/qsslcertificate/more-certificates/blacklisted4.pem new file mode 100644 index 0000000..64c7d41 --- /dev/null +++ b/tests/auto/qsslcertificate/more-certificates/blacklisted4.pem @@ -0,0 +1,19 @@ +-----BEGIN CERTIFICATE----- +MIIDDzCCAnigAwIBAgIQOSpDTw4H3x+KowXeNODCKTANBgkqhkiG9w0BAQUFADBf +MQswCQYDVQQGEwJBVTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50 +ZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMRgwFgYDVQQDEw9sb2dpbi55YWhvby5jb20w +HhcNMTEwMzI0MTMwOTE1WhcNMTEwNDIzMTMwOTE1WjBfMQswCQYDVQQGEwJBVTET +MBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50ZXJuZXQgV2lkZ2l0cyBQ +dHkgTHRkMRgwFgYDVQQDEw9sb2dpbi55YWhvby5jb20wgZ8wDQYJKoZIhvcNAQEB +BQADgY0AMIGJAoGBANO2gz9x2H92xz5OvZSEul9gHxqqd+kdjeoS2exyvjC9wzqb +gYXqNmAsbtNp4WmieEQFd0riCAEkIAn8JpHTCsMHN4rHhS+W+4D5a/drI2jfnZEF +orNYJG1PHSQV/rvh6d7wkVdT+0SYOjrFTAA2biGWaK3W9ztf2yX577w+uQtBAgMB +AAGjgcswgcgwHQYDVR0OBBYEFJjDp8Prs7oReRmskIeFixp0vDkGMIGYBgNVHSME +gZAwgY2AFJjDp8Prs7oReRmskIeFixp0vDkGoWOkYTBfMQswCQYDVQQGEwJBVTET +MBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50ZXJuZXQgV2lkZ2l0cyBQ +dHkgTHRkMRgwFgYDVQQDEw9sb2dpbi55YWhvby5jb22CEDkqQ08OB98fiqMF3jTg +wikwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOBgQAZyo0Q3leeM1+lxeCd +Wp0ZYHMSW11ANc6nuMWOmJC+nIQGlyGiP3IqeUvIfekwboV638bahVPwcl2HYWsS +/l01Bgyd25Zn6VTQBfMK01dILyxscjVwdHuojzYBN05sl+qkVoqQr5EroQQbgDc9 +6I88p6Kjajv3IusCwfK6wlqISw== +-----END CERTIFICATE----- diff --git a/tests/auto/qsslcertificate/more-certificates/blacklisted5.pem b/tests/auto/qsslcertificate/more-certificates/blacklisted5.pem new file mode 100644 index 0000000..c7ddbf2 --- /dev/null +++ b/tests/auto/qsslcertificate/more-certificates/blacklisted5.pem @@ -0,0 +1,19 @@ +-----BEGIN CERTIFICATE----- +MIIDDzCCAnigAwIBAgIQPnXO1GtpMCEhiDCuhqgqcTANBgkqhkiG9w0BAQUFADBf +MQswCQYDVQQGEwJBVTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50 +ZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMRgwFgYDVQQDEw9sb2dpbi55YWhvby5jb20w +HhcNMTEwMzI0MTMwOTQ4WhcNMTEwNDIzMTMwOTQ4WjBfMQswCQYDVQQGEwJBVTET +MBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50ZXJuZXQgV2lkZ2l0cyBQ +dHkgTHRkMRgwFgYDVQQDEw9sb2dpbi55YWhvby5jb20wgZ8wDQYJKoZIhvcNAQEB +BQADgY0AMIGJAoGBALkiHG9TgTw/00CMW8D23NBDAa3331AL5kTkAaXbAWg2R/1o +yKQfXq3hgHbyWGPccUT+tU6FmaBf3bIndLK7iGx81RGzGgXeoQ5mpgnJ50iCeW73 +G99VlVwutPia7d9qqui84YdcG9t+P2Fuxv+xRqAB6lKOaa4qTPIbH50PgwOvAgMB +AAGjgcswgcgwHQYDVR0OBBYEFBWJrs8bnZ5fikfaLbTxK0ssj69MMIGYBgNVHSME +gZAwgY2AFBWJrs8bnZ5fikfaLbTxK0ssj69MoWOkYTBfMQswCQYDVQQGEwJBVTET +MBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50ZXJuZXQgV2lkZ2l0cyBQ +dHkgTHRkMRgwFgYDVQQDEw9sb2dpbi55YWhvby5jb22CED51ztRraTAhIYgwroao +KnEwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOBgQCIfqqs1a7RzdmV8U00 +v/xAsxscKvQvmu6BK+HwvY5iL2pSwXTYgRLJLoj5QGOd3mmgOFsyW3BPSCP1+fVE +M1ROhU2u8wHub+hGGds18Fx6F4yZjdh8pNUoOUR9A0Ym+VDJr2p50oUNTTy0RbH8 +9ns/gbemx84cjF9DD2G5stQhYg== +-----END CERTIFICATE----- diff --git a/tests/auto/qsslcertificate/more-certificates/blacklisted6.pem b/tests/auto/qsslcertificate/more-certificates/blacklisted6.pem new file mode 100644 index 0000000..bc2be2a --- /dev/null +++ b/tests/auto/qsslcertificate/more-certificates/blacklisted6.pem @@ -0,0 +1,19 @@ +-----BEGIN CERTIFICATE----- +MIIDETCCAnqgAwIBAgIRAOkCi5V45BXcGnEKK4gVREcwDQYJKoZIhvcNAQEFBQAw +XzELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNVBAoTGElu +dGVybmV0IFdpZGdpdHMgUHR5IEx0ZDEYMBYGA1UEAxMPbG9naW4uc2t5cGUuY29t +MB4XDTExMDMyNDEzMTAxNloXDTExMDQyMzEzMTAxNlowXzELMAkGA1UEBhMCQVUx +EzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNVBAoTGEludGVybmV0IFdpZGdpdHMg +UHR5IEx0ZDEYMBYGA1UEAxMPbG9naW4uc2t5cGUuY29tMIGfMA0GCSqGSIb3DQEB +AQUAA4GNADCBiQKBgQDFq06qqRl86pP7GRX3m7FMMSaSU6zlNGAo+WPoRfYAzB6x +5KpvlfxMCo3T/nWtInX3Bw9TBWCZSweQ2GEjggO0irjw5UX3MiToLxK+rwzWztm9 +H3LBxTWR0cOOa78kRFvNQ1onvNHbs8fJzXjG7b2IJDOIwG1HAT1LK80oPXZc1wID +AQABo4HMMIHJMB0GA1UdDgQWBBTiGNxw0ImW/wfW0mD3eA65PY5CAzCBmQYDVR0j +BIGRMIGOgBTiGNxw0ImW/wfW0mD3eA65PY5CA6FjpGEwXzELMAkGA1UEBhMCQVUx +EzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNVBAoTGEludGVybmV0IFdpZGdpdHMg +UHR5IEx0ZDEYMBYGA1UEAxMPbG9naW4uc2t5cGUuY29tghEA6QKLlXjkFdwacQor +iBVERzAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUAA4GBAHdb1QY/oxuro/4x +GX9jbm930ysoeXkWZSKVtVxoxrPIferu8jVpb1SLRjGcMnmjJoNWNFpvnbZgoYei +f3wdSWun7ndyQBh61k8eM7UABDOUXUHOsHuHj7s1koMKtet4gykmMfd6VxBkwBvN +ZXOll4X+TKe8nrxbnGUByIwQaRM+ +-----END CERTIFICATE----- diff --git a/tests/auto/qsslcertificate/more-certificates/blacklisted7.pem b/tests/auto/qsslcertificate/more-certificates/blacklisted7.pem new file mode 100644 index 0000000..19d4353 --- /dev/null +++ b/tests/auto/qsslcertificate/more-certificates/blacklisted7.pem @@ -0,0 +1,19 @@ +-----BEGIN CERTIFICATE----- +MIIDGjCCAoOgAwIBAgIRAJI51TSPQNFpWnRUcOHyP0MwDQYJKoZIhvcNAQEFBQAw +YjELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNVBAoTGElu +dGVybmV0IFdpZGdpdHMgUHR5IEx0ZDEbMBkGA1UEAxMSYWRkb25zLm1vemlsbGEu +b3JnMB4XDTExMDMyNDEzMTA0NFoXDTExMDQyMzEzMTA0NFowYjELMAkGA1UEBhMC +QVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNVBAoTGEludGVybmV0IFdpZGdp +dHMgUHR5IEx0ZDEbMBkGA1UEAxMSYWRkb25zLm1vemlsbGEub3JnMIGfMA0GCSqG +SIb3DQEBAQUAA4GNADCBiQKBgQC1lsoAcZTwF8Pf0E9do5avLdobB/O7EhhrCMs2 +/EMO07aIlrLwl3UP/Fmu/cAkKuX8Mx+Eif9x+XT3ZqGKGYKiqPTJcNfeZvgwbn0j +wXDtEo4DuURrwtBU9okS+v4dF6F4RtHQKAGcsXoOjhR7ah71kve+PG2GG0sJ167V +klK1xwIDAQABo4HPMIHMMB0GA1UdDgQWBBRgGDJ4Qp0WFyLIzm4Nz5wgqDSSxjCB +nAYDVR0jBIGUMIGRgBRgGDJ4Qp0WFyLIzm4Nz5wgqDSSxqFmpGQwYjELMAkGA1UE +BhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNVBAoTGEludGVybmV0IFdp +ZGdpdHMgUHR5IEx0ZDEbMBkGA1UEAxMSYWRkb25zLm1vemlsbGEub3JnghEAkjnV +NI9A0WladFRw4fI/QzAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUAA4GBACeE +DHMQ+LWEuoa/6z2EgrgM1k9rvBbUtCR+rjTuyzVW4OLXdpiVwZPOAiKphpq7q8Sb +TQ3zwsCoPLLJk5VolwcPfcD8Y2/tYK3NCYl+HzGxxnzPDFVaZM5Jh8RI861Hc00D +hVoQaptPK/V/lr0KEevqjhusAdFZbwlWA923zASa +-----END CERTIFICATE----- diff --git a/tests/auto/qsslcertificate/more-certificates/blacklisted8.pem b/tests/auto/qsslcertificate/more-certificates/blacklisted8.pem new file mode 100644 index 0000000..aedf3f7 --- /dev/null +++ b/tests/auto/qsslcertificate/more-certificates/blacklisted8.pem @@ -0,0 +1,19 @@ +-----BEGIN CERTIFICATE----- +MIIDDjCCAnegAwIBAgIRALC3Ez7Qlvm1b66RyHS9OsAwDQYJKoZIhvcNAQEFBQAw +XjELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNVBAoTGElu +dGVybmV0IFdpZGdpdHMgUHR5IEx0ZDEXMBUGA1UEAxMObG9naW4ubGl2ZS5jb20w +HhcNMTEwMzI0MTMxMTA2WhcNMTEwNDIzMTMxMTA2WjBeMQswCQYDVQQGEwJBVTET +MBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50ZXJuZXQgV2lkZ2l0cyBQ +dHkgTHRkMRcwFQYDVQQDEw5sb2dpbi5saXZlLmNvbTCBnzANBgkqhkiG9w0BAQEF +AAOBjQAwgYkCgYEA3OVNj9ijzMewvDeZYzgCWoKtyjclyIHxrQfHZpcexaKbxUap +1MtF6L0ayjtRWpiBYuPteUSy/Ja4Oh6zZz8K6z5rVgXhmy3xPIYuOoWaTKEOhb0Z +oHTBtGh8aWWai1XWw37HIm2FP8cmfgdH4lZwVvpTZIUxYidsyqyjB9IrhiMCAwEA +AaOByzCByDAdBgNVHQ4EFgQU4CcQcIvEhJC0tqHlNFMkv6MlDN4wgZgGA1UdIwSB +kDCBjYAU4CcQcIvEhJC0tqHlNFMkv6MlDN6hYqRgMF4xCzAJBgNVBAYTAkFVMRMw +EQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBXaWRnaXRzIFB0 +eSBMdGQxFzAVBgNVBAMTDmxvZ2luLmxpdmUuY29tghEAsLcTPtCW+bVvrpHIdL06 +wDAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUAA4GBAMNzIStXDNSNQ8ayxrcj +4RrUMsHWUG/6XPrgfYqCP5TfPGAa5qBfNb9LfUbiS4b0flJVN1RlHVwwRo0yf9v4 +LGg0dSuPQAOWlLeUR1GminO1jHZw7E4dYfR7QEmiiOgaQU+CbxLsf5vCaKInN9Gu +jv/5xytVCbMoLoZ4EBVb0tka +-----END CERTIFICATE----- diff --git a/tests/auto/qsslcertificate/more-certificates/blacklisted9.pem b/tests/auto/qsslcertificate/more-certificates/blacklisted9.pem new file mode 100644 index 0000000..d179b29 --- /dev/null +++ b/tests/auto/qsslcertificate/more-certificates/blacklisted9.pem @@ -0,0 +1,19 @@ +-----BEGIN CERTIFICATE----- +MIIDDjCCAnegAwIBAgIRANjzX063hystqwaS4xU4L7AwDQYJKoZIhvcNAQEFBQAw +XjELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNVBAoTGElu +dGVybmV0IFdpZGdpdHMgUHR5IEx0ZDEXMBUGA1UEAxMOZ2xvYmFsIHRydXN0ZWUw +HhcNMTEwMzI0MTMxMTM3WhcNMTEwNDIzMTMxMTM3WjBeMQswCQYDVQQGEwJBVTET +MBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50ZXJuZXQgV2lkZ2l0cyBQ +dHkgTHRkMRcwFQYDVQQDEw5nbG9iYWwgdHJ1c3RlZTCBnzANBgkqhkiG9w0BAQEF +AAOBjQAwgYkCgYEArHCVym7AEZDBhDkrUSG3Q94a+caNcCk5fE6ltZHiZHv096xr +cixHYvSGvms780bkI+oot2xI/e9awwkV+7VjWNvr0HrajzBWeimwk+myjP+3ddMY +Kmr0eI6bmvmPHtOFJE5Ar8/62FwD0wlLogRIx56JtXcCpkiUQktJVPz2gtMCAwEA +AaOByzCByDAdBgNVHQ4EFgQUUJwC/qSGBmcB+DVrd43ovRLdLmQwgZgGA1UdIwSB +kDCBjYAUUJwC/qSGBmcB+DVrd43ovRLdLmShYqRgMF4xCzAJBgNVBAYTAkFVMRMw +EQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBXaWRnaXRzIFB0 +eSBMdGQxFzAVBgNVBAMTDmdsb2JhbCB0cnVzdGVlghEA2PNfTreHKy2rBpLjFTgv +sDAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUAA4GBACAYxI+r3+JNelL6SBB0 +Pda3LkbCm+schP64NBYDdGl2Kus2b2QZ83T7xENBFEhyNoXvc6pRI4/Oh6JDxmG1 +7WmqOVStS/4JeAu6ygiyI1ImRKq2/MvJx/kaKh6IiXanB5nW1U+fhDV6kMOEfpwV +i6FBibpHboPQoqzPPRe7qHSL +-----END CERTIFICATE----- diff --git a/tests/auto/qsslcertificate/tst_qsslcertificate.cpp b/tests/auto/qsslcertificate/tst_qsslcertificate.cpp index 1e3a8dd..57f2fa8 100644 --- a/tests/auto/qsslcertificate/tst_qsslcertificate.cpp +++ b/tests/auto/qsslcertificate/tst_qsslcertificate.cpp @@ -111,6 +111,8 @@ private slots: void nulInSan(); void largeSerialNumber(); void largeExpirationDate(); + void blacklistedCertificates(); + // ### add tests for certificate bundles (multiple certificates concatenated into a single // structure); both PEM and DER formatted #endif @@ -817,6 +819,15 @@ void tst_QSslCertificate::largeExpirationDate() // QTBUG-12489 QCOMPARE(cert.expiryDate().toUTC(), QDateTime(QDate(2051, 8, 29), QTime(9, 53, 41), Qt::UTC)); } +void tst_QSslCertificate::blacklistedCertificates() +{ + QList<QSslCertificate> blacklistedCerts = QSslCertificate::fromPath("more-certificates/blacklisted*.pem", QSsl::Pem, QRegExp::Wildcard); + QVERIFY2(blacklistedCerts.count() > 0, "Please run this test from the source directory"); + for (int a = 0; a < blacklistedCerts.count(); a++) { + QVERIFY(! blacklistedCerts.at(a).isValid()); + } +} + #endif // QT_NO_OPENSSL QTEST_MAIN(tst_QSslCertificate) diff --git a/tests/auto/qsslsocket/certs/fake-login.live.com.key b/tests/auto/qsslsocket/certs/fake-login.live.com.key new file mode 100644 index 0000000..692a7bd --- /dev/null +++ b/tests/auto/qsslsocket/certs/fake-login.live.com.key @@ -0,0 +1,15 @@ +-----BEGIN RSA PRIVATE KEY----- +MIICXQIBAAKBgQDOtxdvMa0VHUQYG5q7Tsi1Jj4qKEJppyZEkmuRXOi0fDbd1SwE +bwHrLGMvDO6OMrYBbq3WDNrtnIfF9CvzUOEch+gjr4hEVQqecU5fb45Wor7yNel3 +/C/gxfbzuXHrsj/gUjNghL2i10+c2NW+hUo/sWO6OusaBT6d6s7ee+YBcQIDAQAB +AoGAb8cVhu0HuLkgjyCuJMbPRRUu3ED02Iin6sB6JhplQuNAD+grayJTmUVhRJnr +jTziqhedLHe7Em1oBaSo92MutfMpXvWiccSlbNygI61VgmrJpVB+qIN5H9cQc9ql +Zymc+nIPa1+i5rsrOzlpUytTh7AsbZ27QG4tQXR/kQejEiECQQD6BgTxBeT8D7x9 +DuukoBaSCkLwx7U7P1NXx15EI3lA1nO51t6UHfvk/jGPp8Sl4wv4alJ7AQxr5uQ/ +vC3kzA/1AkEA06gNu10se8pe3n8qL2RRt+FmVjHkQdD9Mm2Dx9oWCs2A4wOSOrlo +6/nKYF1CaQNYn9HgsNbHVEUpnICVO18qDQJBALEw/uOJ1+TDikPfBSWgxx4s45Ad +GNWqZXh6NNZ5hX9r/IwiOZAjR9fcRmeW8IjYRi2BvH6sGY+HDRAWXzgdXtkCQCma +dOiJTf8fLjqp4E7kdzOfuI/kyqstOze4Uxjrgz2oW1dEEnA8laUcumzqp+0gXUE8 +7d+UuCWWWrGKjMrYz9kCQQDh5E5+b6Djn082Jo6gvyuXWC5eXju6IdmihlJ2SMzD +s2y3IDjOUtTeQQRDymLneteMz0ha79KeUp6VnAvZCOVe +-----END RSA PRIVATE KEY----- diff --git a/tests/auto/qsslsocket/certs/fake-login.live.com.pem b/tests/auto/qsslsocket/certs/fake-login.live.com.pem new file mode 100644 index 0000000..429f951 --- /dev/null +++ b/tests/auto/qsslsocket/certs/fake-login.live.com.pem @@ -0,0 +1,19 @@ +-----BEGIN CERTIFICATE----- +MIIDDjCCAnegAwIBAgIRALC3Ez7Qlvm1b66RyHS9OsAwDQYJKoZIhvcNAQEFBQAw +XjELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNVBAoTGElu +dGVybmV0IFdpZGdpdHMgUHR5IEx0ZDEXMBUGA1UEAxMObG9naW4ubGl2ZS5jb20w +HhcNMTEwMzI1MTMyODUwWhcNMTEwNDI0MTMyODUwWjBeMQswCQYDVQQGEwJBVTET +MBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50ZXJuZXQgV2lkZ2l0cyBQ +dHkgTHRkMRcwFQYDVQQDEw5sb2dpbi5saXZlLmNvbTCBnzANBgkqhkiG9w0BAQEF +AAOBjQAwgYkCgYEAzrcXbzGtFR1EGBuau07ItSY+KihCaacmRJJrkVzotHw23dUs +BG8B6yxjLwzujjK2AW6t1gza7ZyHxfQr81DhHIfoI6+IRFUKnnFOX2+OVqK+8jXp +d/wv4MX287lx67I/4FIzYIS9otdPnNjVvoVKP7FjujrrGgU+nerO3nvmAXECAwEA +AaOByzCByDAdBgNVHQ4EFgQUpSOEcmtkQITvBdM2IDfcXnJ0FCAwgZgGA1UdIwSB +kDCBjYAUpSOEcmtkQITvBdM2IDfcXnJ0FCChYqRgMF4xCzAJBgNVBAYTAkFVMRMw +EQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBXaWRnaXRzIFB0 +eSBMdGQxFzAVBgNVBAMTDmxvZ2luLmxpdmUuY29tghEAsLcTPtCW+bVvrpHIdL06 +wDAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUAA4GBAD+2HT4GSHHKCdbl9VkX +zsl+D+drMm2b0ksxz9SgPihP7aW50EEIJDEEihNMTa27mhpeOXHc/sLqDi4ECUao +/0Ns/5uoVuAIrAKCydmtPsonVFh9XWjyrfUzPOHAc9p2bmJ1i9a3kTsLB6jlrVDO +VufGzsowHlHZ0TtKf5omojU5 +-----END CERTIFICATE----- diff --git a/tests/auto/qsslsocket/tst_qsslsocket.cpp b/tests/auto/qsslsocket/tst_qsslsocket.cpp index ef5833ef..ccfe0f3 100644 --- a/tests/auto/qsslsocket/tst_qsslsocket.cpp +++ b/tests/auto/qsslsocket/tst_qsslsocket.cpp @@ -185,6 +185,7 @@ private slots: void ignoreSslErrorsListWithSlot(); void readFromClosedSocket(); void writeBigChunk(); + void blacklist(); void setEmptyDefaultConfiguration(); static void exitLoop() @@ -857,9 +858,16 @@ class SslServer : public QTcpServer { Q_OBJECT public: - SslServer() : socket(0), protocol(QSsl::TlsV1) { } + SslServer(const QString &keyFile = SRCDIR "certs/fluke.key", const QString &certFile = SRCDIR "certs/fluke.cert") + : socket(0), + protocol(QSsl::TlsV1), + m_keyFile(keyFile), + m_certFile(certFile) { } QSslSocket *socket; QSsl::SslProtocol protocol; + QString m_keyFile; + QString m_certFile; + protected: void incomingConnection(int socketDescriptor) { @@ -867,13 +875,13 @@ protected: socket->setProtocol(protocol); connect(socket, SIGNAL(sslErrors(const QList<QSslError> &)), this, SLOT(ignoreErrorSlot())); - QFile file(SRCDIR "certs/fluke.key"); + QFile file(m_keyFile); QVERIFY(file.open(QIODevice::ReadOnly)); QSslKey key(file.readAll(), QSsl::Rsa, QSsl::Pem, QSsl::PrivateKey); QVERIFY(!key.isNull()); socket->setPrivateKey(key); - QList<QSslCertificate> localCert = QSslCertificate::fromPath(SRCDIR "certs/fluke.cert"); + QList<QSslCertificate> localCert = QSslCertificate::fromPath(m_certFile); QVERIFY(!localCert.isEmpty()); QVERIFY(localCert.first().handle()); socket->setLocalCertificate(localCert.first()); @@ -1937,6 +1945,37 @@ void tst_QSslSocket::writeBigChunk() socket->close(); } +void tst_QSslSocket::blacklist() +{ + QFETCH_GLOBAL(bool, setProxy); + if (setProxy) + return; + + SslServer server(SRCDIR "certs/fake-login.live.com.key", SRCDIR "certs/fake-login.live.com.pem"); + QSslSocket *receiver = new QSslSocket(this); + connect(receiver, SIGNAL(readyRead()), SLOT(exitLoop())); + + // connect two sockets to each other: + QVERIFY(server.listen(QHostAddress::LocalHost)); + receiver->connectToHost("127.0.0.1", server.serverPort()); + QVERIFY(receiver->waitForConnected(5000)); + QVERIFY(server.waitForNewConnection(0)); + + QSslSocket *sender = server.socket; + QVERIFY(sender); + QVERIFY(sender->state() == QAbstractSocket::ConnectedState); + receiver->setObjectName("receiver"); + sender->setObjectName("sender"); + receiver->ignoreSslErrors(); + receiver->startClientEncryption(); + + connect(receiver, SIGNAL(error(QAbstractSocket::SocketError)), SLOT(exitLoop())); + connect(receiver, SIGNAL(encrypted()), SLOT(exitLoop())); + enterLoop(1); + QCOMPARE(receiver->error(), QAbstractSocket::SslHandshakeFailedError); + QCOMPARE(receiver->errorString(), QString("The peer certificate is blacklisted")); +} + void tst_QSslSocket::setEmptyDefaultConfiguration() { // used to produce a crash in QSslConfigurationPrivate::deepCopyDefaultConfiguration, QTBUG-13265 diff --git a/tests/auto/qtextboundaryfinder/tst_qtextboundaryfinder.cpp b/tests/auto/qtextboundaryfinder/tst_qtextboundaryfinder.cpp index 6157004..8003c44 100644 --- a/tests/auto/qtextboundaryfinder/tst_qtextboundaryfinder.cpp +++ b/tests/auto/qtextboundaryfinder/tst_qtextboundaryfinder.cpp @@ -257,10 +257,10 @@ void tst_QTextBoundaryFinder::sentenceBoundaries() void tst_QTextBoundaryFinder::isAtWordStart() { - QString txt("The quick brown fox jumped over $the lazy. dog "); + QString txt("The quick brown fox jumped over $the lazy. dog I win!"); QList<int> start, end; - start << 0 << 4 << 10 << 16 << 20 << 27 << 32 << 33 << 37 << 41 << 43; - end << 3 << 9 << 15 << 19 << 26 << 31 << 33 << 36 << 41 << 42 << 46; + start << 0 << 4 << 10 << 16 << 20 << 27 << 32 << 33 << 37 << 41 << 43 << 48 << 50 << 53; + end << 3 << 9 << 15 << 19 << 26 << 31 << 33 << 36 << 41 << 42 << 46 << 49 << 53 << 54; QTextBoundaryFinder finder(QTextBoundaryFinder::Word, txt); for(int i=0; i < txt.length(); ++i) { finder.setPosition(i); diff --git a/tests/auto/qtextlayout/tst_qtextlayout.cpp b/tests/auto/qtextlayout/tst_qtextlayout.cpp index 83c7094..9f79420 100644 --- a/tests/auto/qtextlayout/tst_qtextlayout.cpp +++ b/tests/auto/qtextlayout/tst_qtextlayout.cpp @@ -127,6 +127,7 @@ private slots: void textWithSurrogates_qtbug15679(); void textWidthWithStackedTextEngine(); void textWidthWithLineSeparator(); + void textWithSurrogates_qtbug15679(); private: QFont testFont; @@ -1460,5 +1461,24 @@ void tst_QTextLayout::textWidthWithLineSeparator() QCOMPARE(line1.naturalTextWidth(), line2.naturalTextWidth()); } +void tst_QTextLayout::textWithSurrogates_qtbug15679() +{ + QString str = QString::fromUtf8("🀀a🀀"); + QTextLayout layout(str); + layout.beginLayout(); + QTextLine line = layout.createLine(); + layout.endLayout(); + + qreal x[6]; + for (int i = 0; i < 6; i++) + x[i] = line.cursorToX(i); + + // If the first and third character are using the same + // font, they must have the same advance (since they + // are surrogate pairs, we need to add two for each + // character) + QCOMPARE(x[2] - x[0], x[5] - x[3]); +} + QTEST_MAIN(tst_QTextLayout) #include "tst_qtextlayout.moc" diff --git a/tools/designer/src/lib/sdk/membersheet.qdoc b/tools/designer/src/lib/sdk/membersheet.qdoc index fdd13f2..57a3664 100644 --- a/tools/designer/src/lib/sdk/membersheet.qdoc +++ b/tools/designer/src/lib/sdk/membersheet.qdoc @@ -40,7 +40,7 @@ manipulate the member functions' appearance in \QD's signals and slots editing mode. For example: - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 2 + \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 2 When implementing a custom widget plugin, a pointer to \QD's current QDesignerFormEditorInterface object (\c formEditor in the @@ -69,7 +69,7 @@ made known to the meta object system using the Q_INTERFACES() macro: - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 3 + \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 3 This enables \QD to use qobject_cast() to query for supported interfaces using nothing but a QObject pointer. @@ -101,13 +101,13 @@ QExtensionFactory and reimplement the QExtensionFactory::createExtension() function. For example: - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 4 + \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 4 Or you can use an existing factory, expanding the QExtensionFactory::createExtension() function to make the factory able to create a member sheet extension as well. For example: - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 5 + \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 5 For a complete example using an extension class, see \l {designer/taskmenuextension}{Task Menu Extension example}. The diff --git a/tools/designer/src/lib/sdk/propertysheet.qdoc b/tools/designer/src/lib/sdk/propertysheet.qdoc index d82de88..becc74b 100644 --- a/tools/designer/src/lib/sdk/propertysheet.qdoc +++ b/tools/designer/src/lib/sdk/propertysheet.qdoc @@ -41,7 +41,7 @@ manipulate the properties' appearance in the property editor. For example: - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 15 + \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 15 Note that if you change the value of a property using the QDesignerPropertySheetExtension::setProperty() function, the undo @@ -80,7 +80,7 @@ an interface, we must ensure that it's made known to the meta object system using the Q_INTERFACES() macro: - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 16 + \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 16 This enables \QD to use qobject_cast() to query for supported interfaces using nothing but a QObject pointer. @@ -112,14 +112,14 @@ reimplement the QExtensionFactory::createExtension() function. For example: - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 17 + \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 17 Or you can use an existing factory, expanding the QExtensionFactory::createExtension() function to make the factory able to create a property sheet extension extension as well. For example: - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 18 + \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 18 For a complete example using an extension class, see the \l {designer/taskmenuextension}{Task Menu Extension example}. The diff --git a/tools/designer/src/lib/sdk/taskmenu.qdoc b/tools/designer/src/lib/sdk/taskmenu.qdoc index 06d0b96..c5a3795 100644 --- a/tools/designer/src/lib/sdk/taskmenu.qdoc +++ b/tools/designer/src/lib/sdk/taskmenu.qdoc @@ -51,7 +51,7 @@ inherit from both QObject and QDesignerTaskMenuExtension. For example: - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 9 + \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 9 Since we are implementing an interface, we must ensure that it is made known to the meta-object system using the Q_INTERFACES() @@ -94,13 +94,13 @@ reimplement the QExtensionFactory::createExtension() function. For example: - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 10 + \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 10 Or you can use an existing factory, expanding the QExtensionFactory::createExtension() function to make the factory able to create a task menu extension as well. For example: - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 11 + \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 11 For a complete example using the QDesignerTaskMenuExtension class, see the \l {designer/taskmenuextension}{Task Menu Extension diff --git a/tools/designer/src/lib/uilib/container.qdoc b/tools/designer/src/lib/uilib/container.qdoc index 51d942e..d931051 100644 --- a/tools/designer/src/lib/uilib/container.qdoc +++ b/tools/designer/src/lib/uilib/container.qdoc @@ -44,7 +44,7 @@ To create a container extension, your extension class must inherit from both QObject and QDesignerContainerExtension. For example: - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 6 + \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 6 Since we are implementing an interface, we must ensure that it's made known to the meta object system using the Q_INTERFACES() @@ -88,13 +88,13 @@ reimplement the QExtensionFactory::createExtension() function. For example: - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 7 + \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 7 Or you can use an existing factory, expanding the QExtensionFactory::createExtension() function to make the factory able to create a container extension as well. For example: - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 8 + \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 8 For a complete example using the QDesignerContainerExtension class, see the \l {designer/containerextension}{Container diff --git a/tools/designer/src/lib/uilib/customwidget.qdoc b/tools/designer/src/lib/uilib/customwidget.qdoc index 3410fc6..d5ddaa7 100644 --- a/tools/designer/src/lib/uilib/customwidget.qdoc +++ b/tools/designer/src/lib/uilib/customwidget.qdoc @@ -73,7 +73,7 @@ class called \c MyCustomWidget, we can export it by adding the following line to the file containing the plugin implementation: - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 14 + \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 14 This macro ensures that \QD can access and construct the custom widget. Without this macro, there is no way for \QD to use it. @@ -264,13 +264,13 @@ several custom widgets \c CustomWidgetOne, \c CustomWidgetTwo and \c CustomWidgetThree, the class definition may look like this: - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 12 + \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 12 In the class constructor you add the interfaces to your custom widgets to the list which you return in the customWidgets() function: - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 13 + \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 13 Note that instead of exporting each custom widget plugin using the Q_EXPORT_PLUGIN2() macro, you export the entire collection. The diff --git a/tools/qdoc3/atom.cpp b/tools/qdoc3/atom.cpp index fb473c7..2d50e5a 100644 --- a/tools/qdoc3/atom.cpp +++ b/tools/qdoc3/atom.cpp @@ -51,6 +51,7 @@ QString Atom::INDEX_ ("index"); QString Atom::ITALIC_ ("italic"); QString Atom::LINK_ ("link"); QString Atom::PARAMETER_ ("parameter"); +QString Atom::SPAN_ ("span"); QString Atom::SUBSCRIPT_ ("subscript"); QString Atom::SUPERSCRIPT_ ("superscript"); QString Atom::TELETYPE_ ("teletype"); @@ -107,7 +108,8 @@ QString Atom::UPPERROMAN_ ("upperroman"); \value CodeOld \value CodeQuoteArgument \value CodeQuoteCommand - \value Div + \value DivLeft + \value DivRight \value EndQmlText \value FormatElse \value FormatEndif @@ -180,8 +182,8 @@ static const struct { { "CodeOld", Atom::CodeOld }, { "CodeQuoteArgument", Atom::CodeQuoteArgument }, { "CodeQuoteCommand", Atom::CodeQuoteCommand }, - { "Div", Atom::Div }, - { "EndDiv", Atom::EndDiv }, + { "DivLeft", Atom::DivLeft }, + { "DivRight", Atom::DivRight }, #ifdef QDOC_QML { "EndQmlText", Atom::EndQmlText }, #endif diff --git a/tools/qdoc3/atom.h b/tools/qdoc3/atom.h index e3b993e..dbb1a8b 100644 --- a/tools/qdoc3/atom.h +++ b/tools/qdoc3/atom.h @@ -46,7 +46,7 @@ #ifndef ATOM_H #define ATOM_H -#include <qstring.h> +#include <qstringlist.h> #define QDOC_QML @@ -72,9 +72,9 @@ class Atom CodeOld, CodeQuoteArgument, CodeQuoteCommand, - Div, + DivLeft, // 16 + DivRight, // 17 #ifdef QDOC_QML - EndDiv, EndQmlText, #endif FootnoteLeft, @@ -101,10 +101,10 @@ class Atom ListLeft, ListItemNumber, ListTagLeft, // 40 - ListTagRight, // 41 - ListItemLeft, // 42 - ListItemRight, // 43 - ListRight, // 44 + ListTagRight, + ListItemLeft, + ListItemRight, + ListRight, Nop, ParaLeft, ParaRight, @@ -115,7 +115,7 @@ class Atom QuotationLeft, // 50 QuotationRight, RawString, - SectionLeft, // 53 + SectionLeft, SectionRight, SectionHeadingLeft, SectionHeadingRight, @@ -125,8 +125,8 @@ class Atom SnippetCommand, // 60 SnippetIdentifier, SnippetLocation, - String, // 63 - TableLeft, // 64 + String, + TableLeft, TableRight, TableHeaderLeft, TableHeaderRight, @@ -135,30 +135,57 @@ class Atom TableItemLeft, // 70 TableItemRight, TableOfContents, - Target, // 73 + Target, UnhandledFormat, UnknownCommand, Last = UnknownCommand }; - Atom(Type type, const QString &string = "") - : nxt(0), typ(type), str(string) { } - Atom(Atom *prev, Type type, const QString &string = "") - : nxt(prev->nxt), typ(type), str(string) { prev->nxt = this; } - - void appendChar(QChar ch) { str += ch; } - void appendString(const QString& string) { str += string; } - void chopString() { str.chop(1); } - void setString(const QString &string) { str = string; } - Atom *next() { return nxt; } - void setNext(Atom *newNext) { nxt = newNext; } - - const Atom *next() const { return nxt; } - const Atom *next(Type t) const; - const Atom *next(Type t, const QString& s) const; + Atom(Type type, const QString& string = "") + : nxt(0), typ(type) + { + strs << string; + } + + Atom(Type type, const QString& p1, const QString& p2) + : nxt(0), typ(type) + { + strs << p1; + if (!p2.isEmpty()) + strs << p2; + } + + Atom(Atom* prev, Type type, const QString& string = "") + : nxt(prev->nxt), typ(type) + { + strs << string; + prev->nxt = this; + } + + Atom(Atom* prev, Type type, const QString& p1, const QString& p2) + : nxt(prev->nxt), typ(type) + { + strs << p1; + if (!p2.isEmpty()) + strs << p2; + prev->nxt = this; + } + + void appendChar(QChar ch) { strs[0] += ch; } + void appendString(const QString& string) { strs[0] += string; } + void chopString() { strs[0].chop(1); } + void setString(const QString& string) { strs[0] = string; } + Atom* next() { return nxt; } + void setNext(Atom* newNext) { nxt = newNext; } + + const Atom* next() const { return nxt; } + const Atom* next(Type t) const; + const Atom* next(Type t, const QString& s) const; Type type() const { return typ; } QString typeString() const; - const QString& string() const { return str; } + const QString& string() const { return strs[0]; } + const QString& string(int i) const { return strs[i]; } + int count() const { return strs.size(); } void dump() const; static QString BOLD_; @@ -166,6 +193,7 @@ class Atom static QString ITALIC_; static QString LINK_; static QString PARAMETER_; + static QString SPAN_; static QString SUBSCRIPT_; static QString SUPERSCRIPT_; static QString TELETYPE_; @@ -181,9 +209,9 @@ class Atom static QString UPPERROMAN_; private: - Atom *nxt; + Atom* nxt; Type typ; - QString str; + QStringList strs; }; #define ATOM_FORMATTING_BOLD "bold" @@ -191,6 +219,7 @@ class Atom #define ATOM_FORMATTING_ITALIC "italic" #define ATOM_FORMATTING_LINK "link" #define ATOM_FORMATTING_PARAMETER "parameter" +#define ATOM_FORMATTING_SPAN "span " #define ATOM_FORMATTING_SUBSCRIPT "subscript" #define ATOM_FORMATTING_SUPERSCRIPT "superscript" #define ATOM_FORMATTING_TELETYPE "teletype" diff --git a/tools/qdoc3/cppcodeparser.cpp b/tools/qdoc3/cppcodeparser.cpp index 3979176..595756a 100644 --- a/tools/qdoc3/cppcodeparser.cpp +++ b/tools/qdoc3/cppcodeparser.cpp @@ -863,10 +863,12 @@ Node *CppCodeParser::processTopicCommandGroup(const Doc& doc, } if (qmlPropGroup) { const ClassNode *correspondingClass = static_cast<const QmlClassNode*>(qmlPropGroup->parent())->classNode(); - PropertyNode *correspondingProperty = 0; - if (correspondingClass) - correspondingProperty = static_cast<PropertyNode*>((Node*)correspondingClass->findNode(property, Node::Property)); QmlPropertyNode *qmlPropNode = new QmlPropertyNode(qmlPropGroup,property,type,attached); + + const PropertyNode *correspondingProperty = 0; + if (correspondingClass) { + correspondingProperty = qmlPropNode->correspondingProperty(tre); + } if (correspondingProperty) { bool writableList = type.startsWith("list") && correspondingProperty->dataType().endsWith('*'); qmlPropNode->setWritable(writableList || correspondingProperty->isWritable()); @@ -1829,7 +1831,7 @@ bool CppCodeParser::matchProperty(InnerNode *parent) QString key = previousLexeme(); QString value; - if (match(Tok_Ident)) { + if (match(Tok_Ident) || match(Tok_Number)) { value = previousLexeme(); } else if (match(Tok_LeftParen)) { @@ -1872,8 +1874,15 @@ bool CppCodeParser::matchProperty(InnerNode *parent) tre->addPropertyFunction(property, value, PropertyNode::Resetter); else if (key == "NOTIFY") { tre->addPropertyFunction(property, value, PropertyNode::Notifier); - } - else if (key == "SCRIPTABLE") { + } else if (key == "REVISION") { + int revision; + bool ok; + revision = value.toInt(&ok); + if (ok) + property->setRevision(revision); + else + parent->doc().location().warning(tr("Invalid revision number: %1").arg(value)); + } else if (key == "SCRIPTABLE") { QString v = value.toLower(); if (v == "true") property->setScriptable(true); @@ -1884,7 +1893,7 @@ bool CppCodeParser::matchProperty(InnerNode *parent) property->setRuntimeScrFunc(value); } } - else if (key == "COSTANT") + else if (key == "CONSTANT") property->setConstant(); else if (key == "FINAL") property->setFinal(); diff --git a/tools/qdoc3/ditaxmlgenerator.cpp b/tools/qdoc3/ditaxmlgenerator.cpp index e180c0a..5d3e34a 100644 --- a/tools/qdoc3/ditaxmlgenerator.cpp +++ b/tools/qdoc3/ditaxmlgenerator.cpp @@ -61,230 +61,6 @@ QT_BEGIN_NAMESPACE #define COMMAND_VERSION Doc::alias("version") int DitaXmlGenerator::id = 0; -bool DitaXmlGenerator::inApiDesc = false; -bool DitaXmlGenerator::inSection = false; -bool DitaXmlGenerator::inDetailedDescription = false; -bool DitaXmlGenerator::inLegaleseText = false; - -#define cxxapi_d_xref Doc::alias("cxxapi-d-xref") -#define cxxclass Doc::alias("cxxclass") -#define cxxdefine Doc::alias("cxxdefine") -#define cxxenumeration Doc::alias("cxxenumeration") -#define cxxfile Doc::alias("cxxfile") -#define cxxfunction Doc::alias("cxxfunction") -#define cxxstruct Doc::alias("cxxstruct") -#define cxxtypedef Doc::alias("cxxtypedef") -#define cxxunion Doc::alias("cxxunion") -#define cxxvariable Doc::alias("cxxvariable") - -#define CXXAPIMAP Doc::alias("cxxAPIMap") -#define CXXCLASSREF Doc::alias("cxxClassRef") -#define CXXDEFINEREF Doc::alias("cxxDefineRef") -#define CXXENUMERATIONREF Doc::alias("cxxEnumerationRef") -#define CXXFILEREF Doc::alias("cxxFileRef") -#define CXXFUNCTIONREF Doc::alias("cxxFunctionRef") -#define CXXSTRUCTREF Doc::alias("cxxStructRef") -#define CXXTYPDEFREF Doc::alias("cxxTypedefRef") -#define CXXUNIONREF Doc::alias("cxxUnionRef") -#define CXXVARIABLEREF Doc::alias("cxxVariableRef") - -#define CXXCLASS Doc::alias("cxxClass") -#define CXXCLASSABSTRACT Doc::alias("cxxClassAbstract") -#define CXXCLASSACCESSSPECIFIER Doc::alias("cxxClassAccessSpecifier") -#define CXXCLASSAPIITEMLOCATION Doc::alias("cxxClassAPIItemLocation") -#define CXXCLASSBASECLASS Doc::alias("cxxClassBaseClass") -#define CXXCLASSBASECLASSSTRUCT Doc::alias("cxxClassBaseStruct") -#define CXXCLASSBASEUNION Doc::alias("cxxClassBaseUnion") -#define CXXCLASSDECLARATIONFILE Doc::alias("cxxClassDeclarationFile") -#define CXXCLASSDECLARATIONFILELINE Doc::alias("cxxClassDeclarationFileLine") -#define CXXCLASSDEFINITION Doc::alias("cxxClassDefinition") -#define CXXCLASSDEFINITIONFILE Doc::alias("cxxClassDefinitionFile") -#define CXXCLASSDEFINITIONFILEEND Doc::alias("cxxClassDefinitionFileLineEnd") -#define CXXCLASSDEFINITIONFILESTART Doc::alias("cxxClassDefinitionFileLineStart") -#define CXXCLASSDERIVATION Doc::alias("cxxClassDerivation") -#define CXXCLASSDERIVATIONACCESSSPECIFIER Doc::alias("cxxClassDerivationAccessSpecifier") -#define CXXCLASSDERIVATIONS Doc::alias("cxxClassDerivations") -#define CXXCLASSDERIVATIONVIRTUAL Doc::alias("cxxClassDerivationVirtual") -#define CXXCLASSDETAIL Doc::alias("cxxClassDetail") -#define CXXCLASSENUMERATIONINHERITED Doc::alias("cxxClassEnumerationInherited") -#define CXXCLASSENUMERATORINHERITED Doc::alias("cxxClassEnumeratorInherited") -#define CXXCLASSFUNCTIONINHERITED Doc::alias("cxxClassFunctionInherited") -#define CXXCLASSINHERITS Doc::alias("cxxClassInherits") -#define CXXCLASSINHERITSDETAIL Doc::alias("cxxClassInheritsDetail") -#define CXXCLASSNESTED Doc::alias("cxxClassNested") -#define CXXCLASSNESTEDCLASS Doc::alias("cxxClassNestedClass") -#define CXXCLASSNESTEDDETAIL Doc::alias("cxxClassNestedDetail") -#define CXXCLASSNESTEDSTRUCT Doc::alias("cxxClassNestedStruct") -#define CXXCLASSNESTEDUNION Doc::alias("cxxClassNestedUnion") -#define CXXCLASSTEMPLATEPARAMETER Doc::alias("cxxClassTemplateParameter") -#define CXXCLASSTEMPLATEPARAMETERS Doc::alias("cxxClassTemplateParameters") -#define CXXCLASSTEMPLATEPARAMETERTYPE Doc::alias("cxxClassTemplateParameterType") -#define CXXCLASSVARIABLEINHERITED Doc::alias("cxxClassVariableInherited") - -#define CXXDEFINE Doc::alias("cxxDefine") -#define CXXDEFINEACCESSSPECIFIER Doc::alias("cxxDefineAccessSpecifier") -#define CXXDEFINEAPIITEMLOCATION Doc::alias("cxxDefineAPIItemLocation") -#define CXXDEFINEDECLARATIONFILE Doc::alias("cxxDefineDeclarationFile") -#define CXXDEFINEDECLARATIONFILELINE Doc::alias("cxxDefineDeclarationFileLine") -#define CXXDEFINEDEFINITION Doc::alias("cxxDefineDefinition") -#define CXXDEFINEDETAIL Doc::alias("cxxDefineDetail") -#define CXXDEFINENAMELOOKUP Doc::alias("cxxDefineNameLookup") -#define CXXDEFINEPARAMETER Doc::alias("cxxDefineParameter") -#define CXXDEFINEPARAMETERDECLARATIONNAME Doc::alias("cxxDefineParameterDeclarationName") -#define CXXDEFINEPARAMETERS Doc::alias("cxxDefineParameters") -#define CXXDEFINEPROTOTYPE Doc::alias("cxxDefinePrototype") -#define CXXDEFINEREIMPLEMENTED Doc::alias("cxxDefineReimplemented") - -#define CXXENUMERATION Doc::alias("cxxEnumeration") -#define CXXENUMERATIONACCESSSPECIFIER Doc::alias("cxxEnumerationAccessSpecifier") -#define CXXENUMERATIONAPIITEMLOCATION Doc::alias("cxxEnumerationAPIItemLocation") -#define CXXENUMERATIONDECLARATIONFILE Doc::alias("cxxEnumerationDeclarationFile") -#define CXXENUMERATIONDECLARATIONFILELINE Doc::alias("cxxEnumerationDeclarationFileLine") -#define CXXENUMERATIONDEFINITION Doc::alias("cxxEnumerationDefinition") -#define CXXENUMERATIONDEFINITIONFILE Doc::alias("cxxEnumerationDefinitionFile") -#define CXXENUMERATIONDEFINITIONFILELINEEND Doc::alias("cxxEnumerationDefinitionFileLineEnd") -#define CXXENUMERATIONDEFINITIONFILELINESTART Doc::alias("cxxEnumerationDefinitionFileLineStart") -#define CXXENUMERATIONDETAIL Doc::alias("cxxEnumerationDetail") -#define CXXENUMERATIONNAMELOOKUP Doc::alias("cxxEnumerationNameLookup") -#define CXXENUMERATIONPROTOTYPE Doc::alias("cxxEnumerationPrototype") -#define CXXENUMERATIONREIMPLEMENTED Doc::alias("cxxEnumerationReimplemented") -#define CXXENUMERATIONSCOPEDNAME Doc::alias("cxxEnumerationScopedName") -#define CXXENUMERATOR Doc::alias("cxxEnumerator") -#define CXXENUMERATORAPIITEMLOCATION Doc::alias("cxxEnumeratorAPIItemLocation") -#define CXXENUMERATORDECLARATIONFILE Doc::alias("cxxEnumeratorDeclarationFile") -#define CXXENUMERATORDECLARATIONFILELINE Doc::alias("cxxEnumeratorDeclarationFileLine") -#define CXXENUMERATORINITIALISER Doc::alias("cxxEnumeratorInitialiser") -#define CXXENUMERATORNAMELOOKUP Doc::alias("cxxEnumeratorNameLookup") -#define CXXENUMERATORPROTOTYPE Doc::alias("cxxEnumeratorPrototype") -#define CXXENUMERATORS Doc::alias("cxxEnumerators") -#define CXXENUMERATORSCOPEDNAME Doc::alias("cxxEnumeratorScopedName") - -#define CXXFILE_INFO_TYPES Doc::alias("cxxFile-info-types") -#define CXXFILE_TYPES_DEFAULT Doc::alias("cxxFile-types-default") -#define CXXFILE Doc::alias("cxxFile") -#define CXXFILEAPIITMELOCATION Doc::alias("cxxFileAPIItemLocation") -#define CXXFILEDECLARATIONFILE Doc::alias("cxxFileDeclarationFile") - -#define CXXFUNCTION Doc::alias("cxxFunction") -#define CXXFUNCTIONACCESSSPECIFIER Doc::alias("cxxFunctionAccessSpecifier") -#define CXXFUNCTIONAPIITEMLOCATION Doc::alias("cxxFunctionAPIItemLocation") -#define CXXFUNCTIONCONST Doc::alias("cxxFunctionConst") -#define CXXFUNCTIONCONSTRUCTOR Doc::alias("cxxFunctionConstructor") -#define CXXFUNCTIONDECLARATIONFILE Doc::alias("cxxFunctionDeclarationFile") -#define CXXFUNCTIONDECLARATIONFILELINE Doc::alias("cxxFunctionDeclarationFileLine") -#define CXXFUNCTIONDECLAREDTYPE Doc::alias("cxxFunctionDeclaredType") -#define CXXFUNCTIONDEFINITION Doc::alias("cxxFunctionDefinition") -#define CXXFUNCTIONDEFINITIONFILE Doc::alias("cxxFunctionDefinitionFile") -#define CXXFUNCTIONDEFINITIONFILELINEEND Doc::alias("cxxFunctionDefinitionFileLineEnd") -#define CXXFUNCTIONDEFINITIONFILELINESTART Doc::alias("cxxFunctionDefinitionFileLineStart") -#define CXXFUNCTIONDESTRUCTOR Doc::alias("cxxFunctionDestructor") -#define CXXFUNCTIONDETAIL Doc::alias("cxxFunctionDetail") -#define CXXFUNCTIONEXPLICIT Doc::alias("cxxFunctionExplicit") -#define CXXFUNCTIONINLINE Doc::alias("cxxFunctionInline") -#define CXXFUNCTIONNAMELOOKUP Doc::alias("cxxFunctionNameLookup") -#define CXXFUNCTIONPARAMETER Doc::alias("cxxFunctionParameter") -#define CXXFUNCTIONPARAMETERDECLARATIONNAME Doc::alias("cxxFunctionParameterDeclarationName") -#define CXXFUNCTIONPARAMETERDECLAREDTYPE Doc::alias("cxxFunctionParameterDeclaredType") -#define CXXFUNCTIONPARAMETERDEFAULTVALUE Doc::alias("cxxFunctionParameterDefaultValue") -#define CXXFUNCTIONPARAMETERDEFINITIONNAME Doc::alias("cxxFunctionParameterDefinitionName") -#define CXXFUNCTIONPARAMETERS Doc::alias("cxxFunctionParameters") -#define CXXFUNCTIONPROTOTYPE Doc::alias("cxxFunctionPrototype") -#define CXXFUNCTIONPUREVIRTUAL Doc::alias("cxxFunctionPureVirtual") -#define CXXFUNCTIONREIMPLEMENTED Doc::alias("cxxFunctionReimplemented") -#define CXXFUNCTIONRETURNTYPE Doc::alias("cxxFunctionReturnType") -#define CXXFUNCTIONSCOPEDNAME Doc::alias("cxxFunctionScopedName") -#define CXXFUNCTIONSTORAGECLASSSPECIFIEREXTERN Doc::alias("cxxFunctionStorageClassSpecifierExtern") -#define CXXFUNCTIONSTORAGECLASSSPECIFIERMUTABLE Doc::alias("cxxFunctionStorageClassSpecifierMutable") -#define CXXFUNCTIONSTORAGECLASSSPECIFIERSTATIC Doc::alias("cxxFunctionStorageClassSpecifierStatic") -#define CXXFUNCTIONTEMPLATEPARAMETER Doc::alias("cxxFunctionTemplateParameter") -#define CXXFUNCTIONTEMPLATEPARAMETERS Doc::alias("cxxFunctionTemplateParameters") -#define CXXFUNCTIONTEMPLATEPARAMETERTYPE Doc::alias("cxxFunctionTemplateParameterType") -#define CXXFUNCTIONVIRTUAL Doc::alias("cxxFunctionVirtual") -#define CXXFUNCTIONVOLATILE Doc::alias("cxxFunctionVolatile") - -#define CXXSTRUCT Doc::alias("cxxStruct") -#define CXXSTRUCTABSTRACT Doc::alias("cxxStructAbstract") -#define CXXSTRUCTACCESSSPECIFIER Doc::alias("cxxStructAccessSpecifier") -#define CXXSTRUCTAPIITEMLOCATION Doc::alias("cxxStructAPIItemLocation") -#define CXXSTRUCTBASECLASS Doc::alias("cxxStructBaseClass") -#define CXXSTRUCTBASESTRUCT Doc::alias("cxxStructBaseStruct") -#define CXXSTRUCTBASEUNION Doc::alias("cxxStructBaseUnion") -#define CXXSTRUCTDECLARATIONFILE Doc::alias("cxxStructDeclarationFile") -#define CXXSTRUCTDECLARATIONFILELINE Doc::alias("cxxStructDeclarationFileLine") -#define CXXSTRUCTDEFINITION Doc::alias("cxxStructDefinition") -#define CXXSTRUCTDEFINITIONFILE Doc::alias("cxxStructDefinitionFile") -#define CXXSTRUCTDEFINITIONFILELINEEND Doc::alias("cxxStructDefinitionFileLineEnd") -#define CXXSTRUCTDEFINITIONFILELINESTART Doc::alias("cxxStructDefinitionFileLineStart") -#define CXXSTRUCTDERIVATION Doc::alias("cxxStructDerivation") -#define CXXSTRUCTDERIVATIONACCESSSPECIFIER Doc::alias("cxxStructDerivationAccessSpecifier") -#define CXXSTRUCTDERIVATIONS Doc::alias("cxxStructDerivations") -#define CXXSTRUCTDERIVATIONVIRTUAL Doc::alias("cxxStructDerivationVirtual") -#define CXXSTRUCTDETAIL Doc::alias("cxxStructDetail") -#define CXXSTRUCTENUMERATIONINHERITED Doc::alias("cxxStructEnumerationInherited") -#define CXXSTRUCTENUMERATORINHERITED Doc::alias("cxxStructEnumeratorInherited") -#define CXXSTRUCTFUNCTIONINHERITED Doc::alias("cxxStructFunctionInherited") -#define CXXSTRUCTINHERITS Doc::alias("cxxStructInherits") -#define CXXSTRUCTINHERITSDETAIL Doc::alias("cxxStructInheritsDetail") -#define CXXSTRUCTNESTED Doc::alias("cxxStructNested") -#define CXXSTRUCTNESTEDCLASS Doc::alias("cxxStructNestedClass") -#define CXXSTRUCTNESTEDDETAIL Doc::alias("cxxStructNestedDetail") -#define CXXSTRUCTNESTEDSTRUCT Doc::alias("cxxStructNestedStruct") -#define CXXSTRUCTNESTEDUNION Doc::alias("cxxStructNestedUnion") -#define CXXSTRUCTTEMPLATEPARAMETER Doc::alias("cxxStructTemplateParameter") -#define CXXSTRUCTTEMPLATEPARAMETERS Doc::alias("cxxStructTemplateParameters") -#define CXXSTRUCTTEMPLATEPARAMETERTYPE Doc::alias("cxxStructTemplateParameterType") -#define CXXSTRUCTVARIABLEINHERITED Doc::alias("cxxStructVariableInherited") - -#define CXXTYPEDEF Doc::alias("cxxTypedef") -#define CXXTYPEDEFACCESSSPECIFIER Doc::alias("cxxTypedefAccessSpecifier") -#define CXXTYPEDEFAPIITEMLOCATION Doc::alias("cxxTypedefAPIItemLocation") -#define CXXTYPEDEFDECLARATIONFILE Doc::alias("cxxTypedefDeclarationFile") -#define CXXTYPEDEFDECLARATIONFILELINE Doc::alias("cxxTypedefDeclarationFileLine") -#define CXXTYPEDEFDECLAREDTYPE Doc::alias("cxxTypedefDeclaredType") -#define CXXTYPEDEFDEFINITION Doc::alias("cxxTypedefDefinition") -#define CXXTYPEDEFDETAIL Doc::alias("cxxTypedefDetail") -#define CXXTYPEDEFNAMELOOKUP Doc::alias("cxxTypedefNameLookup") -#define CXXTYPEDEFPROTOTYPE Doc::alias("cxxTypedefPrototype") -#define CXXTYPEDEFREIMPLEMENTED Doc::alias("cxxTypedefReimplemented") -#define CXXTYPEDEFSCOPEDNAME Doc::alias("cxxTypedefScopedName") - -#define CXXUNION Doc::alias("cxxUnion") -#define CXXUNIONABSTRACT Doc::alias("cxxUnionAbstract") -#define CXXUNIONACCESSSPECIFIER Doc::alias("cxxUnionAccessSpecifier") -#define CXXUNIONAPIITEMLOCATION Doc::alias("cxxUnionAPIItemLocation") -#define CXXUNIONDECLARATIONFILE Doc::alias("cxxUnionDeclarationFile") -#define CXXUNIONDECLARATIONFILELINE Doc::alias("cxxUnionDeclarationFileLine") -#define CXXUNIONDEFINITION Doc::alias("cxxUnionDefinition") -#define CXXUNIONDEFINITIONFILE Doc::alias("cxxUnionDefinitionFile") -#define CXXUNIONDEFINITIONFILELINEEND Doc::alias("cxxUnionDefinitionFileLineEnd") -#define CXXUNIONDEFINITIONFILELINESTART Doc::alias("cxxUnionDefinitionFileLineStart") -#define CXXUNIONDETAIL Doc::alias("cxxUnionDetail") -#define CXXUNIONNESTED Doc::alias("cxxUnionNested") -#define CXXUNIONNESTEDCLASS Doc::alias("cxxUnionNestedClass") -#define CXXUNIONNESTEDDETAIL Doc::alias("cxxUnionNestedDetail") -#define CXXUNIONNESTEDSTRUCT Doc::alias("cxxUnionNestedStruct") -#define CXXUNIONNESTEDUNION Doc::alias("cxxUnionNestedUnion") -#define CXXUNIONTEMPLATEPARAMETER Doc::alias("cxxUnionTemplateParameter") -#define CXXUNIONTEMPLATEPARAMETERS Doc::alias("cxxUnionTemplateParameters") -#define CXXUNIONTEMPLATEPARAMETERTYPE Doc::alias("cxxUnionTemplateParameterType") - -#define CXXVARIABLE Doc::alias("cxxVariable") -#define CXXVARIABLEACCESSSPECIFIER Doc::alias("cxxVariableAccessSpecifier") -#define CXXVARIABLEAPIITEMLOCATION Doc::alias("cxxVariableAPIItemLocation") -#define CXXVARIABLECONST Doc::alias("cxxVariableConst") -#define CXXVARIABLEDECLARATIONFILE Doc::alias("cxxVariableDeclarationFile") -#define CXXVARIABLEDECLARATIONFILELINE Doc::alias("cxxVariableDeclarationFileLine") -#define CXXVARIABLEDECLAREDTYPE Doc::alias("cxxVariableDeclaredType") -#define CXXVARIABLEDEFINITION Doc::alias("cxxVariableDefinition") -#define CXXVARIABLEDETAIL Doc::alias("cxxVariableDetail") -#define CXXVARIABLENAMELOOKUP Doc::alias("cxxVariableNameLookup") -#define CXXVARIABLEPROTOTYPE Doc::alias("cxxVariablePrototype") -#define CXXVARIABLEREIMPLEMENTED Doc::alias("cxxVariableReimplemented") -#define CXXVARIABLESCOPEDNAME Doc::alias("cxxVariableScopedName") -#define CXXVARIABLESTORAGECLASSSPECIFIEREXTERN Doc::alias("cxxVariableStorageClassSpecifierExtern") -#define CXXVARIABLESTORAGECLASSSPECIFIERMUTABLE Doc::alias("cxxVariableStorageClassSpecifierMutable") -#define CXXVARIABLESTORAGECLASSSPECIFIERSTATIC Doc::alias("cxxVariableStorageClassSpecifierStatic") -#define CXXVARIABLEVOLATILE Doc::alias("cxxVariableVolatile") QString DitaXmlGenerator::sinceTitles[] = { @@ -305,6 +81,187 @@ QString DitaXmlGenerator::sinceTitles[] = "" }; +/* + The strings in this array must appear in the same order as + the values in enum DitaXmlGenerator::DitaTag. + */ +QString DitaXmlGenerator::ditaTags[] = + { + "", + "alt", + "apiDesc", + "APIMap", + "apiName", + "audience", + "author", + "b", + "body", + "bodydiv", + "brand", + "category", + "codeblock", + "comment", + "component", + "copyrholder", + "copyright", + "copyryear", + "created", + "critdates", + "cxxAPIMap", + "cxxClass", + "cxxClassAbstract", + "cxxClassAccessSpecifier", + "cxxClassAPIItemLocation", + "cxxClassBaseClass", + "cxxClassDeclarationFile", + "cxxClassDeclarationFileLine", + "cxxClassDefinition", + "cxxClassDerivation", + "cxxClassDerivationAccessSpecifier", + "cxxClassDerivations", + "cxxClassDetail", + "cxxClassNested", + "cxxClassNestedClass", + "cxxClassNestedDetail", + "cxxDefine", + "cxxDefineAccessSpecifier", + "cxxDefineAPIItemLocation", + "cxxDefineDeclarationFile", + "cxxDefineDeclarationFileLine", + "cxxDefineDefinition", + "cxxDefineDetail", + "cxxDefineNameLookup", + "cxxDefineParameter", + "cxxDefineParameterDeclarationName", + "cxxDefineParameters", + "cxxDefinePrototype", + "cxxDefineReimplemented", + "cxxEnumeration", + "cxxEnumerationAccessSpecifier", + "cxxEnumerationAPIItemLocation", + "cxxEnumerationDeclarationFile", + "cxxEnumerationDeclarationFileLine", + "cxxEnumerationDefinition", + "cxxEnumerationDefinitionFile", + "cxxEnumerationDefinitionFileLineStart", + "cxxEnumerationDefinitionFileLineEnd", + "cxxEnumerationDetail", + "cxxEnumerationNameLookup", + "cxxEnumerationPrototype", + "cxxEnumerationScopedName", + "cxxEnumerator", + "cxxEnumeratorInitialiser", + "cxxEnumeratorNameLookup", + "cxxEnumeratorPrototype", + "cxxEnumerators", + "cxxEnumeratorScopedName", + "cxxFunction", + "cxxFunctionAccessSpecifier", + "cxxFunctionAPIItemLocation", + "cxxFunctionConst", + "cxxFunctionConstructor", + "cxxFunctionDeclarationFile", + "cxxFunctionDeclarationFileLine", + "cxxFunctionDeclaredType", + "cxxFunctionDefinition", + "cxxFunctionDestructor", + "cxxFunctionDetail", + "cxxFunctionNameLookup", + "cxxFunctionParameter", + "cxxFunctionParameterDeclarationName", + "cxxFunctionParameterDeclaredType", + "cxxFunctionParameterDefaultValue", + "cxxFunctionParameters", + "cxxFunctionPrototype", + "cxxFunctionPureVirtual", + "cxxFunctionReimplemented", + "cxxFunctionScopedName", + "cxxFunctionStorageClassSpecifierStatic", + "cxxFunctionVirtual", + "cxxTypedef", + "cxxTypedefAccessSpecifier", + "cxxTypedefAPIItemLocation", + "cxxTypedefDeclarationFile", + "cxxTypedefDeclarationFileLine", + "cxxTypedefDefinition", + "cxxTypedefDetail", + "cxxTypedefNameLookup", + "cxxTypedefScopedName", + "cxxVariable", + "cxxVariableAccessSpecifier", + "cxxVariableAPIItemLocation", + "cxxVariableDeclarationFile", + "cxxVariableDeclarationFileLine", + "cxxVariableDeclaredType", + "cxxVariableDefinition", + "cxxVariableDetail", + "cxxVariableNameLookup", + "cxxVariablePrototype", + "cxxVariableReimplemented", + "cxxVariableScopedName", + "cxxVariableStorageClassSpecifierStatic", + "data", + "data-about", + "dd", + "dl", + "dlentry", + "dt", + "entry", + "fig", + "i", + "image", + "keyword", + "keywords", + "li", + "link", + "linktext", + "lq", + "metadata", + "ol", + "othermeta", + "p", + "parameter", + "permissions", + "ph", + "platform", + "pre", + "prodinfo", + "prodname", + "prolog", + "publisher", + "related-links", + "resourceid", + "revised", + "row", + "section", + "sectiondiv", + "shortdesc", + "simpletable", + "source", + "stentry", + "sthead", + "strow", + "sub", + "sup", + "table", + "tbody", + "tgroup", + "thead", + "title", + "tm", + "topic", + "topicmeta", + "topicref", + "tt", + "u", + "ul", + "unknown", + "vrm", + "vrmlist", + "xref", + "" + }; + static bool showBrokenLinks = false; /*! @@ -330,10 +287,11 @@ void DitaXmlGenerator::addLink(const QString& href, const QStringRef& text) { if (!href.isEmpty()) { - xmlWriter().writeStartElement("xref"); + writeStartTag(DT_xref); + // formathtml xmlWriter().writeAttribute("href", href); writeCharacters(text.toString()); - xmlWriter().writeEndElement(); // </xref> + writeEndTag(); // </xref> } else { writeCharacters(text.toString()); @@ -341,22 +299,129 @@ void DitaXmlGenerator::addLink(const QString& href, } /*! + Push \a t onto the dita tag stack and write the appropriate + start tag to the DITA XML file. + */ +void DitaXmlGenerator::writeStartTag(DitaTag t) +{ + xmlWriter().writeStartElement(ditaTags[t]); + tagStack.push(t); +} + +/*! + Pop the current DITA tag off the stack, and write the + appropriate end tag to the DITA XML file. + */ +void DitaXmlGenerator::writeEndTag(DitaTag t) +{ + DitaTag top = tagStack.pop(); + if (t > DT_NONE && top != t) + qDebug() << "Expected:" << t << "ACTUAL:" << top; + xmlWriter().writeEndElement(); +} + +/*! + Return the current DITA element tag, the one + on top of the stack. + */ +DitaXmlGenerator::DitaTag DitaXmlGenerator::currentTag() +{ + return tagStack.top(); +} + +/*! + Write the start tag \c{<apiDesc>}. if \a title is not + empty, generate a GUID from it and write the GUID as the + value of the \e{id} attribute. Then write \a title as + the value of the \e {spectitle} attribute. + + Then if \a outputclass is not empty, write it as the value + of the \a outputclass attribute. + + Fiunally, set the section nesting level to 1 and return 1. + */ +int DitaXmlGenerator::enterApiDesc(const QString& outputclass, const QString& title) +{ + writeStartTag(DT_apiDesc); + if (!title.isEmpty()) { + writeGuidAttribute(title); + xmlWriter().writeAttribute("spectitle",title); + } + if (!outputclass.isEmpty()) + xmlWriter().writeAttribute("outputclass",outputclass); + sectionNestingLevel = 1; + return sectionNestingLevel; +} + +/*! + If the section nesting level is 0, output a \c{<section>} + element with an \e id attribute generated from \a title and + an \e outputclass attribute set to \a outputclass. + If \a title is null, no \e id attribute is output. + If \a outputclass is empty, no \e outputclass attribute + is output. + + Finally, increment the section nesting level and return + the new value. + */ +int DitaXmlGenerator::enterSection(const QString& outputclass, const QString& title) +{ + if (sectionNestingLevel == 0) { + writeStartTag(DT_section); + if (!title.isEmpty()) + writeGuidAttribute(title); + if (!outputclass.isEmpty()) + xmlWriter().writeAttribute("outputclass",outputclass); + } + else if (!title.isEmpty()) { + writeStartTag(DT_p); + writeGuidAttribute(title); + if (!outputclass.isEmpty()) + xmlWriter().writeAttribute("outputclass",outputclass); + writeCharacters(title); + writeEndTag(); // </p> + } + return ++sectionNestingLevel; +} + +/*! + If the section nesting level is greater than 0, decrement + it. If it becomes 0, output a \c {</section>}. Return the + decremented section nesting level. + */ +int DitaXmlGenerator::leaveSection() +{ + if (sectionNestingLevel > 0) { + --sectionNestingLevel; + if (sectionNestingLevel == 0) + writeEndTag(); // </section> or </apiDesc> + } + return sectionNestingLevel; +} + +/*! The default constructor. */ DitaXmlGenerator::DitaXmlGenerator() - : inLink(false), - inContents(false), + : inContents(false), + inDetailedDescription(false), + inLegaleseText(false), + inLink(false), + inObsoleteLink(false), inSectionHeading(false), inTableHeader(false), inTableBody(false), - numTableRows(0), - threeColumnEnumValueTable(true), + noLinks(false), + obsoleteLinks(false), offlineDocs(true), + threeColumnEnumValueTable(true), + codeIndent(0), + numTableRows(0), + divNestingLevel(0), + sectionNestingLevel(0), + tableColumnCount(0), funcLeftParen("\\S(\\()"), - myTree(0), - obsoleteLinks(false), - noLinks(false), - tableColumnCount(0) + myTree(0) { // nothing yet. } @@ -378,29 +443,9 @@ DitaXmlGenerator::~DitaXmlGenerator() */ void DitaXmlGenerator::initializeGenerator(const Config &config) { - static const struct { - const char *key; - const char *tag; - } defaults[] = { - { ATOM_FORMATTING_BOLD, "b" }, - { ATOM_FORMATTING_INDEX, "<!--" }, - { ATOM_FORMATTING_ITALIC, "i" }, - { ATOM_FORMATTING_PARAMETER, "i" }, - { ATOM_FORMATTING_SUBSCRIPT, "sub" }, - { ATOM_FORMATTING_SUPERSCRIPT, "sup" }, - { ATOM_FORMATTING_TELETYPE, "tt", }, - { ATOM_FORMATTING_UNDERLINE, "u", }, - { 0, 0 } - }; - Generator::initializeGenerator(config); obsoleteLinks = config.getBool(QLatin1String(CONFIG_OBSOLETELINKS)); setImageFileExtensions(QStringList() << "png" << "jpg" << "jpeg" << "gif"); - int i = 0; - while (defaults[i].key) { - formattingLeftMap().insert(defaults[i].key, defaults[i].tag); - i++; - } style = config.getString(DitaXmlGenerator::format() + Config::dot + @@ -467,7 +512,8 @@ void DitaXmlGenerator::initializeGenerator(const Config &config) Config::dot + DITAXMLGENERATOR_CUSTOMHEADELEMENTS); codeIndent = config.getInt(CONFIG_CODEINDENT); - + version = config.getString(CONFIG_VERSION); + vrm = version.split("."); } /*! @@ -639,7 +685,7 @@ int DitaXmlGenerator::generateAtom(const Atom *atom, int skipAhead = 0; QString hx, str; static bool in_para = false; - QString guid, hc; + QString guid, hc, attr; switch (atom->type()) { case Atom::AbstractLeft: @@ -670,13 +716,13 @@ int DitaXmlGenerator::generateAtom(const Atom *atom, //skipAhead = skipAtoms(atom, Atom::BriefRight); //break; //} - if (inApiDesc || inSection) { - xmlWriter().writeStartElement("p"); + if (inSection()) { + writeStartTag(DT_p); xmlWriter().writeAttribute("outputclass","brief"); } else { noLinks = true; - xmlWriter().writeStartElement("shortdesc"); + writeStartTag(DT_shortdesc); } if (relative->type() == Node::Property || relative->type() == Node::Variable) { @@ -704,62 +750,98 @@ int DitaXmlGenerator::generateAtom(const Atom *atom, break; case Atom::BriefRight: // if (relative->type() != Node::Fake) - xmlWriter().writeEndElement(); // </shortdesc> or </p> + writeEndTag(); // </shortdesc> or </p> noLinks = false; break; case Atom::C: - xmlWriter().writeStartElement(formattingLeftMap()[ATOM_FORMATTING_TELETYPE]); + writeStartTag(DT_tt); if (inLink) { writeCharacters(protectEnc(plainCode(atom->string()))); } else { writeText(atom->string(), marker, relative); } - xmlWriter().writeEndElement(); // sse writeStartElement() above + writeEndTag(); // see writeStartElement() above break; case Atom::Code: { - xmlWriter().writeStartElement("codeblock"); + writeStartTag(DT_codeblock); QString chars = trimmedTrailing(atom->string()); writeText(chars, marker, relative); - xmlWriter().writeEndElement(); // </codeblock> + writeEndTag(); // </codeblock> } break; case Atom::Qml: - xmlWriter().writeStartElement("codeblock"); + writeStartTag(DT_codeblock); writeText(trimmedTrailing(atom->string()), marker, relative); - xmlWriter().writeEndElement(); // </codeblock> + writeEndTag(); // </codeblock> break; case Atom::CodeNew: - xmlWriter().writeStartElement("p"); + writeStartTag(DT_p); xmlWriter().writeCharacters("you can rewrite it as"); - xmlWriter().writeEndElement(); // </p> - xmlWriter().writeStartElement("codeblock"); + writeEndTag(); // </p> + writeStartTag(DT_codeblock); writeText(trimmedTrailing(atom->string()), marker, relative); - xmlWriter().writeEndElement(); // </codeblock> + writeEndTag(); // </codeblock> break; case Atom::CodeOld: - xmlWriter().writeStartElement("p"); + writeStartTag(DT_p); xmlWriter().writeCharacters("For example, if you have code like"); - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </p> // fallthrough case Atom::CodeBad: - xmlWriter().writeStartElement("codeblock"); + writeStartTag(DT_codeblock); writeCharacters(trimmedTrailing(plainCode(atom->string()))); - xmlWriter().writeEndElement(); // </codeblock> + writeEndTag(); // </codeblock> break; - case Atom::Div: - xmlWriter().writeStartElement("bodydiv"); - if (!atom->string().isEmpty()) - xmlWriter().writeAttribute("outputclass", atom->string()); + case Atom::DivLeft: + { + attr = atom->string(); + DitaTag t = currentTag(); + if ((t == DT_section) || (t == DT_sectiondiv)) { + writeStartTag(DT_sectiondiv); + divNestingLevel++; + } + else if ((t == DT_body) || (t == DT_bodydiv)) { + writeStartTag(DT_bodydiv); + divNestingLevel++; + } + if (!attr.isEmpty()) { + if (attr.contains('=')) { + int index = 0; + int from = 0; + QString values; + while (index >= 0) { + index = attr.indexOf('"',from); + if (index >= 0) { + ++index; + from = index; + index = attr.indexOf('"',from); + if (index > from) { + if (!values.isEmpty()) + values.append(' '); + values += attr.mid(from,index-from); + from = index+1; + } + } + } + attr = values; + } + } + xmlWriter().writeAttribute("outputclass", attr); + } break; - case Atom::EndDiv: - xmlWriter().writeEndElement(); // </bodydiv> + case Atom::DivRight: + if ((currentTag() == DT_sectiondiv) || (currentTag() == DT_bodydiv)) { + writeEndTag(); // </sectiondiv>, </bodydiv>, or </p> + if (divNestingLevel > 0) + --divNestingLevel; + } break; case Atom::FootnoteLeft: // ### For now if (in_para) { - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </p> in_para = false; } xmlWriter().writeCharacters("<!-- "); @@ -773,18 +855,68 @@ int DitaXmlGenerator::generateAtom(const Atom *atom, case Atom::FormatIf: break; case Atom::FormattingLeft: - xmlWriter().writeStartElement(formattingLeftMap()[atom->string()]); - if (atom->string() == ATOM_FORMATTING_PARAMETER) { - if (atom->next() != 0 && atom->next()->type() == Atom::String) { - QRegExp subscriptRegExp("([a-z]+)_([0-9n])"); - if (subscriptRegExp.exactMatch(atom->next()->string())) { - xmlWriter().writeCharacters(subscriptRegExp.cap(1)); - xmlWriter().writeStartElement("sub"); - xmlWriter().writeCharacters(subscriptRegExp.cap(2)); - xmlWriter().writeEndElement(); // </sub> - skipAhead = 1; + { + DitaTag t = DT_LAST; + if (atom->string() == ATOM_FORMATTING_BOLD) + t = DT_b; + else if (atom->string() == ATOM_FORMATTING_PARAMETER) + t = DT_i; + else if (atom->string() == ATOM_FORMATTING_ITALIC) + t = DT_i; + else if (atom->string() == ATOM_FORMATTING_TELETYPE) + t = DT_tt; + else if (atom->string().startsWith("span ")) { + t = DT_keyword; + } + else if (atom->string() == ATOM_FORMATTING_UNDERLINE) + t = DT_u; + else if (atom->string() == ATOM_FORMATTING_INDEX) + t = DT_comment; + else if (atom->string() == ATOM_FORMATTING_SUBSCRIPT) + t = DT_sub; + else if (atom->string() == ATOM_FORMATTING_SUPERSCRIPT) + t = DT_sup; + else + qDebug() << "DT_LAST"; + writeStartTag(t); + if (atom->string() == ATOM_FORMATTING_PARAMETER) { + if (atom->next() != 0 && atom->next()->type() == Atom::String) { + QRegExp subscriptRegExp("([a-z]+)_([0-9n])"); + if (subscriptRegExp.exactMatch(atom->next()->string())) { + xmlWriter().writeCharacters(subscriptRegExp.cap(1)); + writeStartTag(DT_sub); + xmlWriter().writeCharacters(subscriptRegExp.cap(2)); + writeEndTag(); // </sub> + skipAhead = 1; + } } } + else if (t == DT_keyword) { + QString attr = atom->string().mid(5); + if (!attr.isEmpty()) { + if (attr.contains('=')) { + int index = 0; + int from = 0; + QString values; + while (index >= 0) { + index = attr.indexOf('"',from); + if (index >= 0) { + ++index; + from = index; + index = attr.indexOf('"',from); + if (index > from) { + if (!values.isEmpty()) + values.append(' '); + values += attr.mid(from,index-from); + from = index+1; + } + } + } + attr = values; + } + } + xmlWriter().writeAttribute("outputclass", attr); + } } break; case Atom::FormattingRight: @@ -792,7 +924,7 @@ int DitaXmlGenerator::generateAtom(const Atom *atom, endLink(); } else { - xmlWriter().writeEndElement(); // ? + writeEndTag(); // ? } break; case Atom::AnnotatedList: @@ -981,7 +1113,7 @@ int DitaXmlGenerator::generateAtom(const Atom *atom, /* First generate the table of contents. */ - xmlWriter().writeStartElement("ul"); + writeStartTag(DT_ul); s = sections.constBegin(); while (s != sections.constEnd()) { if (!(*s).members.isEmpty()) { @@ -990,17 +1122,17 @@ int DitaXmlGenerator::generateAtom(const Atom *atom, } ++s; } - xmlWriter().writeEndElement(); // </ul> + writeEndTag(); // </ul> int idx = 0; s = sections.constBegin(); while (s != sections.constEnd()) { if (!(*s).members.isEmpty()) { - xmlWriter().writeStartElement("p"); + writeStartTag(DT_p); writeGuidAttribute(Doc::canonicalTitle((*s).name)); xmlWriter().writeAttribute("outputclass","h3"); writeCharacters(protectEnc((*s).name)); - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </p> if (idx == Class) generateCompactList(0, marker, ncmap.value(), false, QString("Q")); else if (idx == QmlClass) @@ -1020,15 +1152,16 @@ int DitaXmlGenerator::generateAtom(const Atom *atom, pmap = parentmaps.begin(); while (pmap != parentmaps.end()) { NodeList nlist = pmap->values(); - xmlWriter().writeStartElement("p"); + writeStartTag(DT_p); xmlWriter().writeCharacters("Class "); - xmlWriter().writeStartElement("xref"); + writeStartTag(DT_xref); + // formathtml xmlWriter().writeAttribute("href",linkForNode(pmap.key(), 0)); QStringList pieces = fullName(pmap.key(), 0, marker).split("::"); writeCharacters(protectEnc(pieces.last())); - xmlWriter().writeEndElement(); // </xref> + writeEndTag(); // </xref> xmlWriter().writeCharacters(":"); - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </p> generateSection(nlist, 0, marker, CodeMarker::Summary); ++pmap; @@ -1060,8 +1193,8 @@ int DitaXmlGenerator::generateAtom(const Atom *atom, fileName = QLatin1String("images/") + protectEnc(atom->string()); } - xmlWriter().writeStartElement("fig"); - xmlWriter().writeStartElement("image"); + writeStartTag(DT_fig); + writeStartTag(DT_image); xmlWriter().writeAttribute("href",protectEnc(fileName)); if (atom->type() == Atom::InlineImage) xmlWriter().writeAttribute("placement","inline"); @@ -1070,12 +1203,12 @@ int DitaXmlGenerator::generateAtom(const Atom *atom, xmlWriter().writeAttribute("align","center"); } if (!text.isEmpty()) { - xmlWriter().writeStartElement("alt"); + writeStartTag(DT_alt); writeCharacters(protectEnc(text)); - xmlWriter().writeEndElement(); // </alt> + writeEndTag(); // </alt> } - xmlWriter().writeEndElement(); // </image> - xmlWriter().writeEndElement(); // </fig> + writeEndTag(); // </image> + writeEndTag(); // </fig> } break; case Atom::ImageText: @@ -1129,47 +1262,47 @@ int DitaXmlGenerator::generateAtom(const Atom *atom, break; case Atom::ListLeft: if (in_para) { - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </p> in_para = false; } if (atom->string() == ATOM_LIST_BULLET) { - xmlWriter().writeStartElement("ul"); + writeStartTag(DT_ul); } else if (atom->string() == ATOM_LIST_TAG) { - xmlWriter().writeStartElement("dl"); + writeStartTag(DT_dl); } else if (atom->string() == ATOM_LIST_VALUE) { threeColumnEnumValueTable = isThreeColumnEnumValueTable(atom); if (threeColumnEnumValueTable) { - xmlWriter().writeStartElement("simpletable"); + writeStartTag(DT_simpletable); xmlWriter().writeAttribute("outputclass","valuelist"); - xmlWriter().writeStartElement("sthead"); - xmlWriter().writeStartElement("stentry"); + writeStartTag(DT_sthead); + writeStartTag(DT_stentry); xmlWriter().writeCharacters("Constant"); - xmlWriter().writeEndElement(); // </stentry> - xmlWriter().writeStartElement("stentry"); + writeEndTag(); // </stentry> + writeStartTag(DT_stentry); xmlWriter().writeCharacters("Value"); - xmlWriter().writeEndElement(); // </stentry> - xmlWriter().writeStartElement("stentry"); + writeEndTag(); // </stentry> + writeStartTag(DT_stentry); xmlWriter().writeCharacters("Description"); - xmlWriter().writeEndElement(); // </stentry> - xmlWriter().writeEndElement(); // </sthead> + writeEndTag(); // </stentry> + writeEndTag(); // </sthead> } else { - xmlWriter().writeStartElement("simpletable"); + writeStartTag(DT_simpletable); xmlWriter().writeAttribute("outputclass","valuelist"); - xmlWriter().writeStartElement("sthead"); - xmlWriter().writeStartElement("stentry"); + writeStartTag(DT_sthead); + writeStartTag(DT_stentry); xmlWriter().writeCharacters("Constant"); - xmlWriter().writeEndElement(); // </stentry> - xmlWriter().writeStartElement("stentry"); + writeEndTag(); // </stentry> + writeStartTag(DT_stentry); xmlWriter().writeCharacters("Value"); - xmlWriter().writeEndElement(); // </stentry> - xmlWriter().writeEndElement(); // </sthead> + writeEndTag(); // </stentry> + writeEndTag(); // </sthead> } } else { - xmlWriter().writeStartElement("ol"); + writeStartTag(DT_ol); if (atom->string() == ATOM_LIST_UPPERALPHA) xmlWriter().writeAttribute("outputclass","upperalpha"); else if (atom->string() == ATOM_LIST_LOWERALPHA) @@ -1191,17 +1324,17 @@ int DitaXmlGenerator::generateAtom(const Atom *atom, break; case Atom::ListTagLeft: if (atom->string() == ATOM_LIST_TAG) { - xmlWriter().writeStartElement("dt"); + writeStartTag(DT_dt); } else { // (atom->string() == ATOM_LIST_VALUE) - xmlWriter().writeStartElement("strow"); - xmlWriter().writeStartElement("stentry"); - xmlWriter().writeStartElement("tt"); + writeStartTag(DT_strow); + writeStartTag(DT_stentry); + writeStartTag(DT_tt); writeCharacters(protectEnc(plainCode(marker->markedUpEnumValue(atom->next()->string(), relative)))); - xmlWriter().writeEndElement(); // </tt> - xmlWriter().writeEndElement(); // </stentry> - xmlWriter().writeStartElement("stentry"); + writeEndTag(); // </tt> + writeEndTag(); // </stentry> + writeStartTag(DT_stentry); QString itemValue; if (relative->type() == Node::Enum) { @@ -1212,64 +1345,64 @@ int DitaXmlGenerator::generateAtom(const Atom *atom, if (itemValue.isEmpty()) xmlWriter().writeCharacters("?"); else { - xmlWriter().writeStartElement("tt"); + writeStartTag(DT_tt); writeCharacters(protectEnc(itemValue)); - xmlWriter().writeEndElement(); // </tt> + writeEndTag(); // </tt> } skipAhead = 1; } break; case Atom::ListTagRight: if (atom->string() == ATOM_LIST_TAG) - xmlWriter().writeEndElement(); // </dt> + writeEndTag(); // </dt> break; case Atom::ListItemLeft: if (atom->string() == ATOM_LIST_TAG) { - xmlWriter().writeStartElement("dd"); + writeStartTag(DT_dd); } else if (atom->string() == ATOM_LIST_VALUE) { if (threeColumnEnumValueTable) { - xmlWriter().writeEndElement(); // </stentry> - xmlWriter().writeStartElement("stentry"); + writeEndTag(); // </stentry> + writeStartTag(DT_stentry); } } else { - xmlWriter().writeStartElement("li"); + writeStartTag(DT_li); } if (matchAhead(atom, Atom::ParaLeft)) skipAhead = 1; break; case Atom::ListItemRight: if (atom->string() == ATOM_LIST_TAG) { - xmlWriter().writeEndElement(); // </dd> + writeEndTag(); // </dd> } else if (atom->string() == ATOM_LIST_VALUE) { - xmlWriter().writeEndElement(); // </stentry> - xmlWriter().writeEndElement(); // </strow> + writeEndTag(); // </stentry> + writeEndTag(); // </strow> } else { - xmlWriter().writeEndElement(); // </li> + writeEndTag(); // </li> } break; case Atom::ListRight: if (atom->string() == ATOM_LIST_BULLET) { - xmlWriter().writeEndElement(); // </ul> + writeEndTag(); // </ul> } else if (atom->string() == ATOM_LIST_TAG) { - xmlWriter().writeEndElement(); // </dl> + writeEndTag(); // </dl> } else if (atom->string() == ATOM_LIST_VALUE) { - xmlWriter().writeEndElement(); // </simpletable> + writeEndTag(); // </simpletable> } else { - xmlWriter().writeEndElement(); // </ol> + writeEndTag(); // </ol> } break; case Atom::Nop: // nothing break; case Atom::ParaLeft: - xmlWriter().writeStartElement("p"); + writeStartTag(DT_p); if (inLegaleseText) xmlWriter().writeAttribute("outputclass","legalese"); in_para = true; @@ -1277,15 +1410,15 @@ int DitaXmlGenerator::generateAtom(const Atom *atom, case Atom::ParaRight: endLink(); if (in_para) { - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </p> in_para = false; } break; case Atom::QuotationLeft: - xmlWriter().writeStartElement("lq"); + writeStartTag(DT_lq); break; case Atom::QuotationRight: - xmlWriter().writeEndElement(); // </lq> + writeEndTag(); // </lq> break; case Atom::RawString: if (atom->string() == " ") @@ -1293,41 +1426,44 @@ int DitaXmlGenerator::generateAtom(const Atom *atom, if (atom->string().startsWith("&")) writeCharacters(atom->string()); else if (atom->string() == "<sup>*</sup>") { - xmlWriter().writeStartElement("sup"); + writeStartTag(DT_sup); writeCharacters("*"); - xmlWriter().writeEndElement(); // </sup> + writeEndTag(); // </sup> + } + else if (atom->string() == "<sup>®</sup>") { + writeStartTag(DT_tm); + xmlWriter().writeAttribute("tmtype","reg"); + writeEndTag(); // </tm> } else { - xmlWriter().writeStartElement("pre"); + writeStartTag(DT_pre); xmlWriter().writeAttribute("outputclass","raw-html"); writeCharacters(atom->string()); - xmlWriter().writeEndElement(); // </pre> + writeEndTag(); // </pre> } break; case Atom::SectionLeft: - if (inSection || inApiDesc) { +#if 0 + if (inApiDesc) { + writeEndTag(); // </apiDesc> inApiDesc = false; - xmlWriter().writeEndElement(); // </section> or </apiDesc> } - inSection = true; - xmlWriter().writeStartElement("section"); - writeGuidAttribute(Doc::canonicalTitle(Text::sectionHeading(atom).toString())); - xmlWriter().writeAttribute("outputclass","details"); +#endif + enterSection("details",QString()); + //writeGuidAttribute(Doc::canonicalTitle(Text::sectionHeading(atom).toString())); break; case Atom::SectionRight: - if (inSection) { - inSection = false; - xmlWriter().writeEndElement(); // </section> - } + leaveSection(); break; case Atom::SectionHeadingLeft: - xmlWriter().writeStartElement("title"); + writeStartTag(DT_p); + writeGuidAttribute(Doc::canonicalTitle(Text::sectionHeading(atom).toString())); hx = "h" + QString::number(atom->string().toInt() + hOffset(relative)); xmlWriter().writeAttribute("outputclass",hx); inSectionHeading = true; break; case Atom::SectionHeadingRight: - xmlWriter().writeEndElement(); // </title> (see case Atom::SectionHeadingLeft) + writeEndTag(); // </title> (see case Atom::SectionHeadingLeft) inSectionHeading = false; break; case Atom::SidebarLeft: @@ -1347,97 +1483,144 @@ int DitaXmlGenerator::generateAtom(const Atom *atom, case Atom::TableLeft: { if (in_para) { - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </p> in_para = false; } - xmlWriter().writeStartElement("table"); + writeStartTag(DT_table); numTableRows = 0; if (tableColumnCount != 0) { qDebug() << "ERROR: Nested tables!"; tableColumnCount = 0; } tableColumnCount = countTableColumns(atom->next()); - xmlWriter().writeStartElement("tgroup"); + writeStartTag(DT_tgroup); xmlWriter().writeAttribute("cols",QString::number(tableColumnCount)); inTableHeader = false; inTableBody = false; } break; case Atom::TableRight: - xmlWriter().writeEndElement(); // </tbody> - xmlWriter().writeEndElement(); // </tgroup> - xmlWriter().writeEndElement(); // </table> + writeEndTag(); // </tbody> + writeEndTag(); // </tgroup> + writeEndTag(); // </table> inTableHeader = false; inTableBody = false; tableColumnCount = 0; break; case Atom::TableHeaderLeft: if (inTableBody) { - xmlWriter().writeEndElement(); // </tbody> - xmlWriter().writeEndElement(); // </tgroup> - xmlWriter().writeEndElement(); // </table> + writeEndTag(); // </tbody> + writeEndTag(); // </tgroup> + writeEndTag(); // </table> inTableHeader = false; inTableBody = false; tableColumnCount = 0; - xmlWriter().writeStartElement("table"); + writeStartTag(DT_table); numTableRows = 0; tableColumnCount = countTableColumns(atom); - xmlWriter().writeStartElement("tgroup"); + writeStartTag(DT_tgroup); xmlWriter().writeAttribute("cols",QString::number(tableColumnCount)); } - xmlWriter().writeStartElement("thead"); + writeStartTag(DT_thead); xmlWriter().writeAttribute("valign","top"); - xmlWriter().writeStartElement("row"); + writeStartTag(DT_row); xmlWriter().writeAttribute("valign","top"); inTableHeader = true; inTableBody = false; break; case Atom::TableHeaderRight: - xmlWriter().writeEndElement(); // </row> + writeEndTag(); // </row> if (matchAhead(atom, Atom::TableHeaderLeft)) { skipAhead = 1; - xmlWriter().writeStartElement("row"); + writeStartTag(DT_row); xmlWriter().writeAttribute("valign","top"); } else { - xmlWriter().writeEndElement(); // </thead> + writeEndTag(); // </thead> inTableHeader = false; inTableBody = true; - xmlWriter().writeStartElement("tbody"); + writeStartTag(DT_tbody); } break; case Atom::TableRowLeft: if (!inTableHeader && !inTableBody) { inTableBody = true; - xmlWriter().writeStartElement("tbody"); + writeStartTag(DT_tbody); + } + writeStartTag(DT_row); + attr = atom->string(); + if (!attr.isEmpty()) { + if (attr.contains('=')) { + int index = 0; + int from = 0; + QString values; + while (index >= 0) { + index = attr.indexOf('"',from); + if (index >= 0) { + ++index; + from = index; + index = attr.indexOf('"',from); + if (index > from) { + if (!values.isEmpty()) + values.append(' '); + values += attr.mid(from,index-from); + from = index+1; + } + } + } + attr = values; + } + xmlWriter().writeAttribute("outputclass", attr); } - xmlWriter().writeStartElement("row"); xmlWriter().writeAttribute("valign","top"); break; case Atom::TableRowRight: - xmlWriter().writeEndElement(); // </row> + writeEndTag(); // </row> break; case Atom::TableItemLeft: { - xmlWriter().writeStartElement("entry"); - QStringList spans = atom->string().split(","); - if (spans.size() == 2) { - if (inTableHeader || - (spans[0].toInt() != 1) || - (spans[1].toInt() != 1)) { - QString s = "span(" + spans[0] + "," + spans[1] + ")"; - xmlWriter().writeAttribute("outputclass",s); + QString values = ""; + writeStartTag(DT_entry); + for (int i=0; i<atom->count(); ++i) { + attr = atom->string(i); + if (attr.contains('=')) { + int index = 0; + int from = 0; + while (index >= 0) { + index = attr.indexOf('"',from); + if (index >= 0) { + ++index; + from = index; + index = attr.indexOf('"',from); + if (index > from) { + if (!values.isEmpty()) + values.append(' '); + values += attr.mid(from,index-from); + from = index+1; + } + } + } + } + else { + QStringList spans = attr.split(","); + if (spans.size() == 2) { + if ((spans[0].toInt()>1) || (spans[1].toInt()>1)) { + values += "span(" + spans[0] + "," + spans[1] + ")"; + } + } } } + if (!values.isEmpty()) + xmlWriter().writeAttribute("outputclass",values); if (matchAhead(atom, Atom::ParaLeft)) skipAhead = 1; } break; case Atom::TableItemRight: if (inTableHeader) - xmlWriter().writeEndElement(); // </entry> + writeEndTag(); // </entry> else { - xmlWriter().writeEndElement(); // </entry> + writeEndTag(); // </entry> } if (matchAhead(atom, Atom::ParaLeft)) skipAhead = 1; @@ -1473,26 +1656,26 @@ int DitaXmlGenerator::generateAtom(const Atom *atom, break; case Atom::Target: if (in_para) { - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </p> in_para = false; } - xmlWriter().writeStartElement("p"); + writeStartTag(DT_p); writeGuidAttribute(Doc::canonicalTitle(atom->string())); xmlWriter().writeAttribute("outputclass","target"); //xmlWriter().writeCharacters(protectEnc(atom->string())); - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </p> break; case Atom::UnhandledFormat: - xmlWriter().writeStartElement("b"); + writeStartTag(DT_b); xmlWriter().writeAttribute("outputclass","error"); xmlWriter().writeCharacters("<Missing DITAXML>"); - xmlWriter().writeEndElement(); // </b> + writeEndTag(); // </b> break; case Atom::UnknownCommand: - xmlWriter().writeStartElement("b"); + writeStartTag(DT_b); xmlWriter().writeAttribute("outputclass","error unknown-command"); writeCharacters(protectEnc(atom->string())); - xmlWriter().writeEndElement(); // </b> + writeEndTag(); // </b> break; case Atom::QmlText: case Atom::EndQmlText: @@ -1532,85 +1715,81 @@ DitaXmlGenerator::generateClassLikeNode(const InnerNode* inner, CodeMarker* mark */ generateHeader(inner, fullTitle); generateBrief(inner, marker); // <shortdesc> - - // not included: <prolog> - - xmlWriter().writeStartElement(CXXCLASSDETAIL); - xmlWriter().writeStartElement(CXXCLASSDEFINITION); + writeProlog(inner,marker); + + writeStartTag(DT_cxxClassDetail); + writeStartTag(DT_cxxClassDefinition); writeLocation(nsn); - xmlWriter().writeEndElement(); // <cxxClassDefinition> + writeEndTag(); // <cxxClassDefinition> - xmlWriter().writeStartElement("apiDesc"); - xmlWriter().writeAttribute("spectitle",title); + enterApiDesc(QString(),title); Text brief = nsn->doc().briefText(); // zzz if (!brief.isEmpty()) { - xmlWriter().writeStartElement("p"); + writeStartTag(DT_p); generateText(brief, nsn, marker); - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </p> } generateIncludes(nsn, marker); generateStatus(nsn, marker); generateThreadSafeness(nsn, marker); generateSince(nsn, marker); - xmlWriter().writeEndElement(); // </apiDesc> + + enterSection("h2","Detailed Description"); + generateBody(nsn, marker); + leaveSection(); + leaveSection(); // </apiDesc> bool needOtherSection = false; QList<Section> summarySections; summarySections = marker->sections(inner, CodeMarker::Summary, CodeMarker::Okay); - s = summarySections.begin(); - while (s != summarySections.end()) { - if (s->members.isEmpty() && s->reimpMembers.isEmpty()) { - if (!s->inherited.isEmpty()) - needOtherSection = true; - } - else { - QString attr; - if (!s->members.isEmpty()) { - xmlWriter().writeStartElement("section"); - attr = cleanRef((*s).name).toLower() + " redundant"; - xmlWriter().writeAttribute("outputclass",attr); - xmlWriter().writeStartElement("title"); - xmlWriter().writeAttribute("outputclass","h2"); - writeCharacters(protectEnc((*s).name)); - xmlWriter().writeEndElement(); // </title> - generateSection(s->members, inner, marker, CodeMarker::Summary); - generateSectionInheritedList(*s, inner, marker); - xmlWriter().writeEndElement(); // </section> - } - if (!s->reimpMembers.isEmpty()) { - QString name = QString("Reimplemented ") + (*s).name; - attr = cleanRef(name).toLower() + " redundant"; - xmlWriter().writeStartElement("section"); - xmlWriter().writeAttribute("outputclass",attr); - xmlWriter().writeStartElement("title"); - xmlWriter().writeAttribute("outputclass","h2"); - writeCharacters(protectEnc(name)); - xmlWriter().writeEndElement(); // </title> - generateSection(s->reimpMembers, inner, marker, CodeMarker::Summary); - generateSectionInheritedList(*s, inner, marker); - xmlWriter().writeEndElement(); // </section> - } - } - ++s; - } - if (needOtherSection) { - xmlWriter().writeStartElement("section"); - xmlWriter().writeAttribute("outputclass","additional-inherited-members redundant"); - xmlWriter().writeStartElement("title"); - xmlWriter().writeAttribute("outputclass","h3"); - xmlWriter().writeCharacters("Additional Inherited Members"); - xmlWriter().writeEndElement(); // </title> + if (!summarySections.isEmpty()) { + enterSection("redundant",QString()); s = summarySections.begin(); while (s != summarySections.end()) { - if (s->members.isEmpty()) - generateSectionInheritedList(*s, inner, marker); + if (s->members.isEmpty() && s->reimpMembers.isEmpty()) { + if (!s->inherited.isEmpty()) + needOtherSection = true; + } + else { + QString attr; + if (!s->members.isEmpty()) { + writeStartTag(DT_p); + attr = cleanRef((*s).name).toLower() + " h2"; + xmlWriter().writeAttribute("outputclass",attr); + writeCharacters(protectEnc((*s).name)); + writeEndTag(); // </title> + generateSection(s->members, inner, marker, CodeMarker::Summary); + generateSectionInheritedList(*s, inner, marker); + } + if (!s->reimpMembers.isEmpty()) { + QString name = QString("Reimplemented ") + (*s).name; + attr = cleanRef(name).toLower() + " h2"; + writeStartTag(DT_p); + xmlWriter().writeAttribute("outputclass",attr); + writeCharacters(protectEnc(name)); + writeEndTag(); // </title> + generateSection(s->reimpMembers, inner, marker, CodeMarker::Summary); + generateSectionInheritedList(*s, inner, marker); + } + } ++s; } - xmlWriter().writeEndElement(); // </section> + if (needOtherSection) { + writeStartTag(DT_p); + xmlWriter().writeAttribute("outputclass","h3"); + xmlWriter().writeCharacters("Additional Inherited Members"); + writeEndTag(); // </title> + s = summarySections.begin(); + while (s != summarySections.end()) { + if (s->members.isEmpty()) + generateSectionInheritedList(*s, inner, marker); + ++s; + } + } + leaveSection(); } - - writeDetailedDescription(nsn, marker, false, QString("Detailed Description")); - xmlWriter().writeEndElement(); // </cxxClassDetail> + + writeEndTag(); // </cxxClassDetail> // not included: <related-links> // not included: <cxxClassNested> @@ -1646,7 +1825,7 @@ DitaXmlGenerator::generateClassLikeNode(const InnerNode* inner, CodeMarker* mark generateLowStatusMembers(inner,marker,CodeMarker::Obsolete); generateLowStatusMembers(inner,marker,CodeMarker::Compat); - xmlWriter().writeEndElement(); // </cxxClass> + writeEndTag(); // </cxxClass> } else if (inner->type() == Node::Class) { const ClassNode* cn = const_cast<ClassNode*>(static_cast<const ClassNode*>(inner)); @@ -1656,34 +1835,32 @@ DitaXmlGenerator::generateClassLikeNode(const InnerNode* inner, CodeMarker* mark generateHeader(inner, fullTitle); generateBrief(inner, marker); // <shortdesc> - - // not included: <prolog> + writeProlog(inner,marker); - xmlWriter().writeStartElement(CXXCLASSDETAIL); - xmlWriter().writeStartElement(CXXCLASSDEFINITION); - xmlWriter().writeStartElement(CXXCLASSACCESSSPECIFIER); + writeStartTag(DT_cxxClassDetail); + writeStartTag(DT_cxxClassDefinition); + writeStartTag(DT_cxxClassAccessSpecifier); xmlWriter().writeAttribute("value",inner->accessString()); - xmlWriter().writeEndElement(); // <cxxClassAccessSpecifier> + writeEndTag(); // <cxxClassAccessSpecifier> if (cn->isAbstract()) { - xmlWriter().writeStartElement(CXXCLASSABSTRACT); + writeStartTag(DT_cxxClassAbstract); xmlWriter().writeAttribute("name","abstract"); xmlWriter().writeAttribute("value","abstract"); - xmlWriter().writeEndElement(); // </cxxClassAbstract> + writeEndTag(); // </cxxClassAbstract> } writeDerivations(cn, marker); // <cxxClassDerivations> // not included: <cxxClassTemplateParameters> writeLocation(cn); - xmlWriter().writeEndElement(); // <cxxClassDefinition> + writeEndTag(); // <cxxClassDefinition> - xmlWriter().writeStartElement("apiDesc"); - xmlWriter().writeAttribute("spectitle",title); + enterApiDesc(QString(),title); Text brief = cn->doc().briefText(); // zzz if (!brief.isEmpty()) { - xmlWriter().writeStartElement("p"); + writeStartTag(DT_p); generateText(brief, cn, marker); - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </p> } generateIncludes(cn, marker); generateStatus(cn, marker); @@ -1691,68 +1868,64 @@ DitaXmlGenerator::generateClassLikeNode(const InnerNode* inner, CodeMarker* mark generateInheritedBy(cn, marker); generateThreadSafeness(cn, marker); generateSince(cn, marker); - xmlWriter().writeEndElement(); // </apiDesc> + enterSection("h2","Detailed Description"); + generateBody(cn, marker); + leaveSection(); + leaveSection(); // </apiDesc> bool needOtherSection = false; QList<Section> summarySections; summarySections = marker->sections(inner, CodeMarker::Summary, CodeMarker::Okay); - s = summarySections.begin(); - while (s != summarySections.end()) { - if (s->members.isEmpty() && s->reimpMembers.isEmpty()) { - if (!s->inherited.isEmpty()) - needOtherSection = true; - } - else { - QString attr; - if (!s->members.isEmpty()) { - xmlWriter().writeStartElement("section"); - attr = cleanRef((*s).name).toLower() + " redundant"; - xmlWriter().writeAttribute("outputclass",attr); - xmlWriter().writeStartElement("title"); - xmlWriter().writeAttribute("outputclass","h2"); - writeCharacters(protectEnc((*s).name)); - xmlWriter().writeEndElement(); // </title> - generateSection(s->members, inner, marker, CodeMarker::Summary); - generateSectionInheritedList(*s, inner, marker); - xmlWriter().writeEndElement(); // </section> - } - if (!s->reimpMembers.isEmpty()) { - QString name = QString("Reimplemented ") + (*s).name; - attr = cleanRef(name).toLower() + " redundant"; - xmlWriter().writeStartElement("section"); - xmlWriter().writeAttribute("outputclass",attr); - xmlWriter().writeStartElement("title"); - xmlWriter().writeAttribute("outputclass","h2"); - writeCharacters(protectEnc(name)); - xmlWriter().writeEndElement(); // </title> - generateSection(s->reimpMembers, inner, marker, CodeMarker::Summary); - generateSectionInheritedList(*s, inner, marker); - xmlWriter().writeEndElement(); // </section> - } - } - ++s; - } - if (needOtherSection) { - xmlWriter().writeStartElement("section"); - xmlWriter().writeAttribute("outputclass","additional-inherited-members redundant"); - xmlWriter().writeStartElement("title"); - xmlWriter().writeAttribute("outputclass","h3"); - xmlWriter().writeCharacters("Additional Inherited Members"); - xmlWriter().writeEndElement(); // </title> + if (!summarySections.isEmpty()) { + enterSection("redundant",QString()); s = summarySections.begin(); while (s != summarySections.end()) { - if (s->members.isEmpty()) - generateSectionInheritedList(*s, inner, marker); + if (s->members.isEmpty() && s->reimpMembers.isEmpty()) { + if (!s->inherited.isEmpty()) + needOtherSection = true; + } + else { + QString attr; + if (!s->members.isEmpty()) { + writeStartTag(DT_p); + attr = cleanRef((*s).name).toLower() + " h2"; + xmlWriter().writeAttribute("outputclass",attr); + writeCharacters(protectEnc((*s).name)); + writeEndTag(); // </p> + generateSection(s->members, inner, marker, CodeMarker::Summary); + generateSectionInheritedList(*s, inner, marker); + } + if (!s->reimpMembers.isEmpty()) { + QString name = QString("Reimplemented ") + (*s).name; + attr = cleanRef(name).toLower() + " h2"; + writeStartTag(DT_p); + xmlWriter().writeAttribute("outputclass",attr); + writeCharacters(protectEnc(name)); + writeEndTag(); // </p> + generateSection(s->reimpMembers, inner, marker, CodeMarker::Summary); + generateSectionInheritedList(*s, inner, marker); + } + } ++s; } - xmlWriter().writeEndElement(); // </section> + if (needOtherSection) { + writeStartTag(DT_p); + xmlWriter().writeAttribute("outputclass","h3"); + xmlWriter().writeCharacters("Additional Inherited Members"); + writeEndTag(); // </p> + s = summarySections.begin(); + while (s != summarySections.end()) { + if (s->members.isEmpty()) + generateSectionInheritedList(*s, inner, marker); + ++s; + } + } + leaveSection(); } - - writeDetailedDescription(cn, marker, false, QString("Detailed Description")); // not included: <example> or <apiImpl> - xmlWriter().writeEndElement(); // </cxxClassDetail> + writeEndTag(); // </cxxClassDetail> // not included: <related-links> // not included: <cxxClassNested> @@ -1782,7 +1955,7 @@ DitaXmlGenerator::generateClassLikeNode(const InnerNode* inner, CodeMarker* mark generateLowStatusMembers(inner,marker,CodeMarker::Obsolete); generateLowStatusMembers(inner,marker,CodeMarker::Compat); - xmlWriter().writeEndElement(); // </cxxClass> + writeEndTag(); // </cxxClass> } else if ((inner->type() == Node::Fake) && (inner->subType() == Node::HeaderFile)) { const FakeNode* fn = const_cast<FakeNode*>(static_cast<const FakeNode*>(inner)); @@ -1798,78 +1971,78 @@ DitaXmlGenerator::generateClassLikeNode(const InnerNode* inner, CodeMarker* mark */ generateHeader(inner, fullTitle); generateBrief(inner, marker); // <shortdesc> - xmlWriter().writeStartElement(CXXCLASSDETAIL); - xmlWriter().writeStartElement("apiDesc"); - xmlWriter().writeAttribute("spectitle",title); + writeProlog(inner,marker); + + writeStartTag(DT_cxxClassDetail); + enterApiDesc(QString(),title); Text brief = fn->doc().briefText(); // zzz if (!brief.isEmpty()) { - xmlWriter().writeStartElement("p"); + writeStartTag(DT_p); generateText(brief, fn, marker); - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </p> } generateIncludes(fn, marker); generateStatus(fn, marker); generateThreadSafeness(fn, marker); generateSince(fn, marker); - xmlWriter().writeEndElement(); // </apiDesc> + generateSince(fn, marker); + enterSection("h2","Detailed Description"); + generateBody(fn, marker); + leaveSection(); + leaveSection(); // </apiDesc> bool needOtherSection = false; QList<Section> summarySections; summarySections = marker->sections(inner, CodeMarker::Summary, CodeMarker::Okay); - s = summarySections.begin(); - while (s != summarySections.end()) { - if (s->members.isEmpty() && s->reimpMembers.isEmpty()) { - if (!s->inherited.isEmpty()) - needOtherSection = true; - } - else { - QString attr; - if (!s->members.isEmpty()) { - xmlWriter().writeStartElement("section"); - attr = cleanRef((*s).name).toLower() + " redundant"; - xmlWriter().writeAttribute("outputclass",attr); - xmlWriter().writeStartElement("title"); - xmlWriter().writeAttribute("outputclass","h2"); - writeCharacters(protectEnc((*s).name)); - xmlWriter().writeEndElement(); // </title> - generateSection(s->members, inner, marker, CodeMarker::Summary); - generateSectionInheritedList(*s, inner, marker); - xmlWriter().writeEndElement(); // </section> - } - if (!s->reimpMembers.isEmpty()) { - QString name = QString("Reimplemented ") + (*s).name; - attr = cleanRef(name).toLower() + " redundant"; - xmlWriter().writeStartElement("section"); - xmlWriter().writeAttribute("outputclass",attr); - xmlWriter().writeStartElement("title"); - xmlWriter().writeAttribute("outputclass","h2"); - writeCharacters(protectEnc(name)); - xmlWriter().writeEndElement(); // </title> - generateSection(s->reimpMembers, inner, marker, CodeMarker::Summary); - generateSectionInheritedList(*s, inner, marker); - xmlWriter().writeEndElement(); // </section> - } - } - ++s; - } - if (needOtherSection) { - xmlWriter().writeStartElement("section"); - xmlWriter().writeAttribute("outputclass","additional-inherited-members redundant"); - xmlWriter().writeStartElement("title"); - xmlWriter().writeAttribute("outputclass","h3"); - xmlWriter().writeCharacters("Additional Inherited Members"); - xmlWriter().writeEndElement(); // </title> + if (!summarySections.isEmpty()) { + enterSection("redundant",QString()); s = summarySections.begin(); while (s != summarySections.end()) { - if (s->members.isEmpty()) - generateSectionInheritedList(*s, inner, marker); + if (s->members.isEmpty() && s->reimpMembers.isEmpty()) { + if (!s->inherited.isEmpty()) + needOtherSection = true; + } + else { + QString attr; + if (!s->members.isEmpty()) { + writeStartTag(DT_p); + attr = cleanRef((*s).name).toLower() + " h2"; + xmlWriter().writeAttribute("outputclass",attr); + writeCharacters(protectEnc((*s).name)); + writeEndTag(); // </p> + generateSection(s->members, inner, marker, CodeMarker::Summary); + generateSectionInheritedList(*s, inner, marker); + } + if (!s->reimpMembers.isEmpty()) { + QString name = QString("Reimplemented ") + (*s).name; + attr = cleanRef(name).toLower() + " h2"; + writeStartTag(DT_p); + xmlWriter().writeAttribute("outputclass",attr); + writeCharacters(protectEnc(name)); + writeEndTag(); // </p> + generateSection(s->reimpMembers, inner, marker, CodeMarker::Summary); + generateSectionInheritedList(*s, inner, marker); + } + } ++s; } - xmlWriter().writeEndElement(); // </section> + if (needOtherSection) { + enterSection("additional-inherited-members redundant",QString()); + writeStartTag(DT_p); + xmlWriter().writeAttribute("outputclass","h3"); + xmlWriter().writeCharacters("Additional Inherited Members"); + writeEndTag(); // </p> + s = summarySections.begin(); + while (s != summarySections.end()) { + if (s->members.isEmpty()) + generateSectionInheritedList(*s, inner, marker); + ++s; + } + } + leaveSection(); } - - writeDetailedDescription(fn, marker, false, QString("Detailed Description")); - xmlWriter().writeEndElement(); // </cxxClassDetail> + + writeEndTag(); // </cxxClassDetail> // not included: <related-links> // not included: <cxxClassNested> @@ -1904,7 +2077,7 @@ DitaXmlGenerator::generateClassLikeNode(const InnerNode* inner, CodeMarker* mark } generateLowStatusMembers(inner,marker,CodeMarker::Obsolete); generateLowStatusMembers(inner,marker,CodeMarker::Compat); - xmlWriter().writeEndElement(); // </cxxClass> + writeEndTag(); // </cxxClass> } else if ((inner->type() == Node::Fake) && (inner->subType() == Node::QmlClass)) { const QmlClassNode* qcn = const_cast<QmlClassNode*>(static_cast<const QmlClassNode*>(inner)); @@ -1917,76 +2090,74 @@ DitaXmlGenerator::generateClassLikeNode(const InnerNode* inner, CodeMarker* mark generateHeader(inner, fullTitle); generateBrief(inner, marker); // <shortdesc> + writeProlog(inner,marker); - // not included: <prolog> - - xmlWriter().writeStartElement(CXXCLASSDETAIL); - xmlWriter().writeStartElement("apiDesc"); - xmlWriter().writeAttribute("spectitle",title); + writeStartTag(DT_cxxClassDetail); + enterApiDesc(QString(),title); Text brief = qcn->doc().briefText(); // zzz if (!brief.isEmpty()) { - xmlWriter().writeStartElement("p"); + writeStartTag(DT_p); generateText(brief, qcn, marker); - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </p> } generateQmlInstantiates(qcn, marker); generateQmlInherits(qcn, marker); generateQmlInheritedBy(qcn, marker); generateSince(qcn, marker); - xmlWriter().writeEndElement(); // </apiDesc> + enterSection("h2","Detailed Description"); + generateBody(qcn, marker); + if (cn) + generateQmlText(cn->doc().body(), cn, marker, qcn->name()); + leaveSection(); + leaveSection(); // </apiDesc> QList<Section> summarySections; summarySections = marker->qmlSections(qcn,CodeMarker::Summary,0); - s = summarySections.begin(); - while (s != summarySections.end()) { - QString attr; - if (!s->members.isEmpty()) { - xmlWriter().writeStartElement("section"); - attr = cleanRef((*s).name).toLower() + " redundant"; - xmlWriter().writeAttribute("outputclass",attr); - xmlWriter().writeStartElement("title"); - xmlWriter().writeAttribute("outputclass","h2"); - writeCharacters(protectEnc((*s).name)); - xmlWriter().writeEndElement(); // </title> - generateQmlSummary(*s,qcn,marker); - //generateSection(s->members, inner, marker, CodeMarker::Summary); - //generateSectionInheritedList(*s, inner, marker); - xmlWriter().writeEndElement(); // </section> + if (!summarySections.isEmpty()) { + enterSection("redundant",QString()); + s = summarySections.begin(); + while (s != summarySections.end()) { + QString attr; + if (!s->members.isEmpty()) { + writeStartTag(DT_p); + attr = cleanRef((*s).name).toLower() + " h2"; + xmlWriter().writeAttribute("outputclass",attr); + writeCharacters(protectEnc((*s).name)); + writeEndTag(); // </p> + generateQmlSummary(*s,qcn,marker); + //generateSection(s->members, inner, marker, CodeMarker::Summary); + //generateSectionInheritedList(*s, inner, marker); + } + ++s; } - ++s; + leaveSection(); } - - writeDetailedDescription(qcn, marker, false, QString("Detailed Description")); - if (cn) - generateQmlText(cn->doc().body(), cn, marker, qcn->name()); QList<Section> detailSections; detailSections = marker->qmlSections(qcn,CodeMarker::Detailed,0); - s = detailSections.begin(); - while (s != detailSections.end()) { - if (!s->members.isEmpty()) { - QString attr; - inSection = true; - xmlWriter().writeStartElement("section"); - attr = cleanRef((*s).name).toLower(); - xmlWriter().writeAttribute("outputclass",attr); - xmlWriter().writeStartElement("title"); - xmlWriter().writeAttribute("outputclass","h2"); - writeCharacters(protectEnc((*s).name)); - xmlWriter().writeEndElement(); // </title> - NodeList::ConstIterator m = (*s).members.begin(); - while (m != (*s).members.end()) { - generateDetailedQmlMember(*m, qcn, marker); - ++m; + if (!detailSections.isEmpty()) { + enterSection("details",QString()); + s = detailSections.begin(); + while (s != detailSections.end()) { + if (!s->members.isEmpty()) { + QString attr; + writeStartTag(DT_p); + attr = cleanRef((*s).name).toLower() + " h2"; + xmlWriter().writeAttribute("outputclass",attr); + writeCharacters(protectEnc((*s).name)); + writeEndTag(); // </p> + NodeList::ConstIterator m = (*s).members.begin(); + while (m != (*s).members.end()) { + generateDetailedQmlMember(*m, qcn, marker); + ++m; + } } - xmlWriter().writeEndElement(); // </section> - inSection = false; + ++s; } - ++s; + leaveSection(); } - - xmlWriter().writeEndElement(); // </cxxClassDetail> - xmlWriter().writeEndElement(); // </cxxClass> + writeEndTag(); // </cxxClassDetail> + writeEndTag(); // </cxxClass> } } @@ -1996,12 +2167,13 @@ DitaXmlGenerator::generateClassLikeNode(const InnerNode* inner, CodeMarker* mark */ void DitaXmlGenerator::writeXrefListItem(const QString& link, const QString& text) { - xmlWriter().writeStartElement("li"); - xmlWriter().writeStartElement("xref"); + writeStartTag(DT_li); + writeStartTag(DT_xref); + // formathtml xmlWriter().writeAttribute("href",link); writeCharacters(text); - xmlWriter().writeEndElement(); // </xref> - xmlWriter().writeEndElement(); // </li> + writeEndTag(); // </xref> + writeEndTag(); // </li> } /*! @@ -2010,45 +2182,31 @@ void DitaXmlGenerator::writeXrefListItem(const QString& link, const QString& tex */ void DitaXmlGenerator::generateFakeNode(const FakeNode* fake, CodeMarker* marker) { - SubTitleSize subTitleSize = LargeSubTitle; QList<Section> sections; QList<Section>::const_iterator s; QString fullTitle = fake->fullTitle(); - QString htmlTitle = fullTitle; - if (fake->subType() == Node::File && !fake->subTitle().isEmpty()) { - subTitleSize = SmallSubTitle; - htmlTitle += " (" + fake->subTitle() + ")"; - } - else if (fake->subType() == Node::QmlBasicType) { + if (fake->subType() == Node::QmlBasicType) { fullTitle = "QML Basic Type: " + fullTitle; - htmlTitle = fullTitle; } generateHeader(fake, fullTitle); generateBrief(fake, marker); // <shortdesc> - xmlWriter().writeStartElement("body"); + writeProlog(fake, marker); + + writeStartTag(DT_body); + enterSection(QString(),QString()); if (fake->subType() == Node::Module) { generateStatus(fake, marker); if (moduleNamespaceMap.contains(fake->name())) { - xmlWriter().writeStartElement("section"); - xmlWriter().writeAttribute("outputclass","namespaces"); - xmlWriter().writeStartElement("title"); - xmlWriter().writeAttribute("outputclass","h2"); - xmlWriter().writeCharacters("Namespaces"); - xmlWriter().writeEndElement(); // </title> + enterSection("h2","Namespaces"); generateAnnotatedList(fake, marker, moduleNamespaceMap[fake->name()]); - xmlWriter().writeEndElement(); // </section> + leaveSection(); } if (moduleClassMap.contains(fake->name())) { - xmlWriter().writeStartElement("section"); - xmlWriter().writeAttribute("outputclass","classes"); - xmlWriter().writeStartElement("title"); - xmlWriter().writeAttribute("outputclass","h2"); - xmlWriter().writeCharacters("Classes"); - xmlWriter().writeEndElement(); // </title> + enterSection("h2","Classes"); generateAnnotatedList(fake, marker, moduleClassMap[fake->name()]); - xmlWriter().writeEndElement(); // </section> + leaveSection(); } } @@ -2056,11 +2214,11 @@ void DitaXmlGenerator::generateFakeNode(const FakeNode* fake, CodeMarker* marker if (fake->subType() == Node::File) { Text text; Quoter quoter; - xmlWriter().writeStartElement("p"); + writeStartTag(DT_p); xmlWriter().writeAttribute("outputclass", "small-subtitle"); text << fake->subTitle(); generateText(text, fake, marker); - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </p> Doc::quoteFromFile(fake->doc().location(), quoter, fake->name()); QString code = quoter.quoteTo(fake->location(), "", ""); text.clear(); @@ -2070,10 +2228,12 @@ void DitaXmlGenerator::generateFakeNode(const FakeNode* fake, CodeMarker* marker } else { if (fake->subType() == Node::Module) { - writeDetailedDescription(fake, marker, false, QString("Detailed Description")); + enterSection("h2","Detailed Description"); + generateBody(fake, marker); + leaveSection(); } else - writeDetailedDescription(fake, marker, false, QString()); + generateBody(fake, marker); generateAlsoList(fake, marker); if (!fake->groupMembers().isEmpty()) { @@ -2085,9 +2245,10 @@ void DitaXmlGenerator::generateFakeNode(const FakeNode* fake, CodeMarker* marker generateAnnotatedList(fake, marker, groupMembersMap); } } - xmlWriter().writeEndElement(); // </body> + leaveSection(); // </section> + writeEndTag(); // </body> writeRelatedLinks(fake, marker); - xmlWriter().writeEndElement(); // </topic> + writeEndTag(); // </topic> } /*! @@ -2102,13 +2263,13 @@ void DitaXmlGenerator::writeLink(const Node* node, { if (node) { QString link = fileName(node) + "#" + node->guid(); - xmlWriter().writeStartElement("link"); + writeStartTag(DT_link); xmlWriter().writeAttribute("href", link); xmlWriter().writeAttribute("role", role); - xmlWriter().writeStartElement("linktext"); + writeStartTag(DT_linktext); writeCharacters(text); - xmlWriter().writeEndElement(); // </linktext> - xmlWriter().writeEndElement(); // </link> + writeEndTag(); // </linktext> + writeEndTag(); // </link> } } @@ -2124,7 +2285,7 @@ void DitaXmlGenerator::writeRelatedLinks(const FakeNode* node, CodeMarker* marke const Node* linkNode = 0; QPair<QString,QString> linkPair; if (node && !node->links().empty()) { - xmlWriter().writeStartElement("related-links"); + writeStartTag(DT_relatedLinks); if (node->links().contains(Node::PreviousLink)) { linkPair = node->links()[Node::PreviousLink]; linkNode = findNodeForTarget(linkPair.first, node, marker); @@ -2140,7 +2301,7 @@ void DitaXmlGenerator::writeRelatedLinks(const FakeNode* node, CodeMarker* marke linkNode = findNodeForTarget(linkPair.first, node, marker); writeLink(linkNode, linkPair.second, "parent"); } - xmlWriter().writeEndElement(); // </related-links> + writeEndTag(); // </related-links> } } @@ -2166,59 +2327,59 @@ void DitaXmlGenerator::generateHeader(const Node* node, if (!node) return; + DitaTag mainTag = DT_cxxClass; + DitaTag nameTag = DT_apiName; QString doctype; - QString mainElement; - QString nameElement; QString dtd; QString base; QString version; QString outputclass; if (node->type() == Node::Class) { - mainElement = "cxxClass"; - nameElement = "apiName"; + mainTag = DT_cxxClass; + nameTag = DT_apiName; dtd = "dtd/cxxClass.dtd"; version = "0.6.0"; - doctype = "<!DOCTYPE " + mainElement + + doctype = "<!DOCTYPE " + ditaTags[mainTag] + " PUBLIC \"-//NOKIA//DTD DITA C++ API Class Reference Type v" + version + "//EN\" \"" + dtd + "\">"; } else if (node->type() == Node::Namespace) { - mainElement = "cxxClass"; - nameElement = "apiName"; + mainTag = DT_cxxClass; + nameTag = DT_apiName; dtd = "dtd/cxxClass.dtd"; version = "0.6.0"; - doctype = "<!DOCTYPE " + mainElement + + doctype = "<!DOCTYPE " + ditaTags[mainTag] + " PUBLIC \"-//NOKIA//DTD DITA C++ API Class Reference Type v" + version + "//EN\" \"" + dtd + "\">"; outputclass = "namespace"; } else if (node->type() == Node::Fake || subpage) { if (node->subType() == Node::HeaderFile) { - mainElement = "cxxClass"; - nameElement = "apiName"; + mainTag = DT_cxxClass; + nameTag = DT_apiName; dtd = "dtd/cxxClass.dtd"; version = "0.6.0"; - doctype = "<!DOCTYPE " + mainElement + + doctype = "<!DOCTYPE " + ditaTags[mainTag] + " PUBLIC \"-//NOKIA//DTD DITA C++ API Class Reference Type v" + version + "//EN\" \"" + dtd + "\">"; outputclass = "headerfile"; } else if (node->subType() == Node::QmlClass) { - mainElement = "cxxClass"; - nameElement = "apiName"; + mainTag = DT_cxxClass; + nameTag = DT_apiName; dtd = "dtd/cxxClass.dtd"; version = "0.6.0"; - doctype = "<!DOCTYPE " + mainElement + + doctype = "<!DOCTYPE " + ditaTags[mainTag] + " PUBLIC \"-//NOKIA//DTD DITA C++ API Class Reference Type v" + version + "//EN\" \"" + dtd + "\">"; outputclass = "QML-class"; } else { - mainElement = "topic"; - nameElement = "title"; + mainTag = DT_topic; + nameTag = DT_title; dtd = "dtd/topic.dtd"; - doctype = "<!DOCTYPE " + mainElement + + doctype = "<!DOCTYPE " + ditaTags[mainTag] + " PUBLIC \"-//OASIS//DTD DITA Topic//EN\" \"" + dtd + "\">"; switch (node->subType()) { case Node::Page: @@ -2250,13 +2411,13 @@ void DitaXmlGenerator::generateHeader(const Node* node, xmlWriter().writeDTD(doctype); xmlWriter().writeComment(node->doc().location().fileName()); - xmlWriter().writeStartElement(mainElement); + writeStartTag(mainTag); xmlWriter().writeAttribute("id",node->guid()); if (!outputclass.isEmpty()) xmlWriter().writeAttribute("outputclass",outputclass); - xmlWriter().writeStartElement(nameElement); // <title> or <apiName> + writeStartTag(nameTag); // <title> or <apiName> writeCharacters(name); - xmlWriter().writeEndElement(); // </title> or </apiName> + writeEndTag(); // </title> or </apiName> } /*! @@ -2277,9 +2438,9 @@ void DitaXmlGenerator::generateBrief(const Node* node, CodeMarker* marker) void DitaXmlGenerator::generateIncludes(const InnerNode* inner, CodeMarker* marker) { if (!inner->includes().isEmpty()) { - xmlWriter().writeStartElement("codeblock"); + writeStartTag(DT_codeblock); writeText(marker->markedUpIncludes(inner->includes()), marker, inner); - xmlWriter().writeEndElement(); // </codeblock> + writeEndTag(); // </codeblock> } } @@ -2551,20 +2712,20 @@ void DitaXmlGenerator::generateClassHierarchy(const Node* relative, QStack<NodeMap > stack; stack.push(topLevel); - xmlWriter().writeStartElement("ul"); + writeStartTag(DT_ul); while (!stack.isEmpty()) { if (stack.top().isEmpty()) { stack.pop(); - xmlWriter().writeEndElement(); // </ul> + writeEndTag(); // </ul> if (!stack.isEmpty()) - xmlWriter().writeEndElement(); // </li> + writeEndTag(); // </li> } else { const ClassNode *child = static_cast<const ClassNode *>(*stack.top().begin()); - xmlWriter().writeStartElement("li"); + writeStartTag(DT_li); generateFullName(child, relative, marker); - xmlWriter().writeEndElement(); // </li> + writeEndTag(); // </li> stack.top().erase(stack.top().begin()); NodeMap newTop; @@ -2574,8 +2735,8 @@ void DitaXmlGenerator::generateClassHierarchy(const Node* relative, } if (!newTop.isEmpty()) { stack.push(newTop); - xmlWriter().writeStartElement("li"); - xmlWriter().writeStartElement("ul"); + writeStartTag(DT_li); + writeStartTag(DT_ul); } } } @@ -2591,11 +2752,11 @@ void DitaXmlGenerator::generateAnnotatedList(const Node* relative, { if (nodeMap.isEmpty()) return; - xmlWriter().writeStartElement("table"); + writeStartTag(DT_table); xmlWriter().writeAttribute("outputclass","annotated"); - xmlWriter().writeStartElement("tgroup"); + writeStartTag(DT_tgroup); xmlWriter().writeAttribute("cols","2"); - xmlWriter().writeStartElement("tbody"); + writeStartTag(DT_tbody); foreach (const QString& name, nodeMap.keys()) { const Node* node = nodeMap[name]; @@ -2603,35 +2764,35 @@ void DitaXmlGenerator::generateAnnotatedList(const Node* relative, if (node->status() == Node::Obsolete) continue; - xmlWriter().writeStartElement("row"); - xmlWriter().writeStartElement("entry"); - xmlWriter().writeStartElement("p"); + writeStartTag(DT_row); + writeStartTag(DT_entry); + writeStartTag(DT_p); generateFullName(node, relative, marker); - xmlWriter().writeEndElement(); // </p> - xmlWriter().writeEndElement(); // <entry> + writeEndTag(); // </p> + writeEndTag(); // <entry> if (!(node->type() == Node::Fake)) { Text brief = node->doc().trimmedBriefText(name); if (!brief.isEmpty()) { - xmlWriter().writeStartElement("entry"); - xmlWriter().writeStartElement("p"); + writeStartTag(DT_entry); + writeStartTag(DT_p); generateText(brief, node, marker); - xmlWriter().writeEndElement(); // </p> - xmlWriter().writeEndElement(); // <entry> + writeEndTag(); // </p> + writeEndTag(); // <entry> } } else { - xmlWriter().writeStartElement("entry"); - xmlWriter().writeStartElement("p"); + writeStartTag(DT_entry); + writeStartTag(DT_p); writeCharacters(protectEnc(node->doc().briefText().toString())); // zzz - xmlWriter().writeEndElement(); // </p> - xmlWriter().writeEndElement(); // <entry> + writeEndTag(); // </p> + writeEndTag(); // <entry> } - xmlWriter().writeEndElement(); // </row> + writeEndTag(); // </row> } - xmlWriter().writeEndElement(); // </tbody> - xmlWriter().writeEndElement(); // </tgroup> - xmlWriter().writeEndElement(); // </table> + writeEndTag(); // </tbody> + writeEndTag(); // </tgroup> + writeEndTag(); // </table> } /*! @@ -2768,26 +2929,27 @@ void DitaXmlGenerator::generateCompactList(const Node* relative, Output the alphabet as a row of links. */ if (includeAlphabet) { - xmlWriter().writeStartElement("p"); + writeStartTag(DT_p); xmlWriter().writeAttribute("outputclass","alphabet"); for (int i = 0; i < 26; i++) { QChar ch('a' + i); if (usedParagraphNames.contains(char('a' + i))) { - xmlWriter().writeStartElement("xref"); + writeStartTag(DT_xref); + // formathtml QString guid = lookupGuid(outFileName(),QString(ch)); QString attr = outFileName() + QString("#%1").arg(guid); xmlWriter().writeAttribute("href", attr); xmlWriter().writeCharacters(QString(ch.toUpper())); - xmlWriter().writeEndElement(); // </xref> + writeEndTag(); // </xref> } } - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </p> } /* Output a <p> element to contain all the <dl> elements. */ - xmlWriter().writeStartElement("p"); + writeStartTag(DT_p); xmlWriter().writeAttribute("outputclass","compactlist"); for (int i=0; i<classMap.count()-1; i++) { @@ -2802,25 +2964,25 @@ void DitaXmlGenerator::generateCompactList(const Node* relative, */ if (curParOffset == 0) { if (i > 0) { - xmlWriter().writeEndElement(); // </dlentry> - xmlWriter().writeEndElement(); // </dl> + writeEndTag(); // </dlentry> + writeEndTag(); // </dl> } - xmlWriter().writeStartElement("dl"); - xmlWriter().writeStartElement("dlentry"); - xmlWriter().writeStartElement("dt"); + writeStartTag(DT_dl); + writeStartTag(DT_dlentry); + writeStartTag(DT_dt); if (includeAlphabet) { QChar c = paragraphName[curParNr][0].toLower(); writeGuidAttribute(QString(c)); } xmlWriter().writeAttribute("outputclass","sublist-header"); xmlWriter().writeCharacters(paragraphName[curParNr]); - xmlWriter().writeEndElement(); // </dt> + writeEndTag(); // </dt> } /* Output a <dd> for the current offset in the current paragraph. */ - xmlWriter().writeStartElement("dd"); + writeStartTag(DT_dd); if ((curParNr < NumParagraphs) && !paragraphName[curParNr].isEmpty()) { NodeMap::Iterator it; @@ -2832,7 +2994,8 @@ void DitaXmlGenerator::generateCompactList(const Node* relative, Previously, we used generateFullName() for this, but we require some special formatting. */ - xmlWriter().writeStartElement("xref"); + writeStartTag(DT_xref); + // formathtml xmlWriter().writeAttribute("href",linkForNode(it.value(), relative)); QStringList pieces; @@ -2841,19 +3004,19 @@ void DitaXmlGenerator::generateCompactList(const Node* relative, else pieces = fullName(it.value(), relative, marker).split("::"); xmlWriter().writeCharacters(protectEnc(pieces.last())); - xmlWriter().writeEndElement(); // </xref> + writeEndTag(); // </xref> if (pieces.size() > 1) { xmlWriter().writeCharacters(" ("); generateFullName(it.value()->parent(),relative,marker); xmlWriter().writeCharacters(")"); } } - xmlWriter().writeEndElement(); // </dd> + writeEndTag(); // </dd> curParOffset++; } - xmlWriter().writeEndElement(); // </dlentry> - xmlWriter().writeEndElement(); // </dl> - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </dlentry> + writeEndTag(); // </dl> + writeEndTag(); // </p> } /*! @@ -2862,34 +3025,35 @@ void DitaXmlGenerator::generateCompactList(const Node* relative, void DitaXmlGenerator::generateFunctionIndex(const Node* relative, CodeMarker* marker) { - xmlWriter().writeStartElement("p"); + writeStartTag(DT_p); xmlWriter().writeAttribute("outputclass","alphabet"); for (int i = 0; i < 26; i++) { QChar ch('a' + i); - xmlWriter().writeStartElement("xref"); + writeStartTag(DT_xref); + // formathtml QString guid = lookupGuid(outFileName(),QString(ch)); QString attr = outFileName() + QString("#%1").arg(guid); xmlWriter().writeAttribute("href", attr); xmlWriter().writeCharacters(QString(ch.toUpper())); - xmlWriter().writeEndElement(); // </xref> + writeEndTag(); // </xref> } - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </p> char nextLetter = 'a'; char currentLetter; - xmlWriter().writeStartElement("ul"); + writeStartTag(DT_ul); QMap<QString, NodeMap >::ConstIterator f = funcIndex.begin(); while (f != funcIndex.end()) { - xmlWriter().writeStartElement("li"); + writeStartTag(DT_li); currentLetter = f.key()[0].unicode(); while (islower(currentLetter) && currentLetter >= nextLetter) { - xmlWriter().writeStartElement("p"); + writeStartTag(DT_p); writeGuidAttribute(QString(nextLetter)); xmlWriter().writeAttribute("outputclass","target"); xmlWriter().writeCharacters(QString(nextLetter)); - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </p> nextLetter++; } xmlWriter().writeCharacters(protectEnc(f.key())); @@ -2900,10 +3064,10 @@ void DitaXmlGenerator::generateFunctionIndex(const Node* relative, generateFullName((*s)->parent(), relative, marker, *s); ++s; } - xmlWriter().writeEndElement(); // </li> + writeEndTag(); // </li> ++f; } - xmlWriter().writeEndElement(); // </ul> + writeEndTag(); // </ul> } /*! @@ -2916,14 +3080,14 @@ void DitaXmlGenerator::generateLegaleseList(const Node* relative, while (it != legaleseTexts.end()) { Text text = it.key(); generateText(text, relative, marker); - xmlWriter().writeStartElement("ul"); + writeStartTag(DT_ul); do { - xmlWriter().writeStartElement("li"); + writeStartTag(DT_li); generateFullName(it.value(), relative, marker); - xmlWriter().writeEndElement(); // </li> + writeEndTag(); // </li> ++it; } while (it != legaleseTexts.end() && it.key() == text); - xmlWriter().writeEndElement(); //</ul> + writeEndTag(); //</ul> } } @@ -3044,50 +3208,53 @@ void DitaXmlGenerator::generateOverviewList(const Node* relative, CodeMarker* /* if (!fakeNodeMap.isEmpty()) { foreach (const QString& groupTitle, groupTitlesMap.keys()) { const FakeNode* groupNode = groupTitlesMap[groupTitle]; - xmlWriter().writeStartElement("p"); + writeStartTag(DT_p); xmlWriter().writeAttribute("outputclass","h3"); - xmlWriter().writeStartElement("xref"); + writeStartTag(DT_xref); + // formathtml xmlWriter().writeAttribute("href",linkForNode(groupNode, relative)); writeCharacters(protectEnc(groupNode->fullTitle())); - xmlWriter().writeEndElement(); // </xref> - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </xref> + writeEndTag(); // </p> if (fakeNodeMap[groupNode].count() == 0) continue; - xmlWriter().writeStartElement("ul"); + writeStartTag(DT_ul); foreach (const FakeNode* fakeNode, fakeNodeMap[groupNode]) { QString title = fakeNode->fullTitle(); if (title.startsWith("The ")) title.remove(0, 4); - xmlWriter().writeStartElement("li"); - xmlWriter().writeStartElement("xref"); + writeStartTag(DT_li); + writeStartTag(DT_xref); + // formathtml xmlWriter().writeAttribute("href",linkForNode(fakeNode, relative)); writeCharacters(protectEnc(title)); - xmlWriter().writeEndElement(); // </xref> - xmlWriter().writeEndElement(); // </li> + writeEndTag(); // </xref> + writeEndTag(); // </li> } - xmlWriter().writeEndElement(); // </ul> + writeEndTag(); // </ul> } } if (!uncategorizedNodeMap.isEmpty()) { - xmlWriter().writeStartElement("p"); + writeStartTag(DT_p); xmlWriter().writeAttribute("outputclass","h3"); xmlWriter().writeCharacters("Miscellaneous"); - xmlWriter().writeEndElement(); // </p> - xmlWriter().writeStartElement("ul"); + writeEndTag(); // </p> + writeStartTag(DT_ul); foreach (const FakeNode *fakeNode, uncategorizedNodeMap) { QString title = fakeNode->fullTitle(); if (title.startsWith("The ")) title.remove(0, 4); - xmlWriter().writeStartElement("li"); - xmlWriter().writeStartElement("xref"); + writeStartTag(DT_li); + writeStartTag(DT_xref); + // formathtml xmlWriter().writeAttribute("href",linkForNode(fakeNode, relative)); writeCharacters(protectEnc(title)); - xmlWriter().writeEndElement(); // </xref> - xmlWriter().writeEndElement(); // </li> + writeEndTag(); // </xref> + writeEndTag(); // </li> } - xmlWriter().writeEndElement(); // </ul> + writeEndTag(); // </ul> } } @@ -3102,18 +3269,18 @@ void DitaXmlGenerator::generateSection(const NodeList& nl, CodeMarker::SynopsisStyle style) { if (!nl.isEmpty()) { - xmlWriter().writeStartElement("ul"); + writeStartTag(DT_ul); NodeList::ConstIterator m = nl.begin(); while (m != nl.end()) { if ((*m)->access() != Node::Private) { - xmlWriter().writeStartElement("li"); + writeStartTag(DT_li); QString marked = getMarkedUpSynopsis(*m, relative, marker, style); writeText(marked, marker, relative); - xmlWriter().writeEndElement(); // </li> + writeEndTag(); // </li> } ++m; } - xmlWriter().writeEndElement(); // </ul> + writeEndTag(); // </ul> } } @@ -3126,10 +3293,10 @@ void DitaXmlGenerator::generateSectionInheritedList(const Section& section, { if (section.inherited.isEmpty()) return; - xmlWriter().writeStartElement("ul"); + writeStartTag(DT_ul); QList<QPair<ClassNode*,int> >::ConstIterator p = section.inherited.begin(); while (p != section.inherited.end()) { - xmlWriter().writeStartElement("li"); + writeStartTag(DT_li); QString text; text.setNum((*p).second); text += " "; @@ -3139,18 +3306,19 @@ void DitaXmlGenerator::generateSectionInheritedList(const Section& section, text += section.pluralMember; text += " inherited from "; writeCharacters(text); - xmlWriter().writeStartElement("xref"); + writeStartTag(DT_xref); + // formathtml // zzz text = fileName((*p).first) + "#"; text += DitaXmlGenerator::cleanRef(section.name.toLower()); xmlWriter().writeAttribute("href",text); text = protectEnc(marker->plainFullName((*p).first, relative)); writeCharacters(text); - xmlWriter().writeEndElement(); // </xref> - xmlWriter().writeEndElement(); // </li> + writeEndTag(); // </xref> + writeEndTag(); // </li> ++p; } - xmlWriter().writeEndElement(); // </ul> + writeEndTag(); // </ul> } /*! @@ -3299,18 +3467,18 @@ void DitaXmlGenerator::writeText(const QString& markedCode, writeCharacters(html); html.clear(); } - xmlWriter().writeStartElement("i"); + writeStartTag(DT_i); writeCharacters(arg.toString()); - xmlWriter().writeEndElement(); // </i> + writeEndTag(); // </i> } else if (k == 5) { // <@extra> if (!html.isEmpty()) { writeCharacters(html); html.clear(); } - xmlWriter().writeStartElement("tt"); + writeStartTag(DT_tt); writeCharacters(arg.toString()); - xmlWriter().writeEndElement(); // </tt> + writeEndTag(); // </tt> } else { if (!html.isEmpty()) { @@ -3362,10 +3530,10 @@ void DitaXmlGenerator::generateLink(const Atom* atom, writeCharacters(protectEnc(atom->string().left(k))); if (link.isEmpty()) { if (showBrokenLinks) - xmlWriter().writeEndElement(); // </i> + writeEndTag(); // </i> } else - xmlWriter().writeEndElement(); // </xref> + writeEndTag(); // </xref> inLink = false; writeCharacters(protectEnc(atom->string().mid(k))); } @@ -3374,12 +3542,12 @@ void DitaXmlGenerator::generateLink(const Atom* atom, bool func = atom->string().endsWith("()"); bool tt = (func || atom->string().contains(camelCase)); if (tt) - xmlWriter().writeStartElement("tt"); + writeStartTag(DT_tt); if (func) writeCharacters(protectEnc(atom->string().left(atom->string().length() - 2))); else writeCharacters(protectEnc(atom->string())); - xmlWriter().writeEndElement(); // </tt> + writeEndTag(); // </tt> } else writeCharacters(protectEnc(atom->string())); @@ -3714,11 +3882,12 @@ void DitaXmlGenerator::generateFullName(const Node* apparentNode, { if (actualNode == 0) actualNode = apparentNode; - xmlWriter().writeStartElement("xref"); + writeStartTag(DT_xref); + // formathtml QString href = linkForNode(actualNode, relative); xmlWriter().writeAttribute("href",href); writeCharacters(protectEnc(fullName(apparentNode, relative, marker))); - xmlWriter().writeEndElement(); // </xref> + writeEndTag(); // </xref> } void DitaXmlGenerator::findAllClasses(const InnerNode* node) @@ -3902,6 +4071,11 @@ void DitaXmlGenerator::findAllNamespaces(const InnerNode* node) } } +/*! + We're writing an attribute that indicates that the text + data is a heading, hence, h1, h2, h3... etc, and we must + decide which number to use. + */ int DitaXmlGenerator::hOffset(const Node* node) { switch (node->type()) { @@ -4142,7 +4316,8 @@ void DitaXmlGenerator::beginLink(const QString& link) this->link = link; if (link.isEmpty()) return; - xmlWriter().writeStartElement("xref"); + writeStartTag(DT_xref); + // formathtml xmlWriter().writeAttribute("href",link); inLink = true; } @@ -4152,15 +4327,15 @@ void DitaXmlGenerator::endLink() if (inLink) { if (link.isEmpty()) { if (showBrokenLinks) - xmlWriter().writeEndElement(); // </i> + writeEndTag(); // </i> } else { if (inObsoleteLink) { - xmlWriter().writeStartElement("sup"); + writeStartTag(DT_sup); xmlWriter().writeCharacters("(obsolete)"); - xmlWriter().writeEndElement(); // </sup> + writeEndTag(); // </sup> } - xmlWriter().writeEndElement(); // </xref> + writeEndTag(); // </xref> } } inLink = false; @@ -4178,16 +4353,16 @@ void DitaXmlGenerator::generateQmlSummary(const Section& section, CodeMarker* marker) { if (!section.members.isEmpty()) { - xmlWriter().writeStartElement("ul"); + writeStartTag(DT_ul); NodeList::ConstIterator m; m = section.members.begin(); while (m != section.members.end()) { - xmlWriter().writeStartElement("li"); + writeStartTag(DT_li); generateQmlItem(*m,relative,marker,true); - xmlWriter().writeEndElement(); // </li> + writeEndTag(); // </li> ++m; } - xmlWriter().writeEndElement(); // </ul> + writeEndTag(); // </ul> } } @@ -4205,11 +4380,11 @@ void DitaXmlGenerator::generateDetailedQmlMember(const Node* node, if (node->subType() == Node::QmlPropertyGroup) { const QmlPropGroupNode* qpgn = static_cast<const QmlPropGroupNode*>(node); NodeList::ConstIterator p = qpgn->childNodes().begin(); - xmlWriter().writeStartElement("ul"); + writeStartTag(DT_ul); while (p != qpgn->childNodes().end()) { if ((*p)->type() == Node::QmlProperty) { qpn = static_cast<const QmlPropertyNode*>(*p); - xmlWriter().writeStartElement("li"); + writeStartTag(DT_li); writeGuidAttribute((Node*)qpn); QString attr; if (!qpn->isWritable(myTree)) @@ -4222,31 +4397,31 @@ void DitaXmlGenerator::generateDetailedQmlMember(const Node* node, if (!attr.isEmpty()) xmlWriter().writeAttribute("outputclass",attr); generateQmlItem(qpn, relative, marker, false); - xmlWriter().writeEndElement(); // </li> + writeEndTag(); // </li> } ++p; } - xmlWriter().writeEndElement(); // </ul> + writeEndTag(); // </ul> } else if (node->type() == Node::QmlSignal) { Node* n = const_cast<Node*>(node); - xmlWriter().writeStartElement("ul"); - xmlWriter().writeStartElement("li"); + writeStartTag(DT_ul); + writeStartTag(DT_li); writeGuidAttribute(n); marked = getMarkedUpSynopsis(n, relative, marker, CodeMarker::Detailed); writeText(marked, marker, relative); - xmlWriter().writeEndElement(); // </li> - xmlWriter().writeEndElement(); // </ul> + writeEndTag(); // </li> + writeEndTag(); // </ul> } else if (node->type() == Node::QmlMethod) { Node* n = const_cast<Node*>(node); - xmlWriter().writeStartElement("ul"); - xmlWriter().writeStartElement("li"); + writeStartTag(DT_ul); + writeStartTag(DT_li); writeGuidAttribute(n); marked = getMarkedUpSynopsis(n, relative, marker, CodeMarker::Detailed); writeText(marked, marker, relative); - xmlWriter().writeEndElement(); // </li> - xmlWriter().writeEndElement(); // </ul> + writeEndTag(); // </li> + writeEndTag(); // </ul> } generateStatus(node, marker); generateBody(node, marker); @@ -4270,7 +4445,7 @@ void DitaXmlGenerator::generateQmlInherits(const QmlClassNode* cn, const Node* n = myTree->findNode(strList,Node::Fake); if (n && n->subType() == Node::QmlClass) { const QmlClassNode* qcn = static_cast<const QmlClassNode*>(n); - xmlWriter().writeStartElement("p"); + writeStartTag(DT_p); xmlWriter().writeAttribute("outputclass","inherits"); Text text; text << "[Inherits "; @@ -4280,7 +4455,7 @@ void DitaXmlGenerator::generateQmlInherits(const QmlClassNode* cn, text << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK); text << "]"; generateText(text, cn, marker); - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </p> } } } @@ -4318,7 +4493,7 @@ void DitaXmlGenerator::generateQmlInstantiates(const QmlClassNode* qcn, { const ClassNode* cn = qcn->classNode(); if (cn && (cn->status() != Node::Internal)) { - xmlWriter().writeStartElement("p"); + writeStartTag(DT_p); xmlWriter().writeAttribute("outputclass","instantiates"); Text text; text << "["; @@ -4333,7 +4508,7 @@ void DitaXmlGenerator::generateQmlInstantiates(const QmlClassNode* qcn, text << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK); text << "]"; generateText(text, qcn, marker); - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </p> } } @@ -4350,7 +4525,7 @@ void DitaXmlGenerator::generateInstantiatedBy(const ClassNode* cn, if (cn && cn->status() != Node::Internal && !cn->qmlElement().isEmpty()) { const Node* n = myTree->root()->findNode(cn->qmlElement(),Node::Fake); if (n && n->subType() == Node::QmlClass) { - xmlWriter().writeStartElement("p"); + writeStartTag(DT_p); xmlWriter().writeAttribute("outputclass","instantiated-by"); Text text; text << "["; @@ -4365,7 +4540,7 @@ void DitaXmlGenerator::generateInstantiatedBy(const ClassNode* cn, text << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK); text << "]"; generateText(text, cn, marker); - xmlWriter().writeEndElement(); // </p> + writeEndTag(); // </p> } } } @@ -4421,32 +4596,32 @@ void DitaXmlGenerator::writeDerivations(const ClassNode* cn, CodeMarker* marker) int index; if (!cn->baseClasses().isEmpty()) { - xmlWriter().writeStartElement(CXXCLASSDERIVATIONS); + writeStartTag(DT_cxxClassDerivations); r = cn->baseClasses().begin(); index = 0; while (r != cn->baseClasses().end()) { - xmlWriter().writeStartElement(CXXCLASSDERIVATION); - xmlWriter().writeStartElement(CXXCLASSDERIVATIONACCESSSPECIFIER); + writeStartTag(DT_cxxClassDerivation); + writeStartTag(DT_cxxClassDerivationAccessSpecifier); xmlWriter().writeAttribute("value",(*r).accessString()); - xmlWriter().writeEndElement(); // </cxxClassDerivationAccessSpecifier> + writeEndTag(); // </cxxClassDerivationAccessSpecifier> // not included: <cxxClassDerivationVirtual> - xmlWriter().writeStartElement(CXXCLASSBASECLASS); + writeStartTag(DT_cxxClassBaseClass); QString attr = fileName((*r).node) + "#" + (*r).node->guid(); xmlWriter().writeAttribute("href",attr); writeCharacters(marker->plainFullName((*r).node)); - xmlWriter().writeEndElement(); // </cxxClassBaseClass> + writeEndTag(); // </cxxClassBaseClass> // not included: <ClassBaseStruct> or <cxxClassBaseUnion> - xmlWriter().writeEndElement(); // </cxxClassDerivation> + writeEndTag(); // </cxxClassDerivation> // not included: <cxxStructDerivation> ++r; } - xmlWriter().writeEndElement(); // </cxxClassDerivations> + writeEndTag(); // </cxxClassDerivations> } } @@ -4457,73 +4632,77 @@ void DitaXmlGenerator::writeDerivations(const ClassNode* cn, CodeMarker* marker) */ void DitaXmlGenerator::writeLocation(const Node* n) { - QString s1, s2, s3, s4, s5, s6; + DitaTag s1, s2, s3, s4, s5, s6; + s1 = DT_cxxClassAPIItemLocation; + s2 = DT_cxxClassDeclarationFile; + s3 = DT_cxxClassDeclarationFileLine; + s4 = DT_LAST; if (n->type() == Node::Class || n->type() == Node::Namespace) { - s1 = CXXCLASSAPIITEMLOCATION; - s2 = CXXCLASSDECLARATIONFILE; - s3 = CXXCLASSDECLARATIONFILELINE; + s1 = DT_cxxClassAPIItemLocation; + s2 = DT_cxxClassDeclarationFile; + s3 = DT_cxxClassDeclarationFileLine; } else if (n->type() == Node::Function) { FunctionNode* fn = const_cast<FunctionNode*>(static_cast<const FunctionNode*>(n)); if (fn->isMacro()) { - s1 = CXXDEFINEAPIITEMLOCATION; - s2 = CXXDEFINEDECLARATIONFILE; - s3 = CXXDEFINEDECLARATIONFILELINE; + s1 = DT_cxxDefineAPIItemLocation; + s2 = DT_cxxDefineDeclarationFile; + s3 = DT_cxxDefineDeclarationFileLine; } else { - s1 = CXXFUNCTIONAPIITEMLOCATION; - s2 = CXXFUNCTIONDECLARATIONFILE; - s3 = CXXFUNCTIONDECLARATIONFILELINE; + s1 = DT_cxxFunctionAPIItemLocation; + s2 = DT_cxxFunctionDeclarationFile; + s3 = DT_cxxFunctionDeclarationFileLine; } } else if (n->type() == Node::Enum) { - s1 = CXXENUMERATIONAPIITEMLOCATION; - s2 = CXXENUMERATIONDECLARATIONFILE; - s3 = CXXENUMERATIONDECLARATIONFILELINE; - s4 = CXXENUMERATIONDEFINITIONFILE; - s5 = CXXENUMERATIONDEFINITIONFILELINESTART; - s6 = CXXENUMERATIONDEFINITIONFILELINEEND; + s1 = DT_cxxEnumerationAPIItemLocation; + s2 = DT_cxxEnumerationDeclarationFile; + s3 = DT_cxxEnumerationDeclarationFileLine; + s4 = DT_cxxEnumerationDefinitionFile; + s5 = DT_cxxEnumerationDefinitionFileLineStart; + s6 = DT_cxxEnumerationDefinitionFileLineEnd; } else if (n->type() == Node::Typedef) { - s1 = CXXTYPEDEFAPIITEMLOCATION; - s2 = CXXTYPEDEFDECLARATIONFILE; - s3 = CXXTYPEDEFDECLARATIONFILELINE; + s1 = DT_cxxTypedefAPIItemLocation; + s2 = DT_cxxTypedefDeclarationFile; + s3 = DT_cxxTypedefDeclarationFileLine; } else if ((n->type() == Node::Property) || (n->type() == Node::Variable)) { - s1 = CXXVARIABLEAPIITEMLOCATION; - s2 = CXXVARIABLEDECLARATIONFILE; - s3 = CXXVARIABLEDECLARATIONFILELINE; + s1 = DT_cxxVariableAPIItemLocation; + s2 = DT_cxxVariableDeclarationFile; + s3 = DT_cxxVariableDeclarationFileLine; } - xmlWriter().writeStartElement(s1); - xmlWriter().writeStartElement(s2); + writeStartTag(s1); + writeStartTag(s2); xmlWriter().writeAttribute("name","filePath"); xmlWriter().writeAttribute("value",n->location().filePath()); - xmlWriter().writeEndElement(); // </cxx<s2>DeclarationFile> - xmlWriter().writeStartElement(s3); + writeEndTag(); // </cxx<s2>DeclarationFile> + writeStartTag(s3); xmlWriter().writeAttribute("name","lineNumber"); QString lineNr; xmlWriter().writeAttribute("value",lineNr.setNum(n->location().lineNo())); - xmlWriter().writeEndElement(); // </cxx<s3>DeclarationFileLine> - if (!s4.isEmpty()) { // zzz This stuff is temporary, I think. - xmlWriter().writeStartElement(s4); + writeEndTag(); // </cxx<s3>DeclarationFileLine> + if (s4 != DT_LAST) { // zzz This stuff is temporary, I think. + writeStartTag(s4); xmlWriter().writeAttribute("name","filePath"); xmlWriter().writeAttribute("value",n->location().filePath()); - xmlWriter().writeEndElement(); // </cxx<s4>DefinitionFile> - xmlWriter().writeStartElement(s5); + writeEndTag(); // </cxx<s4>DefinitionFile> + writeStartTag(s5); xmlWriter().writeAttribute("name","lineNumber"); xmlWriter().writeAttribute("value",lineNr.setNum(n->location().lineNo())); - xmlWriter().writeEndElement(); // </cxx<s5>DefinitionFileLineStart> - xmlWriter().writeStartElement(s6); + writeEndTag(); // </cxx<s5>DefinitionFileLineStart> + writeStartTag(s6); xmlWriter().writeAttribute("name","lineNumber"); xmlWriter().writeAttribute("value",lineNr.setNum(n->location().lineNo())); - xmlWriter().writeEndElement(); // </cxx<s6>DefinitionFileLineEnd> + writeEndTag(); // </cxx<s6>DefinitionFileLineEnd> } // not included: <cxxXXXDefinitionFile>, <cxxXXXDefinitionFileLineStart>, // and <cxxXXXDefinitionFileLineEnd> - xmlWriter().writeEndElement(); // </cxx<s1>ApiItemLocation> + writeEndTag(); // </cxx<s1>ApiItemLocation> } /*! @@ -4538,90 +4717,90 @@ void DitaXmlGenerator::writeFunctions(const Section& s, while (m != s.members.end()) { if ((*m)->type() == Node::Function) { FunctionNode* fn = const_cast<FunctionNode*>(static_cast<const FunctionNode*>(*m)); - xmlWriter().writeStartElement(CXXFUNCTION); + writeStartTag(DT_cxxFunction); xmlWriter().writeAttribute("id",fn->guid()); if (!attribute.isEmpty()) xmlWriter().writeAttribute("outputclass",attribute); - xmlWriter().writeStartElement("apiName"); + writeStartTag(DT_apiName); if (fn->metaness() == FunctionNode::Signal) xmlWriter().writeAttribute("class","signal"); else if (fn->metaness() == FunctionNode::Slot) xmlWriter().writeAttribute("class","slot"); writeCharacters(fn->name()); - xmlWriter().writeEndElement(); // </apiName> + writeEndTag(); // </apiName> generateBrief(fn,marker); // not included: <prolog> - xmlWriter().writeStartElement(CXXFUNCTIONDETAIL); - xmlWriter().writeStartElement(CXXFUNCTIONDEFINITION); - xmlWriter().writeStartElement(CXXFUNCTIONACCESSSPECIFIER); + writeStartTag(DT_cxxFunctionDetail); + writeStartTag(DT_cxxFunctionDefinition); + writeStartTag(DT_cxxFunctionAccessSpecifier); xmlWriter().writeAttribute("value",fn->accessString()); - xmlWriter().writeEndElement(); // <cxxFunctionAccessSpecifier> + writeEndTag(); // <cxxFunctionAccessSpecifier> // not included: <cxxFunctionStorageClassSpecifierExtern> if (fn->isStatic()) { - xmlWriter().writeStartElement(CXXFUNCTIONSTORAGECLASSSPECIFIERSTATIC); + writeStartTag(DT_cxxFunctionStorageClassSpecifierStatic); xmlWriter().writeAttribute("name","static"); xmlWriter().writeAttribute("value","static"); - xmlWriter().writeEndElement(); // <cxxFunctionStorageClassSpecifierStatic> + writeEndTag(); // <cxxFunctionStorageClassSpecifierStatic> } // not included: <cxxFunctionStorageClassSpecifierMutable>, if (fn->isConst()) { - xmlWriter().writeStartElement(CXXFUNCTIONCONST); + writeStartTag(DT_cxxFunctionConst); xmlWriter().writeAttribute("name","const"); xmlWriter().writeAttribute("value","const"); - xmlWriter().writeEndElement(); // <cxxFunctionConst> + writeEndTag(); // <cxxFunctionConst> } // not included: <cxxFunctionExplicit> // <cxxFunctionInline if (fn->virtualness() != FunctionNode::NonVirtual) { - xmlWriter().writeStartElement(CXXFUNCTIONVIRTUAL); + writeStartTag(DT_cxxFunctionVirtual); xmlWriter().writeAttribute("name","virtual"); xmlWriter().writeAttribute("value","virtual"); - xmlWriter().writeEndElement(); // <cxxFunctionVirtual> + writeEndTag(); // <cxxFunctionVirtual> if (fn->virtualness() == FunctionNode::PureVirtual) { - xmlWriter().writeStartElement(CXXFUNCTIONPUREVIRTUAL); + writeStartTag(DT_cxxFunctionPureVirtual); xmlWriter().writeAttribute("name","pure virtual"); xmlWriter().writeAttribute("value","pure virtual"); - xmlWriter().writeEndElement(); // <cxxFunctionPureVirtual> + writeEndTag(); // <cxxFunctionPureVirtual> } } if (fn->name() == n->name()) { - xmlWriter().writeStartElement(CXXFUNCTIONCONSTRUCTOR); + writeStartTag(DT_cxxFunctionConstructor); xmlWriter().writeAttribute("name","constructor"); xmlWriter().writeAttribute("value","constructor"); - xmlWriter().writeEndElement(); // <cxxFunctionConstructor> + writeEndTag(); // <cxxFunctionConstructor> } else if (fn->name()[0] == QChar('~')) { - xmlWriter().writeStartElement(CXXFUNCTIONDESTRUCTOR); + writeStartTag(DT_cxxFunctionDestructor); xmlWriter().writeAttribute("name","destructor"); xmlWriter().writeAttribute("value","destructor"); - xmlWriter().writeEndElement(); // <cxxFunctionDestructor> + writeEndTag(); // <cxxFunctionDestructor> } else { - xmlWriter().writeStartElement(CXXFUNCTIONDECLAREDTYPE); + writeStartTag(DT_cxxFunctionDeclaredType); writeCharacters(fn->returnType()); - xmlWriter().writeEndElement(); // <cxxFunctionDeclaredType> + writeEndTag(); // <cxxFunctionDeclaredType> } // not included: <cxxFunctionReturnType> QString fq = fullQualification(fn); if (!fq.isEmpty()) { - xmlWriter().writeStartElement(CXXFUNCTIONSCOPEDNAME); + writeStartTag(DT_cxxFunctionScopedName); writeCharacters(fq); - xmlWriter().writeEndElement(); // <cxxFunctionScopedName> + writeEndTag(); // <cxxFunctionScopedName> } - xmlWriter().writeStartElement(CXXFUNCTIONPROTOTYPE); + writeStartTag(DT_cxxFunctionPrototype); writeCharacters(fn->signature(true)); - xmlWriter().writeEndElement(); // <cxxFunctionPrototype> + writeEndTag(); // <cxxFunctionPrototype> QString fnl = fn->signature(false); int idx = fnl.indexOf(' '); @@ -4630,30 +4809,30 @@ void DitaXmlGenerator::writeFunctions(const Section& s, else ++idx; fnl = fn->parent()->name() + "::" + fnl.mid(idx); - xmlWriter().writeStartElement(CXXFUNCTIONNAMELOOKUP); + writeStartTag(DT_cxxFunctionNameLookup); writeCharacters(fnl); - xmlWriter().writeEndElement(); // <cxxFunctionNameLookup> + writeEndTag(); // <cxxFunctionNameLookup> if (!fn->isInternal() && fn->isReimp() && fn->reimplementedFrom() != 0) { FunctionNode* rfn = (FunctionNode*)fn->reimplementedFrom(); if (rfn && !rfn->isInternal()) { - xmlWriter().writeStartElement(CXXFUNCTIONREIMPLEMENTED); + writeStartTag(DT_cxxFunctionReimplemented); xmlWriter().writeAttribute("href",rfn->ditaXmlHref()); writeCharacters(marker->plainFullName(rfn)); - xmlWriter().writeEndElement(); // </cxxFunctionReimplemented> + writeEndTag(); // </cxxFunctionReimplemented> } } writeParameters(fn); writeLocation(fn); - xmlWriter().writeEndElement(); // <cxxFunctionDefinition> + writeEndTag(); // <cxxFunctionDefinition> - writeDetailedDescription(fn, marker, true, QString()); + writeApiDesc(fn, marker, QString()); // generateAlsoList(inner, marker); // not included: <example> or <apiImpl> - xmlWriter().writeEndElement(); // </cxxFunctionDetail> - xmlWriter().writeEndElement(); // </cxxFunction> + writeEndTag(); // </cxxFunctionDetail> + writeEndTag(); // </cxxFunction> if (fn->metaness() == FunctionNode::Ctor || fn->metaness() == FunctionNode::Dtor || @@ -4671,33 +4850,33 @@ void DitaXmlGenerator::writeParameters(const FunctionNode* fn) { const QList<Parameter>& parameters = fn->parameters(); if (!parameters.isEmpty()) { - xmlWriter().writeStartElement(CXXFUNCTIONPARAMETERS); + writeStartTag(DT_cxxFunctionParameters); QList<Parameter>::ConstIterator p = parameters.begin(); while (p != parameters.end()) { - xmlWriter().writeStartElement(CXXFUNCTIONPARAMETER); - xmlWriter().writeStartElement(CXXFUNCTIONPARAMETERDECLAREDTYPE); + writeStartTag(DT_cxxFunctionParameter); + writeStartTag(DT_cxxFunctionParameterDeclaredType); writeCharacters((*p).leftType()); if (!(*p).rightType().isEmpty()) writeCharacters((*p).rightType()); - xmlWriter().writeEndElement(); // <cxxFunctionParameterDeclaredType> - xmlWriter().writeStartElement(CXXFUNCTIONPARAMETERDECLARATIONNAME); + writeEndTag(); // <cxxFunctionParameterDeclaredType> + writeStartTag(DT_cxxFunctionParameterDeclarationName); writeCharacters((*p).name()); - xmlWriter().writeEndElement(); // <cxxFunctionParameterDeclarationName> + writeEndTag(); // <cxxFunctionParameterDeclarationName> // not included: <cxxFunctionParameterDefinitionName> if (!(*p).defaultValue().isEmpty()) { - xmlWriter().writeStartElement(CXXFUNCTIONPARAMETERDEFAULTVALUE); + writeStartTag(DT_cxxFunctionParameterDefaultValue); writeCharacters((*p).defaultValue()); - xmlWriter().writeEndElement(); // <cxxFunctionParameterDefaultValue> + writeEndTag(); // <cxxFunctionParameterDefaultValue> } // not included: <apiDefNote> - xmlWriter().writeEndElement(); // <cxxFunctionParameter> + writeEndTag(); // <cxxFunctionParameter> ++p; } - xmlWriter().writeEndElement(); // <cxxFunctionParameters> + writeEndTag(); // <cxxFunctionParameters> } } @@ -4712,32 +4891,32 @@ void DitaXmlGenerator::writeEnumerations(const Section& s, while (m != s.members.end()) { if ((*m)->type() == Node::Enum) { const EnumNode* en = static_cast<const EnumNode*>(*m); - xmlWriter().writeStartElement(CXXENUMERATION); + writeStartTag(DT_cxxEnumeration); xmlWriter().writeAttribute("id",en->guid()); if (!attribute.isEmpty()) xmlWriter().writeAttribute("outputclass",attribute); - xmlWriter().writeStartElement("apiName"); + writeStartTag(DT_apiName); writeCharacters(en->name()); - xmlWriter().writeEndElement(); // </apiName> + writeEndTag(); // </apiName> generateBrief(en,marker); // not included <prolog> - xmlWriter().writeStartElement(CXXENUMERATIONDETAIL); - xmlWriter().writeStartElement(CXXENUMERATIONDEFINITION); - xmlWriter().writeStartElement(CXXENUMERATIONACCESSSPECIFIER); + writeStartTag(DT_cxxEnumerationDetail); + writeStartTag(DT_cxxEnumerationDefinition); + writeStartTag(DT_cxxEnumerationAccessSpecifier); xmlWriter().writeAttribute("value",en->accessString()); - xmlWriter().writeEndElement(); // <cxxEnumerationAccessSpecifier> + writeEndTag(); // <cxxEnumerationAccessSpecifier> QString fq = fullQualification(en); if (!fq.isEmpty()) { - xmlWriter().writeStartElement(CXXENUMERATIONSCOPEDNAME); + writeStartTag(DT_cxxEnumerationScopedName); writeCharacters(fq); - xmlWriter().writeEndElement(); // <cxxEnumerationScopedName> + writeEndTag(); // <cxxEnumerationScopedName> } const QList<EnumItem>& items = en->items(); if (!items.isEmpty()) { - xmlWriter().writeStartElement(CXXENUMERATIONPROTOTYPE); + writeStartTag(DT_cxxEnumerationPrototype); writeCharacters(en->name()); xmlWriter().writeCharacters(" = { "); QList<EnumItem>::ConstIterator i = items.begin(); @@ -4752,68 +4931,68 @@ void DitaXmlGenerator::writeEnumerations(const Section& s, xmlWriter().writeCharacters(", "); } xmlWriter().writeCharacters(" }"); - xmlWriter().writeEndElement(); // <cxxEnumerationPrototype> + writeEndTag(); // <cxxEnumerationPrototype> } - xmlWriter().writeStartElement(CXXENUMERATIONNAMELOOKUP); + writeStartTag(DT_cxxEnumerationNameLookup); writeCharacters(en->parent()->name() + "::" + en->name()); - xmlWriter().writeEndElement(); // <cxxEnumerationNameLookup> + writeEndTag(); // <cxxEnumerationNameLookup> // not included: <cxxEnumerationReimplemented> if (!items.isEmpty()) { - xmlWriter().writeStartElement(CXXENUMERATORS); + writeStartTag(DT_cxxEnumerators); QList<EnumItem>::ConstIterator i = items.begin(); while (i != items.end()) { - xmlWriter().writeStartElement(CXXENUMERATOR); - xmlWriter().writeStartElement("apiName"); + writeStartTag(DT_cxxEnumerator); + writeStartTag(DT_apiName); writeCharacters((*i).name()); - xmlWriter().writeEndElement(); // </apiName> + writeEndTag(); // </apiName> QString fq = fullQualification(en->parent()); if (!fq.isEmpty()) { - xmlWriter().writeStartElement(CXXENUMERATORSCOPEDNAME); + writeStartTag(DT_cxxEnumeratorScopedName); writeCharacters(fq + "::" + (*i).name()); - xmlWriter().writeEndElement(); // <cxxEnumeratorScopedName> + writeEndTag(); // <cxxEnumeratorScopedName> } - xmlWriter().writeStartElement(CXXENUMERATORPROTOTYPE); + writeStartTag(DT_cxxEnumeratorPrototype); writeCharacters((*i).name()); - xmlWriter().writeEndElement(); // <cxxEnumeratorPrototype> - xmlWriter().writeStartElement(CXXENUMERATORNAMELOOKUP); + writeEndTag(); // <cxxEnumeratorPrototype> + writeStartTag(DT_cxxEnumeratorNameLookup); writeCharacters(en->parent()->name() + "::" + (*i).name()); - xmlWriter().writeEndElement(); // <cxxEnumeratorNameLookup> + writeEndTag(); // <cxxEnumeratorNameLookup> if (!(*i).value().isEmpty()) { - xmlWriter().writeStartElement(CXXENUMERATORINITIALISER); + writeStartTag(DT_cxxEnumeratorInitialiser); xmlWriter().writeAttribute("value", (*i).value()); - xmlWriter().writeEndElement(); // <cxxEnumeratorInitialiser> + writeEndTag(); // <cxxEnumeratorInitialiser> } // not included: <cxxEnumeratorAPIItemLocation> if (!(*i).text().isEmpty()) { - xmlWriter().writeStartElement("apiDesc"); + writeStartTag(DT_apiDesc); generateText((*i).text(), en, marker); - xmlWriter().writeEndElement(); // </apiDesc> + writeEndTag(); // </apiDesc> } - xmlWriter().writeEndElement(); // <cxxEnumerator> + writeEndTag(); // <cxxEnumerator> ++i; } - xmlWriter().writeEndElement(); // <cxxEnumerators> + writeEndTag(); // <cxxEnumerators> } writeLocation(en); - xmlWriter().writeEndElement(); // <cxxEnumerationDefinition> + writeEndTag(); // <cxxEnumerationDefinition> - writeDetailedDescription(en, marker, true, QString()); + writeApiDesc(en, marker, QString()); // not included: <example> or <apiImpl> - xmlWriter().writeEndElement(); // </cxxEnumerationDetail> + writeEndTag(); // </cxxEnumerationDetail> // not included: <related-links> - xmlWriter().writeEndElement(); // </cxxEnumeration> + writeEndTag(); // </cxxEnumeration> } ++m; } @@ -4831,52 +5010,52 @@ void DitaXmlGenerator::writeTypedefs(const Section& s, while (m != s.members.end()) { if ((*m)->type() == Node::Typedef) { const TypedefNode* tn = static_cast<const TypedefNode*>(*m); - xmlWriter().writeStartElement(CXXTYPEDEF); + writeStartTag(DT_cxxTypedef); xmlWriter().writeAttribute("id",tn->guid()); if (!attribute.isEmpty()) xmlWriter().writeAttribute("outputclass",attribute); - xmlWriter().writeStartElement("apiName"); + writeStartTag(DT_apiName); writeCharacters(tn->name()); - xmlWriter().writeEndElement(); // </apiName> + writeEndTag(); // </apiName> generateBrief(tn,marker); // not included: <prolog> - xmlWriter().writeStartElement(CXXTYPEDEFDETAIL); - xmlWriter().writeStartElement(CXXTYPEDEFDEFINITION); - xmlWriter().writeStartElement(CXXTYPEDEFACCESSSPECIFIER); + writeStartTag(DT_cxxTypedefDetail); + writeStartTag(DT_cxxTypedefDefinition); + writeStartTag(DT_cxxTypedefAccessSpecifier); xmlWriter().writeAttribute("value",tn->accessString()); - xmlWriter().writeEndElement(); // <cxxTypedefAccessSpecifier> + writeEndTag(); // <cxxTypedefAccessSpecifier> // not included: <cxxTypedefDeclaredType> QString fq = fullQualification(tn); if (!fq.isEmpty()) { - xmlWriter().writeStartElement(CXXTYPEDEFSCOPEDNAME); + writeStartTag(DT_cxxTypedefScopedName); writeCharacters(fq); - xmlWriter().writeEndElement(); // <cxxTypedefScopedName> + writeEndTag(); // <cxxTypedefScopedName> } // not included: <cxxTypedefPrototype> - xmlWriter().writeStartElement(CXXTYPEDEFNAMELOOKUP); + writeStartTag(DT_cxxTypedefNameLookup); writeCharacters(tn->parent()->name() + "::" + tn->name()); - xmlWriter().writeEndElement(); // <cxxTypedefNameLookup> + writeEndTag(); // <cxxTypedefNameLookup> // not included: <cxxTypedefReimplemented> writeLocation(tn); - xmlWriter().writeEndElement(); // <cxxTypedefDefinition> + writeEndTag(); // <cxxTypedefDefinition> - writeDetailedDescription(tn, marker, true, QString()); + writeApiDesc(tn, marker, QString()); // not included: <example> or <apiImpl> - xmlWriter().writeEndElement(); // </cxxTypedefDetail> + writeEndTag(); // </cxxTypedefDetail> // not included: <related-links> - xmlWriter().writeEndElement(); // </cxxTypedef> + writeEndTag(); // </cxxTypedef> } ++m; } @@ -4894,22 +5073,22 @@ void DitaXmlGenerator::writeProperties(const Section& s, while (m != s.members.end()) { if ((*m)->type() == Node::Property) { const PropertyNode* pn = static_cast<const PropertyNode*>(*m); - xmlWriter().writeStartElement(CXXVARIABLE); + writeStartTag(DT_cxxVariable); xmlWriter().writeAttribute("id",pn->guid()); if (!attribute.isEmpty()) xmlWriter().writeAttribute("outputclass",attribute); - xmlWriter().writeStartElement("apiName"); + writeStartTag(DT_apiName); writeCharacters(pn->name()); - xmlWriter().writeEndElement(); // </apiName> + writeEndTag(); // </apiName> generateBrief(pn,marker); // not included: <prolog> - xmlWriter().writeStartElement(CXXVARIABLEDETAIL); - xmlWriter().writeStartElement(CXXVARIABLEDEFINITION); - xmlWriter().writeStartElement(CXXVARIABLEACCESSSPECIFIER); + writeStartTag(DT_cxxVariableDetail); + writeStartTag(DT_cxxVariableDefinition); + writeStartTag(DT_cxxVariableAccessSpecifier); xmlWriter().writeAttribute("value",pn->accessString()); - xmlWriter().writeEndElement(); // <cxxVariableAccessSpecifier> + writeEndTag(); // <cxxVariableAccessSpecifier> // not included: <cxxVariableStorageClassSpecifierExtern>, // <cxxVariableStorageClassSpecifierStatic>, @@ -4917,18 +5096,18 @@ void DitaXmlGenerator::writeProperties(const Section& s, // <cxxVariableConst>, <cxxVariableVolatile> if (!pn->qualifiedDataType().isEmpty()) { - xmlWriter().writeStartElement(CXXVARIABLEDECLAREDTYPE); + writeStartTag(DT_cxxVariableDeclaredType); writeCharacters(pn->qualifiedDataType()); - xmlWriter().writeEndElement(); // <cxxVariableDeclaredType> + writeEndTag(); // <cxxVariableDeclaredType> } QString fq = fullQualification(pn); if (!fq.isEmpty()) { - xmlWriter().writeStartElement(CXXVARIABLESCOPEDNAME); + writeStartTag(DT_cxxVariableScopedName); writeCharacters(fq); - xmlWriter().writeEndElement(); // <cxxVariableScopedName> + writeEndTag(); // <cxxVariableScopedName> } - xmlWriter().writeStartElement(CXXVARIABLEPROTOTYPE); + writeStartTag(DT_cxxVariablePrototype); xmlWriter().writeCharacters("Q_PROPERTY("); writeCharacters(pn->qualifiedDataType()); xmlWriter().writeCharacters(" "); @@ -4964,32 +5143,32 @@ void DitaXmlGenerator::writeProperties(const Section& s, if (pn->isFinal()) xmlWriter().writeCharacters(" FINAL"); xmlWriter().writeCharacters(")"); - xmlWriter().writeEndElement(); // <cxxVariablePrototype> + writeEndTag(); // <cxxVariablePrototype> - xmlWriter().writeStartElement(CXXVARIABLENAMELOOKUP); + writeStartTag(DT_cxxVariableNameLookup); writeCharacters(pn->parent()->name() + "::" + pn->name()); - xmlWriter().writeEndElement(); // <cxxVariableNameLookup> + writeEndTag(); // <cxxVariableNameLookup> if (pn->overriddenFrom() != 0) { PropertyNode* opn = (PropertyNode*)pn->overriddenFrom(); - xmlWriter().writeStartElement(CXXVARIABLEREIMPLEMENTED); + writeStartTag(DT_cxxVariableReimplemented); xmlWriter().writeAttribute("href",opn->ditaXmlHref()); writeCharacters(marker->plainFullName(opn)); - xmlWriter().writeEndElement(); // </cxxVariableReimplemented> + writeEndTag(); // </cxxVariableReimplemented> } writeLocation(pn); - xmlWriter().writeEndElement(); // <cxxVariableDefinition> + writeEndTag(); // <cxxVariableDefinition> - writeDetailedDescription(pn, marker, true, QString()); + writeApiDesc(pn, marker, QString()); // not included: <example> or <apiImpl> - xmlWriter().writeEndElement(); // </cxxVariableDetail> + writeEndTag(); // </cxxVariableDetail> // not included: <related-links> - xmlWriter().writeEndElement(); // </cxxVariable> + writeEndTag(); // </cxxVariable> } ++m; } @@ -5006,74 +5185,74 @@ void DitaXmlGenerator::writeDataMembers(const Section& s, while (m != s.members.end()) { if ((*m)->type() == Node::Variable) { const VariableNode* vn = static_cast<const VariableNode*>(*m); - xmlWriter().writeStartElement(CXXVARIABLE); + writeStartTag(DT_cxxVariable); xmlWriter().writeAttribute("id",vn->guid()); if (!attribute.isEmpty()) xmlWriter().writeAttribute("outputclass",attribute); - xmlWriter().writeStartElement("apiName"); + writeStartTag(DT_apiName); writeCharacters(vn->name()); - xmlWriter().writeEndElement(); // </apiName> + writeEndTag(); // </apiName> generateBrief(vn,marker); // not included: <prolog> - xmlWriter().writeStartElement(CXXVARIABLEDETAIL); - xmlWriter().writeStartElement(CXXVARIABLEDEFINITION); - xmlWriter().writeStartElement(CXXVARIABLEACCESSSPECIFIER); + writeStartTag(DT_cxxVariableDetail); + writeStartTag(DT_cxxVariableDefinition); + writeStartTag(DT_cxxVariableAccessSpecifier); xmlWriter().writeAttribute("value",vn->accessString()); - xmlWriter().writeEndElement(); // <cxxVariableAccessSpecifier> + writeEndTag(); // <cxxVariableAccessSpecifier> // not included: <cxxVAriableStorageClassSpecifierExtern> if (vn->isStatic()) { - xmlWriter().writeStartElement(CXXVARIABLESTORAGECLASSSPECIFIERSTATIC); + writeStartTag(DT_cxxVariableStorageClassSpecifierStatic); xmlWriter().writeAttribute("name","static"); xmlWriter().writeAttribute("value","static"); - xmlWriter().writeEndElement(); // <cxxVariableStorageClassSpecifierStatic> + writeEndTag(); // <cxxVariableStorageClassSpecifierStatic> } // not included: <cxxVAriableStorageClassSpecifierMutable>, // <cxxVariableConst>, <cxxVariableVolatile> - xmlWriter().writeStartElement(CXXVARIABLEDECLAREDTYPE); + writeStartTag(DT_cxxVariableDeclaredType); writeCharacters(vn->leftType()); if (!vn->rightType().isEmpty()) writeCharacters(vn->rightType()); - xmlWriter().writeEndElement(); // <cxxVariableDeclaredType> + writeEndTag(); // <cxxVariableDeclaredType> QString fq = fullQualification(vn); if (!fq.isEmpty()) { - xmlWriter().writeStartElement(CXXVARIABLESCOPEDNAME); + writeStartTag(DT_cxxVariableScopedName); writeCharacters(fq); - xmlWriter().writeEndElement(); // <cxxVariableScopedName> + writeEndTag(); // <cxxVariableScopedName> } - xmlWriter().writeStartElement(CXXVARIABLEPROTOTYPE); + writeStartTag(DT_cxxVariablePrototype); writeCharacters(vn->leftType() + " "); //writeCharacters(vn->parent()->name() + "::" + vn->name()); writeCharacters(vn->name()); if (!vn->rightType().isEmpty()) writeCharacters(vn->rightType()); - xmlWriter().writeEndElement(); // <cxxVariablePrototype> + writeEndTag(); // <cxxVariablePrototype> - xmlWriter().writeStartElement(CXXVARIABLENAMELOOKUP); + writeStartTag(DT_cxxVariableNameLookup); writeCharacters(vn->parent()->name() + "::" + vn->name()); - xmlWriter().writeEndElement(); // <cxxVariableNameLookup> + writeEndTag(); // <cxxVariableNameLookup> // not included: <cxxVariableReimplemented> writeLocation(vn); - xmlWriter().writeEndElement(); // <cxxVariableDefinition> + writeEndTag(); // <cxxVariableDefinition> - writeDetailedDescription(vn, marker, true, QString()); + writeApiDesc(vn, marker, QString()); // not included: <example> or <apiImpl> - xmlWriter().writeEndElement(); // </cxxVariableDetail> + writeEndTag(); // </cxxVariableDetail> // not included: <related-links> - xmlWriter().writeEndElement(); // </cxxVariable> + writeEndTag(); // </cxxVariable> } ++m; } @@ -5091,24 +5270,24 @@ void DitaXmlGenerator::writeMacros(const Section& s, if ((*m)->type() == Node::Function) { const FunctionNode* fn = static_cast<const FunctionNode*>(*m); if (fn->isMacro()) { - xmlWriter().writeStartElement(CXXDEFINE); + writeStartTag(DT_cxxDefine); xmlWriter().writeAttribute("id",fn->guid()); if (!attribute.isEmpty()) xmlWriter().writeAttribute("outputclass",attribute); - xmlWriter().writeStartElement("apiName"); + writeStartTag(DT_apiName); writeCharacters(fn->name()); - xmlWriter().writeEndElement(); // </apiName> + writeEndTag(); // </apiName> generateBrief(fn,marker); // not included: <prolog> - xmlWriter().writeStartElement(CXXDEFINEDETAIL); - xmlWriter().writeStartElement(CXXDEFINEDEFINITION); - xmlWriter().writeStartElement(CXXDEFINEACCESSSPECIFIER); + writeStartTag(DT_cxxDefineDetail); + writeStartTag(DT_cxxDefineDefinition); + writeStartTag(DT_cxxDefineAccessSpecifier); xmlWriter().writeAttribute("value",fn->accessString()); - xmlWriter().writeEndElement(); // <cxxDefineAccessSpecifier> + writeEndTag(); // <cxxDefineAccessSpecifier> - xmlWriter().writeStartElement(CXXDEFINEPROTOTYPE); + writeStartTag(DT_cxxDefinePrototype); xmlWriter().writeCharacters("#define "); writeCharacters(fn->name()); if (fn->metaness() == FunctionNode::MacroWithParams) { @@ -5126,50 +5305,50 @@ void DitaXmlGenerator::writeMacros(const Section& s, xmlWriter().writeCharacters(")"); } } - xmlWriter().writeEndElement(); // <cxxDefinePrototype> + writeEndTag(); // <cxxDefinePrototype> - xmlWriter().writeStartElement(CXXDEFINENAMELOOKUP); + writeStartTag(DT_cxxDefineNameLookup); writeCharacters(fn->name()); - xmlWriter().writeEndElement(); // <cxxDefineNameLookup> + writeEndTag(); // <cxxDefineNameLookup> if (fn->reimplementedFrom() != 0) { FunctionNode* rfn = (FunctionNode*)fn->reimplementedFrom(); - xmlWriter().writeStartElement(CXXDEFINEREIMPLEMENTED); + writeStartTag(DT_cxxDefineReimplemented); xmlWriter().writeAttribute("href",rfn->ditaXmlHref()); writeCharacters(marker->plainFullName(rfn)); - xmlWriter().writeEndElement(); // </cxxDefineReimplemented> + writeEndTag(); // </cxxDefineReimplemented> } if (fn->metaness() == FunctionNode::MacroWithParams) { QStringList params = fn->parameterNames(); if (!params.isEmpty()) { - xmlWriter().writeStartElement(CXXDEFINEPARAMETERS); + writeStartTag(DT_cxxDefineParameters); for (int i = 0; i < params.size(); ++i) { - xmlWriter().writeStartElement(CXXDEFINEPARAMETER); - xmlWriter().writeStartElement(CXXDEFINEPARAMETERDECLARATIONNAME); + writeStartTag(DT_cxxDefineParameter); + writeStartTag(DT_cxxDefineParameterDeclarationName); writeCharacters(params[i]); - xmlWriter().writeEndElement(); // <cxxDefineParameterDeclarationName> + writeEndTag(); // <cxxDefineParameterDeclarationName> // not included: <apiDefNote> - xmlWriter().writeEndElement(); // <cxxDefineParameter> + writeEndTag(); // <cxxDefineParameter> } - xmlWriter().writeEndElement(); // <cxxDefineParameters> + writeEndTag(); // <cxxDefineParameters> } } writeLocation(fn); - xmlWriter().writeEndElement(); // <cxxDefineDefinition> + writeEndTag(); // <cxxDefineDefinition> - writeDetailedDescription(fn, marker, true, QString()); + writeApiDesc(fn, marker, QString()); // not included: <example> or <apiImpl> - xmlWriter().writeEndElement(); // </cxxDefineDetail> + writeEndTag(); // </cxxDefineDetail> // not included: <related-links> - xmlWriter().writeEndElement(); // </cxxDefine> + writeEndTag(); // </cxxDefine> } } ++m; @@ -5212,6 +5391,7 @@ void DitaXmlGenerator::beginSubPage(const Location& location, writer->setAutoFormatting(true); writer->setAutoFormattingIndent(4); writer->writeStartDocument(); + clearSectionNesting(); } /*! @@ -5221,6 +5401,8 @@ void DitaXmlGenerator::beginSubPage(const Location& location, */ void DitaXmlGenerator::endSubPage() { + if (inSection()) + qDebug() << "Missing </section> in" << outFileName() << sectionNestingLevel; xmlWriter().writeEndDocument(); delete xmlWriterStack.pop(); PageGenerator::endSubPage(); @@ -5238,58 +5420,18 @@ QXmlStreamWriter& DitaXmlGenerator::xmlWriter() } /*! - Writes the \e {Detailed Description} section(s) for \a node to the - current XML stream using the code \a marker. if the \a apiDesc flag - is true, then the first section of the sequence of sections written - will be an \c {apiDesc>} element with a \e {spectitle} attribute of - \e {Detailed Description}. Otherwise, the first section will be a - \c {<section>} element with a \c {<title>} element of \e {Detailed - Description}. This function calls the Generator::generateBody() - function to write the XML for the section list. + Writes the \e {<apiDesc>} element for \a node to the current XML + stream using the code \a marker and the \a title. */ -void DitaXmlGenerator::writeDetailedDescription(const Node* node, - CodeMarker* marker, - bool apiDesc, - const QString& title) +void DitaXmlGenerator::writeApiDesc(const Node* node, + CodeMarker* marker, + const QString& title) { if (!node->doc().isEmpty()) { inDetailedDescription = true; - if (apiDesc) { - inApiDesc = true; - xmlWriter().writeStartElement("apiDesc"); - if (!title.isEmpty()) { - writeGuidAttribute(title); - xmlWriter().writeAttribute("spectitle",title); - } - else - writeGuidAttribute("Detailed Description"); - xmlWriter().writeAttribute("outputclass","details"); - } - else { - inSection = true; - xmlWriter().writeStartElement("section"); - if (!title.isEmpty()) { - writeGuidAttribute(title); - xmlWriter().writeAttribute("outputclass","details"); - xmlWriter().writeStartElement("title"); - xmlWriter().writeAttribute("outputclass","h2"); - writeCharacters(title); - xmlWriter().writeEndElement(); // </title> - } - else { - writeGuidAttribute("Detailed Description"); - xmlWriter().writeAttribute("outputclass","details"); - } - } + enterApiDesc(QString(),title); generateBody(node, marker); - if (inApiDesc) { - xmlWriter().writeEndElement(); // </apiDesc> - inApiDesc = false; - } - else if (inSection) { - xmlWriter().writeEndElement(); // </section> - inSection = false; - } + leaveSection(); } inDetailedDescription = false; } @@ -5302,23 +5444,23 @@ void DitaXmlGenerator::writeNestedClasses(const Section& s, { if (s.members.isEmpty()) return; - xmlWriter().writeStartElement("cxxClassNested"); - xmlWriter().writeStartElement("cxxClassNestedDetail"); + writeStartTag(DT_cxxClassNested); + writeStartTag(DT_cxxClassNestedDetail); NodeList::ConstIterator m = s.members.begin(); while (m != s.members.end()) { if ((*m)->type() == Node::Class) { - xmlWriter().writeStartElement("cxxClassNestedClass"); + writeStartTag(DT_cxxClassNestedClass); QString link = linkForNode((*m), n); xmlWriter().writeAttribute("href", link); QString name = n->name() + "::" + (*m)->name(); writeCharacters(name); - xmlWriter().writeEndElement(); // <cxxClassNestedClass> + writeEndTag(); // <cxxClassNestedClass> } ++m; } - xmlWriter().writeEndElement(); // <cxxClassNestedDetail> - xmlWriter().writeEndElement(); // <cxxClassNested> + writeEndTag(); // <cxxClassNestedDetail> + writeEndTag(); // <cxxClassNested> } /*! @@ -5389,23 +5531,158 @@ void DitaXmlGenerator::writeDitaMap() doctype = "<!DOCTYPE cxxAPIMap PUBLIC \"-//NOKIA//DTD DITA C++ API Map Reference Type v0.6.0//EN\" \"dtd/cxxAPIMap.dtd\">"; xmlWriter().writeDTD(doctype); - xmlWriter().writeStartElement("cxxAPIMap"); + writeStartTag(DT_cxxAPIMap); xmlWriter().writeAttribute("id","Qt-DITA-Map"); xmlWriter().writeAttribute("title","Qt DITA Map"); - xmlWriter().writeStartElement("topicmeta"); - xmlWriter().writeStartElement("shortdesc"); + writeStartTag(DT_topicmeta); + writeStartTag(DT_shortdesc); xmlWriter().writeCharacters("The top level map for the Qt documentation"); - xmlWriter().writeEndElement(); // </shortdesc> - xmlWriter().writeEndElement(); // </topicmeta> + writeEndTag(); // </shortdesc> + writeEndTag(); // </topicmeta> GuidMaps::iterator i = guidMaps.begin(); while (i != guidMaps.end()) { - xmlWriter().writeStartElement("topicref"); + writeStartTag(DT_topicref); xmlWriter().writeAttribute("href",i.key()); xmlWriter().writeAttribute("type","topic"); - xmlWriter().writeEndElement(); // </topicref> + writeEndTag(); // </topicref> ++i; } endSubPage(); } +/*! + Writes the <prolog> element for the \a inner node + using the \a marker. The <prolog> element contains + the <metadata> element, plus some others. This + function writes one or more of these elements: + + \list + \o <audience> + \o <author> * + \o <brand> + \o <category> * + \o <compomnent> * + \o <copyrholder> + \o <copyright> + \o <created> + \o <copyryear> + \o <critdates> + \o <keyword> + \o <keywords> + \o <metadata> * + \o <othermeta> + \o <permissions> * + \o <platform> + \o <prodinfo> * + \o <prodname> * + \o <prolog> * + \o <publisher> * + \o <resourceid> + \o <revised> + \o <source> + \o <tm> + \o <unknown> + \o <vrm> * + \o <vrmlist> * + \endlist + + \node * means the tag has been used. + + */ +void +DitaXmlGenerator::writeProlog(const InnerNode* inner, CodeMarker* marker) +{ + if (!inner) + return; + writeStartTag(DT_prolog); + + QString author = inner->author(); + writeStartTag(DT_author); + if (author.isEmpty()) + author = "Qt Development Frameworks"; + xmlWriter().writeCharacters(author); + writeEndTag(); // <author> + + QString publisher = inner->publisher(); + writeStartTag(DT_publisher); + if (publisher.isEmpty()) + publisher = "Nokia"; + xmlWriter().writeCharacters(publisher); + writeEndTag(); // <publisher> + + QString permissions = inner->permissions(); + writeStartTag(DT_permissions); + if (permissions.isEmpty()) + permissions = "all"; + xmlWriter().writeAttribute("view",permissions); + writeEndTag(); // <permissions> + + writeStartTag(DT_metadata); + writeStartTag(DT_category); + QString category = "Page"; + if (inner->type() == Node::Class) + category = "C++ Class"; + else if (inner->type() == Node::Namespace) + category = "C++ Namespace"; + else if (inner->type() == Node::Fake) { + if (inner->subType() == Node::QmlBasicType) + category = "QML Class"; + else if (inner->subType() == Node::QmlClass) + category = "QML Basic Type"; + else if (inner->subType() == Node::HeaderFile) + category = "Header File"; + else if (inner->subType() == Node::Module) + category = "Module"; + else if (inner->subType() == Node::File) + category = "Example Source File"; + else if (inner->subType() == Node::Example) + category = "Example"; + else if (inner->subType() == Node::Image) + category = "Image"; + else if (inner->subType() == Node::Group) + category = "Group"; + else if (inner->subType() == Node::Page) + category = "Page"; + else if (inner->subType() == Node::ExternalPage) + category = "External Page"; // Is this necessary? + } + xmlWriter().writeCharacters(category); + writeEndTag(); // <category> + if (vrm.size() > 0) { + writeStartTag(DT_prodinfo); + writeStartTag(DT_prodname); + xmlWriter().writeCharacters(projectDescription); + writeEndTag(); // <prodname> + writeStartTag(DT_vrmlist); + writeStartTag(DT_vrm); + if (vrm.size() > 0) + xmlWriter().writeAttribute("version",vrm[0]); + if (vrm.size() > 1) + xmlWriter().writeAttribute("release",vrm[1]); + if (vrm.size() > 2) + xmlWriter().writeAttribute("modification",vrm[2]); + writeEndTag(); // <vrm> + writeEndTag(); // <vrmlist> + QString component = inner->moduleName(); + if (!component.isEmpty()) { + writeStartTag(DT_component); + xmlWriter().writeCharacters(component); + writeEndTag(); // <component> + } + writeEndTag(); // <prodinfo> + if (inner->hasOtherMetadata()) { + const QMap<QString, QString>& omd = inner->otherMetadata(); + QMapIterator<QString, QString> i(omd); + while (i.hasNext()) { + i.next(); + writeStartTag(DT_othermeta); + xmlWriter().writeAttribute("name",i.key()); + xmlWriter().writeAttribute("content",i.value()); + } + } + } + writeEndTag(); // <metadata> + writeEndTag(); // <prolog> +} + QT_END_NAMESPACE diff --git a/tools/qdoc3/ditaxmlgenerator.h b/tools/qdoc3/ditaxmlgenerator.h index 4aae657..7793db0 100644 --- a/tools/qdoc3/ditaxmlgenerator.h +++ b/tools/qdoc3/ditaxmlgenerator.h @@ -81,6 +81,182 @@ class DitaXmlGenerator : public PageGenerator LastSinceType }; + enum DitaTag { + DT_NONE, + DT_alt, + DT_apiDesc, + DT_APIMap, + DT_apiName, + DT_audience, + DT_author, + DT_b, + DT_body, + DT_bodydiv, + DT_brand, + DT_category, + DT_codeblock, + DT_comment, + DT_component, + DT_copyrholder, + DT_copyright, + DT_copyryear, + DT_created, + DT_critdates, + DT_cxxAPIMap, + DT_cxxClass, + DT_cxxClassAbstract, + DT_cxxClassAccessSpecifier, + DT_cxxClassAPIItemLocation, + DT_cxxClassBaseClass, + DT_cxxClassDeclarationFile, + DT_cxxClassDeclarationFileLine, + DT_cxxClassDefinition, + DT_cxxClassDerivation, + DT_cxxClassDerivationAccessSpecifier, + DT_cxxClassDerivations, + DT_cxxClassDetail, + DT_cxxClassNested, + DT_cxxClassNestedClass, + DT_cxxClassNestedDetail, + DT_cxxDefine, + DT_cxxDefineAccessSpecifier, + DT_cxxDefineAPIItemLocation, + DT_cxxDefineDeclarationFile, + DT_cxxDefineDeclarationFileLine, + DT_cxxDefineDefinition, + DT_cxxDefineDetail, + DT_cxxDefineNameLookup, + DT_cxxDefineParameter, + DT_cxxDefineParameterDeclarationName, + DT_cxxDefineParameters, + DT_cxxDefinePrototype, + DT_cxxDefineReimplemented, + DT_cxxEnumeration, + DT_cxxEnumerationAccessSpecifier, + DT_cxxEnumerationAPIItemLocation, + DT_cxxEnumerationDeclarationFile, + DT_cxxEnumerationDeclarationFileLine, + DT_cxxEnumerationDefinition, + DT_cxxEnumerationDefinitionFile, + DT_cxxEnumerationDefinitionFileLineStart, + DT_cxxEnumerationDefinitionFileLineEnd, + DT_cxxEnumerationDetail, + DT_cxxEnumerationNameLookup, + DT_cxxEnumerationPrototype, + DT_cxxEnumerationScopedName, + DT_cxxEnumerator, + DT_cxxEnumeratorInitialiser, + DT_cxxEnumeratorNameLookup, + DT_cxxEnumeratorPrototype, + DT_cxxEnumerators, + DT_cxxEnumeratorScopedName, + DT_cxxFunction, + DT_cxxFunctionAccessSpecifier, + DT_cxxFunctionAPIItemLocation, + DT_cxxFunctionConst, + DT_cxxFunctionConstructor, + DT_cxxFunctionDeclarationFile, + DT_cxxFunctionDeclarationFileLine, + DT_cxxFunctionDeclaredType, + DT_cxxFunctionDefinition, + DT_cxxFunctionDestructor, + DT_cxxFunctionDetail, + DT_cxxFunctionNameLookup, + DT_cxxFunctionParameter, + DT_cxxFunctionParameterDeclarationName, + DT_cxxFunctionParameterDeclaredType, + DT_cxxFunctionParameterDefaultValue, + DT_cxxFunctionParameters, + DT_cxxFunctionPrototype, + DT_cxxFunctionPureVirtual, + DT_cxxFunctionReimplemented, + DT_cxxFunctionScopedName, + DT_cxxFunctionStorageClassSpecifierStatic, + DT_cxxFunctionVirtual, + DT_cxxTypedef, + DT_cxxTypedefAccessSpecifier, + DT_cxxTypedefAPIItemLocation, + DT_cxxTypedefDeclarationFile, + DT_cxxTypedefDeclarationFileLine, + DT_cxxTypedefDefinition, + DT_cxxTypedefDetail, + DT_cxxTypedefNameLookup, + DT_cxxTypedefScopedName, + DT_cxxVariable, + DT_cxxVariableAccessSpecifier, + DT_cxxVariableAPIItemLocation, + DT_cxxVariableDeclarationFile, + DT_cxxVariableDeclarationFileLine, + DT_cxxVariableDeclaredType, + DT_cxxVariableDefinition, + DT_cxxVariableDetail, + DT_cxxVariableNameLookup, + DT_cxxVariablePrototype, + DT_cxxVariableReimplemented, + DT_cxxVariableScopedName, + DT_cxxVariableStorageClassSpecifierStatic, + DT_data, + DT_dataabout, + DT_dd, + DT_dl, + DT_dlentry, + DT_dt, + DT_entry, + DT_fig, + DT_i, + DT_image, + DT_keyword, + DT_keywords, + DT_li, + DT_link, + DT_linktext, + DT_lq, + DT_metadata, + DT_ol, + DT_othermeta, + DT_p, + DT_parameter, + DT_permissions, + DT_ph, + DT_platform, + DT_pre, + DT_prodinfo, + DT_prodname, + DT_prolog, + DT_publisher, + DT_relatedLinks, + DT_resourceid, + DT_revised, + DT_row, + DT_section, + DT_sectiondiv, + DT_shortdesc, + DT_simpletable, + DT_source, + DT_stentry, + DT_sthead, + DT_strow, + DT_sub, + DT_sup, + DT_table, + DT_tbody, + DT_tgroup, + DT_thead, + DT_title, + DT_tm, + DT_topic, + DT_topicmeta, + DT_topicref, + DT_tt, + DT_u, + DT_ul, + DT_unknown, + DT_vrm, + DT_vrmlist, + DT_xref, + DT_LAST + }; + public: DitaXmlGenerator(); ~DitaXmlGenerator(); @@ -139,6 +315,7 @@ class DitaXmlGenerator : public PageGenerator void writePropertyParameter(const QString& tag, const NodeList& nlist); void writeRelatedLinks(const FakeNode* fake, CodeMarker* marker); void writeLink(const Node* node, const QString& tex, const QString& role); + void writeProlog(const InnerNode* inner, CodeMarker* marker); private: enum SubTitleSize { SmallSubTitle, LargeSubTitle }; @@ -254,27 +431,45 @@ class DitaXmlGenerator : public PageGenerator virtual void endSubPage(); virtual void generateInnerNode(const InnerNode* node); QXmlStreamWriter& xmlWriter(); - void writeDetailedDescription(const Node* node, - CodeMarker* marker, - bool apiDesc, - const QString& title); + void writeApiDesc(const Node* node, CodeMarker* marker, const QString& title); void addLink(const QString& href, const QStringRef& text); void writeDitaMap(); + void writeStartTag(DitaTag t); + void writeEndTag(DitaTag t=DT_NONE); + DitaTag currentTag(); + void clearSectionNesting() { sectionNestingLevel = 0; } + int enterApiDesc(const QString& outputclass, const QString& title); + int enterSection(const QString& outputclass, const QString& title); + int leaveSection(); + bool inSection() const { return (sectionNestingLevel > 0); } + int currentSectionNestingLevel() const { return sectionNestingLevel; } + private: - QMap<QString, QString> refMap; - QMap<QString, QString> name2guidMap; - GuidMaps guidMaps; - int codeIndent; + /* + These flags indicate which elements the generator + is currently outputting. + */ + bool inContents; + bool inDetailedDescription; + bool inLegaleseText; bool inLink; bool inObsoleteLink; - bool inContents; bool inSectionHeading; bool inTableHeader; bool inTableBody; - int numTableRows; - bool threeColumnEnumValueTable; + + bool noLinks; + bool obsoleteLinks; bool offlineDocs; + bool threeColumnEnumValueTable; + + int codeIndent; + int numTableRows; + int divNestingLevel; + int sectionNestingLevel; + int tableColumnCount; + QString link; QStringList sectionNumber; QRegExp funcLeftParen; @@ -288,12 +483,14 @@ class DitaXmlGenerator : public PageGenerator QString projectDescription; QString projectUrl; QString navigationLinks; + QString version; + QStringList vrm; QStringList stylesheets; QStringList customHeadElements; const Tree* myTree; - bool obsoleteLinks; - bool noLinks; - int tableColumnCount; + QMap<QString, QString> refMap; + QMap<QString, QString> name2guidMap; + GuidMaps guidMaps; QMap<QString, NodeMap > moduleClassMap; QMap<QString, NodeMap > moduleNamespaceMap; NodeMap nonCompatClasses; @@ -312,12 +509,9 @@ class DitaXmlGenerator : public PageGenerator NewClassMaps newClassMaps; NewClassMaps newQmlClassMaps; static int id; - static bool inApiDesc; - static bool inSection; - static bool inDetailedDescription; - static bool inLegaleseText; - + static QString ditaTags[]; QStack<QXmlStreamWriter*> xmlWriterStack; + QStack<DitaTag> tagStack; }; #define DITAXMLGENERATOR_ADDRESS "address" diff --git a/tools/qdoc3/doc.cpp b/tools/qdoc3/doc.cpp index a730799..5f563be 100644 --- a/tools/qdoc3/doc.cpp +++ b/tools/qdoc3/doc.cpp @@ -55,6 +55,7 @@ #include <qregexp.h> #include <ctype.h> #include <limits.h> +#include <qdebug.h> QT_BEGIN_NAMESPACE @@ -90,8 +91,8 @@ enum { CMD_QUOTEFROMFILE, CMD_QUOTEFUNCTION, CMD_RAW, CMD_ROW, CMD_SA, CMD_SECTION1, CMD_SECTION2, CMD_SECTION3, CMD_SECTION4, CMD_SIDEBAR, CMD_SINCELIST, CMD_SKIPLINE, - CMD_SKIPTO, CMD_SKIPUNTIL, CMD_SNIPPET, CMD_SUB, CMD_SUP, - CMD_TABLE, CMD_TABLEOFCONTENTS, CMD_TARGET, CMD_TT, + CMD_SKIPTO, CMD_SKIPUNTIL, CMD_SNIPPET, CMD_SPAN, CMD_SUB, + CMD_SUP, CMD_TABLE, CMD_TABLEOFCONTENTS, CMD_TARGET, CMD_TT, CMD_UNDERLINE, CMD_UNICODE, CMD_VALUE, CMD_WARNING, #ifdef QDOC_QML CMD_QML, CMD_ENDQML, CMD_CPP, CMD_ENDCPP, CMD_QMLTEXT, @@ -184,6 +185,7 @@ static struct { { "skipto", CMD_SKIPTO, 0 }, { "skipuntil", CMD_SKIPUNTIL, 0 }, { "snippet", CMD_SNIPPET, 0 }, + { "span", CMD_SPAN, 0 }, { "sub", CMD_SUB, 0 }, { "sup", CMD_SUP, 0 }, { "table", CMD_TABLE, 0 }, @@ -366,14 +368,15 @@ class DocParser void endSection(int unit, int endCmd); void parseAlso(); void append(Atom::Type type, const QString& string = ""); + void append(Atom::Type type, const QString& p1, const QString& p2); void appendChar(QChar ch); void appendWord(const QString &word); void appendToCode(const QString &code); void appendToCode(const QString &code, Atom::Type defaultType); void startNewPara(); void enterPara(Atom::Type leftType = Atom::ParaLeft, - Atom::Type rightType = Atom::ParaRight, - const QString& string = ""); + Atom::Type rightType = Atom::ParaRight, + const QString& string = ""); void leavePara(); void leaveValue(); void leaveValueList(); @@ -405,9 +408,13 @@ class DocParser Location cachedLoc; int cachedPos; - DocPrivate *priv; - enum ParaState { OutsidePara, InsideSingleLinePara, InsideMultiLinePara }; - ParaState paraState; + DocPrivate* priv; + enum ParagraphState { + OutsideParagraph, + InSingleLineParagraph, + InMultiLineParagraph + }; + ParagraphState paraState; bool inTableHeader; bool inTableRow; bool inTableItem; @@ -454,7 +461,7 @@ void DocParser::parse(const QString& source, priv = docPrivate; priv->text << Atom::Nop; - paraState = OutsidePara; + paraState = OutsideParagraph; inTableHeader = false; inTableRow = false; inTableItem = false; @@ -470,7 +477,7 @@ void DocParser::parse(const QString& source, CodeMarker *marker = 0; Atom *currentLinkAtom = 0; - QString x; + QString p1, p2; QStack<bool> preprocessorSkipping; int numPreprocessorSkipping = 0; @@ -509,11 +516,11 @@ void DocParser::parse(const QString& source, switch (cmd) { case CMD_A: enterPara(); - x = getArgument(); + p1 = getArgument(); append(Atom::FormattingLeft,ATOM_FORMATTING_PARAMETER); - append(Atom::String, x); + append(Atom::String, p1); append(Atom::FormattingRight,ATOM_FORMATTING_PARAMETER); - priv->params.insert(x); + priv->params.insert(p1); break; case CMD_ABSTRACT: if (openCommand(cmd)) { @@ -538,20 +545,20 @@ void DocParser::parse(const QString& source, break; case CMD_C: enterPara(); - x = untabifyEtc(getArgument(true)); - marker = CodeMarker::markerForCode(x); - append(Atom::C, marker->markedUpCode(x, 0, location())); + p1 = untabifyEtc(getArgument(true)); + marker = CodeMarker::markerForCode(p1); + append(Atom::C, marker->markedUpCode(p1, 0, location())); break; case CMD_CAPTION: leavePara(); - /* ... */ + enterPara(Atom::CaptionLeft, Atom::CaptionRight); break; case CMD_CHAPTER: startSection(Doc::Chapter, cmd); break; case CMD_CODE: leavePara(); - append(Atom::Code, getCode(CMD_CODE, marker)); + append(Atom::Code, getCode(CMD_CODE, 0)); break; #ifdef QDOC_QML case CMD_QML: @@ -568,10 +575,14 @@ void DocParser::parse(const QString& source, #endif case CMD_DIV: leavePara(); - x = getArgument(true); - append(Atom::Div, x); + p1 = getArgument(true); + append(Atom::DivLeft, p1); openedCommands.push(cmd); - enterPara(); + break; + case CMD_ENDDIV: + leavePara(); + append(Atom::DivRight); + closeCommand(cmd); break; case CMD_CODELINE: { @@ -635,16 +646,11 @@ void DocParser::parse(const QString& source, } break; case CMD_ENDCHAPTER: - endSection(0, cmd); + endSection(Doc::Chapter, cmd); break; case CMD_ENDCODE: closeCommand(cmd); break; - case CMD_ENDDIV: - leavePara(); - append(Atom::EndDiv); - closeCommand(cmd); - break; #ifdef QDOC_QML case CMD_ENDQML: closeCommand(cmd); @@ -660,7 +666,7 @@ void DocParser::parse(const QString& source, if (closeCommand(cmd)) { leavePara(); append(Atom::FootnoteRight); - paraState = InsideMultiLinePara; // ### + paraState = InMultiLineParagraph; // ### } break; case CMD_ENDIF: @@ -747,7 +753,7 @@ void DocParser::parse(const QString& source, if (openCommand(cmd)) { enterPara(); append(Atom::FootnoteLeft); - paraState = OutsidePara; // ### + paraState = OutsideParagraph; // ### } break; case CMD_ANNOTATEDLIST: @@ -807,7 +813,7 @@ void DocParser::parse(const QString& source, append(Atom::String, " "); break; case CMD_INDEX: - if (paraState == OutsidePara) { + if (paraState == OutsideParagraph) { enterPara(); indexStartedPara = true; } @@ -826,23 +832,23 @@ void DocParser::parse(const QString& source, case CMD_L: enterPara(); if (isLeftBraceAhead()) { - x = getArgument(); - append(Atom::Link, x); + p1 = getArgument(); + append(Atom::Link, p1); if (isLeftBraceAhead()) { currentLinkAtom = priv->text.lastAtom(); startFormat(ATOM_FORMATTING_LINK, cmd); } else { append(Atom::FormattingLeft, ATOM_FORMATTING_LINK); - append(Atom::String, cleanLink(x)); + append(Atom::String, cleanLink(p1)); append(Atom::FormattingRight, ATOM_FORMATTING_LINK); } } else { - x = getArgument(); - append(Atom::Link, x); + p1 = getArgument(); + append(Atom::Link, p1); append(Atom::FormattingLeft, ATOM_FORMATTING_LINK); - append(Atom::String, cleanLink(x)); + append(Atom::String, cleanLink(p1)); append(Atom::FormattingRight, ATOM_FORMATTING_LINK); } break; @@ -855,8 +861,8 @@ void DocParser::parse(const QString& source, case CMD_LINK: if (openCommand(cmd)) { enterPara(); - x = getArgument(); - append(Atom::Link, x); + p1 = getArgument(); + append(Atom::Link, p1); append(Atom::FormattingLeft, ATOM_FORMATTING_LINK); skipSpacesOrOneEndl(); } @@ -870,8 +876,8 @@ void DocParser::parse(const QString& source, break; case CMD_META: priv->constructExtra(); - x = getArgument(); - priv->extra->metaMap.insert(x, getRestOfLine()); + p1 = getArgument(); + priv->extra->metaMap.insert(p1, getRestOfLine()); break; case CMD_NEWCODE: location().warning(tr("Unexpected '\\%1'").arg(cmdName(CMD_NEWCODE))); @@ -895,9 +901,13 @@ void DocParser::parse(const QString& source, enterPara(); } else if (openedCommands.top() == CMD_TABLE) { - x = "1,1"; - if (isLeftBraceAhead()) - x = getArgument(); + p1 = "1,1"; + if (isLeftBraceAhead()) { + p1 = getArgument(); + if (isLeftBraceAhead()) { + p2 = getArgument(); + } + } if (!inTableHeader && !inTableRow) { location().warning(tr("Missing '\\%1' or '\\%1' before '\\%3'") @@ -912,7 +922,7 @@ void DocParser::parse(const QString& source, inTableItem = false; } - append(Atom::TableItemLeft, x); + append(Atom::TableItemLeft, p1, p2); inTableItem = true; } else { @@ -931,11 +941,11 @@ void DocParser::parse(const QString& source, getUntilEnd(cmd); break; case CMD_OMITVALUE: - x = getArgument(); - if (!priv->enumItemList.contains(x)) - priv->enumItemList.append(x); - if (!priv->omitEnumItemList.contains(x)) - priv->omitEnumItemList.append(x); + p1 = getArgument(); + if (!priv->enumItemList.contains(p1)) + priv->enumItemList.append(p1); + if (!priv->omitEnumItemList.contains(p1)) + priv->omitEnumItemList.append(p1); break; case CMD_PART: startSection(Doc::Part, cmd); @@ -1004,35 +1014,38 @@ void DocParser::parse(const QString& source, case CMD_QUOTEFUNCTION: leavePara(); marker = quoteFromFile(); - x = getRestOfLine(); + p1 = getRestOfLine(); if (!quoting) { quoter.quoteTo(location(), cmdStr, - slashed(marker->functionBeginRegExp(x))); + slashed(marker->functionBeginRegExp(p1))); append(Atom::Code, quoter.quoteUntil(location(), cmdStr, - slashed(marker->functionEndRegExp(x)))); + slashed(marker->functionEndRegExp(p1)))); quoter.reset(); } else { append(Atom::CodeQuoteCommand, cmdStr); - append(Atom::CodeQuoteArgument, slashed(marker->functionEndRegExp(x))); + append(Atom::CodeQuoteArgument, slashed(marker->functionEndRegExp(p1))); } break; case CMD_RAW: leavePara(); - x = getRestOfLine(); - if (x.isEmpty()) + p1 = getRestOfLine(); + if (p1.isEmpty()) location().warning(tr("Missing format name after '\\%1") .arg(cmdName(CMD_RAW))); - append(Atom::FormatIf, x); + append(Atom::FormatIf, p1); append(Atom::RawString, untabifyEtc(getUntilEnd(cmd))); append(Atom::FormatElse); append(Atom::FormatEndif); break; case CMD_ROW: if (openedCommands.top() == CMD_TABLE) { + p1.clear(); + if (isLeftBraceAhead()) + p1 = getArgument(true); leaveTableRow(); - append(Atom::TableRowLeft); + append(Atom::TableRowLeft,p1); inTableRow = true; } else { @@ -1102,6 +1115,10 @@ void DocParser::parse(const QString& source, append(Atom::CodeQuoteArgument, getRestOfLine()); } break; + case CMD_SPAN: + p1 = ATOM_FORMATTING_SPAN + getArgument(true); + startFormat(p1, cmd); + break; case CMD_SNIPPET: leavePara(); { @@ -1125,22 +1142,22 @@ void DocParser::parse(const QString& source, startFormat(ATOM_FORMATTING_SUPERSCRIPT, cmd); break; case CMD_TABLE: - x = getRestOfLine(); + p1 = getRestOfLine(); if (openCommand(cmd)) { leavePara(); - append(Atom::TableLeft, x); + append(Atom::TableLeft, p1); inTableHeader = false; inTableRow = false; inTableItem = false; } break; case CMD_TABLEOFCONTENTS: - x = "1"; + p1 = "1"; if (isLeftBraceAhead()) - x = getArgument(); - x += ","; - x += QString::number((int)getSectioningUnit()); - append(Atom::TableOfContents, x); + p1 = getArgument(); + p1 += ","; + p1 += QString::number((int)getSectioningUnit()); + append(Atom::TableOfContents, p1); break; case CMD_TARGET: insertTarget(getRestOfLine(),false); @@ -1153,16 +1170,16 @@ void DocParser::parse(const QString& source, break; case CMD_UNICODE: enterPara(); - x = getArgument(); + p1 = getArgument(); { bool ok; - uint unicodeChar = x.toUInt(&ok, 0); + uint unicodeChar = p1.toUInt(&ok, 0); if (!ok || (unicodeChar == 0x0000) || (unicodeChar > 0xFFFE)) { location().warning(tr("Invalid Unicode character '%1' specified " "with '%2'") - .arg(x, cmdName(CMD_UNICODE))); + .arg(p1, cmdName(CMD_UNICODE))); } else { append(Atom::String, QChar(unicodeChar)); @@ -1172,13 +1189,13 @@ void DocParser::parse(const QString& source, case CMD_VALUE: leaveValue(); if (openedLists.top().style() == OpenedList::Value) { - x = getArgument(); - if (!priv->enumItemList.contains(x)) - priv->enumItemList.append(x); + p1 = getArgument(); + if (!priv->enumItemList.contains(p1)) + priv->enumItemList.append(p1); openedLists.top().next(); append(Atom::ListTagLeft, ATOM_LIST_VALUE); - append(Atom::String, x); + append(Atom::String, p1); append(Atom::ListTagRight, ATOM_LIST_VALUE); append(Atom::ListItemLeft, ATOM_LIST_VALUE); @@ -1191,7 +1208,8 @@ void DocParser::parse(const QString& source, } break; case CMD_WARNING: - startNewPara(); + leavePara(); + enterPara(); append(Atom::FormattingLeft, ATOM_FORMATTING_BOLD); append(Atom::String, "Warning:"); append(Atom::FormattingRight, ATOM_FORMATTING_BOLD); @@ -1199,13 +1217,13 @@ void DocParser::parse(const QString& source, break; case CMD_OVERLOAD: priv->metacommandsUsed.insert(cmdStr); - x.clear(); + p1.clear(); if (!isBlankLine()) - x = getRestOfLine(); - if (!x.isEmpty()) { + p1 = getRestOfLine(); + if (!p1.isEmpty()) { append(Atom::ParaLeft); append(Atom::String, "This function overloads "); - append(Atom::AutoLink,x); + append(Atom::AutoLink,p1); append(Atom::String, "."); append(Atom::ParaRight); } @@ -1213,9 +1231,9 @@ void DocParser::parse(const QString& source, append(Atom::ParaLeft); append(Atom::String,"This is an overloaded function."); append(Atom::ParaRight); - x = getMetaCommandArgument(cmdStr); + p1 = getMetaCommandArgument(cmdStr); } - priv->metaCommandMap[cmdStr].append(x); + priv->metaCommandMap[cmdStr].append(p1); break; case NOT_A_CMD: if (metaCommandSet.contains(cmdStr)) { @@ -1281,8 +1299,7 @@ void DocParser::parse(const QString& source, braceDepth--; pos++; - QMap<int, QString>::Iterator f = - pendingFormats.find(braceDepth); + QMap<int, QString>::Iterator f = pendingFormats.find(braceDepth); if (f == pendingFormats.end()) { enterPara(); appendChar('}'); @@ -1319,7 +1336,7 @@ void DocParser::parse(const QString& source, newWord = false; } - if (paraState == OutsidePara) { + if (paraState == OutsideParagraph) { if (ch.isSpace()) { ++pos; newWord = false; @@ -1333,7 +1350,7 @@ void DocParser::parse(const QString& source, if (ch.isSpace()) { ++pos; if ((ch == '\n') && - (paraState == InsideSingleLinePara || + (paraState == InSingleLineParagraph || isBlankLine())) { leavePara(); newWord = false; @@ -1441,7 +1458,7 @@ void DocParser::parse(const QString& source, location().warning(tr("Missing '\\%1'").arg(cmdName(CMD_ENDIF))); } - while (currentSectioningUnit > Doc::Chapter) { + while (currentSectioningUnit >= Doc::Chapter) { int delta = currentSectioningUnit - priv->extra->sectioningUnit; append(Atom::SectionRight, QString::number(delta)); currentSectioningUnit = Doc::SectioningUnit(int(currentSectioningUnit) - 1); @@ -1697,8 +1714,7 @@ bool DocParser::closeCommand(int endCmd) } } else { - location().warning(tr("Unexpected '\\%1'") - .arg(cmdName(endCmd))); + location().warning(tr("Unexpected '\\%1'").arg(cmdName(endCmd))); } return false; } @@ -1816,19 +1832,32 @@ void DocParser::parseAlso() } } +//static bool debug = false; +#if 0 + if (type == Atom::DivLeft) + debug = true; + if (debug) + qDebug() << type << string; + if (type == Atom::DivRight) + debug = false; +#endif + void DocParser::append(Atom::Type type, const QString &string) { Atom::Type lastType = priv->text.lastAtom()->type(); -#ifdef QDOC_QML - if (((lastType == Atom::Code) || (lastType == Atom::Code)) && -#else - if ((lastType == Atom::Code) && -#endif - priv->text.lastAtom()->string().endsWith(QLatin1String("\n\n"))) + if ((lastType == Atom::Code) && priv->text.lastAtom()->string().endsWith(QLatin1String("\n\n"))) priv->text.lastAtom()->chopString(); priv->text << Atom(type, string); } +void DocParser::append(Atom::Type type, const QString& p1, const QString& p2) +{ + Atom::Type lastType = priv->text.lastAtom()->type(); + if ((lastType == Atom::Code) && priv->text.lastAtom()->string().endsWith(QLatin1String("\n\n"))) + priv->text.lastAtom()->chopString(); + priv->text << Atom(type, p1, p2); +} + void DocParser::appendChar(QChar ch) { if (priv->text.lastAtom()->type() != Atom::String) @@ -1883,20 +1912,23 @@ void DocParser::enterPara(Atom::Type leftType, Atom::Type rightType, const QString& string) { - if (paraState == OutsidePara) { - if (priv->text.lastAtom()->type() != Atom::ListItemLeft) + if (paraState == OutsideParagraph) { + + if ((priv->text.lastAtom()->type() != Atom::ListItemLeft) && + (priv->text.lastAtom()->type() != Atom::DivLeft)) { leaveValueList(); + } + append(leftType, string); indexStartedPara = false; pendingParaLeftType = leftType; pendingParaRightType = rightType; pendingParaString = string; - if ( - leftType == Atom::SectionHeadingLeft) { - paraState = InsideSingleLinePara; + if (leftType == Atom::SectionHeadingLeft) { + paraState = InSingleLineParagraph; } else { - paraState = InsideMultiLinePara; + paraState = InMultiLineParagraph; } skipSpacesOrOneEndl(); } @@ -1904,7 +1936,7 @@ void DocParser::enterPara(Atom::Type leftType, void DocParser::leavePara() { - if (paraState != OutsidePara) { + if (paraState != OutsideParagraph) { if (!pendingFormats.isEmpty()) { location().warning(tr("Missing '}'")); pendingFormats.clear(); @@ -1920,7 +1952,7 @@ void DocParser::leavePara() } append(pendingParaRightType, pendingParaString); } - paraState = OutsidePara; + paraState = OutsideParagraph; indexStartedPara = false; pendingParaRightType = Atom::Nop; pendingParaString = ""; @@ -2154,10 +2186,8 @@ QString DocParser::getArgument(bool verbatim) location().warning(tr("Missing '}'")); } else { - while (pos < in.length() && - ((delimDepth > 0) || - ((delimDepth == 0) && - !in[pos].isSpace()))) { + while ((pos < in.length()) && + ((delimDepth > 0) || ((delimDepth == 0) && !in[pos].isSpace()))) { switch (in[pos].unicode()) { case '(': case '[': @@ -2362,6 +2392,9 @@ bool DocParser::isLeftBraceAhead() return numEndl < 2 && i < len && in[i] == '{'; } +/*! + Skips to the next non-space character or EOL. + */ void DocParser::skipSpacesOnLine() { while ((pos < in.length()) && @@ -2370,6 +2403,9 @@ void DocParser::skipSpacesOnLine() ++pos; } +/*! + Skips spaces and on EOL. + */ void DocParser::skipSpacesOrOneEndl() { int firstEndl = -1; diff --git a/tools/qdoc3/doc/config/compat.qdocconf b/tools/qdoc3/doc/config/compat.qdocconf new file mode 100644 index 0000000..4b8d7a4 --- /dev/null +++ b/tools/qdoc3/doc/config/compat.qdocconf @@ -0,0 +1,28 @@ +macro.0 = "\\\\0" +macro.b = "\\\\b" +macro.n = "\\\\n" +macro.r = "\\\\r" +macro.i = "\\o" +macro.i11 = "\\o{1,1}" +macro.i12 = "\\o{1,2}" +macro.i13 = "\\o{1,3}" +macro.i14 = "\\o{1,4}" +macro.i15 = "\\o{1,5}" +macro.i16 = "\\o{1,6}" +macro.i17 = "\\o{1,7}" +macro.i18 = "\\o{1,8}" +macro.i19 = "\\o{1,9}" +macro.i21 = "\\o{2,1}" +macro.i31 = "\\o{3,1}" +macro.i41 = "\\o{4,1}" +macro.i51 = "\\o{5,1}" +macro.i61 = "\\o{6,1}" +macro.i71 = "\\o{7,1}" +macro.i81 = "\\o{8,1}" +macro.i91 = "\\o{9,1}" +macro.img = "\\image" +macro.endquote = "\\endquotation" +macro.relatesto = "\\relates" + +spurious = "Missing comma in .*" \ + "Missing pattern .*" diff --git a/tools/qdoc3/doc/config/macros.qdocconf b/tools/qdoc3/doc/config/macros.qdocconf new file mode 100644 index 0000000..2262daa --- /dev/null +++ b/tools/qdoc3/doc/config/macros.qdocconf @@ -0,0 +1,37 @@ +macro.aacute.HTML = "á" +macro.Aring.HTML = "Å" +macro.aring.HTML = "å" +macro.Auml.HTML = "Ä" +macro.author = "\\bold{Author:}" +macro.br.HTML = "<br />" +macro.BR.HTML = "<br />" +macro.copyright.HTML = "©" +macro.eacute.HTML = "é" +macro.gui = "\\bold" +macro.hr.HTML = "<hr />" +macro.iacute.HTML = "í" +macro.key = "\\bold" +macro.menu = "\\bold" +macro.note = "\\bold{Note:}" +macro.oslash.HTML = "ø" +macro.ouml.HTML = "ö" +macro.QA = "\\e{Qt Assistant}" +macro.QD = "\\e{Qt Designer}" +macro.QL = "\\e{Qt Linguist}" +macro.QQV = "\\e{Qt QML Viewer}" +macro.param = "\\e" +macro.raisedaster.HTML = "<sup>*</sup>" +macro.rarrow.HTML = "→" +macro.reg.HTML = "<sup>®</sup>" +macro.return = "Returns" +macro.starslash = "\\c{*/}" +macro.begincomment = "\\c{/*}" +macro.endcomment = "\\c{*/}" +macro.uuml.HTML = "ü" +macro.mdash.HTML = "—" + +macro.beginfloatleft.HTML = "<div style=\"float: left; margin-right: 2em\">" +macro.beginfloatright.HTML = "<div style=\"float: right; margin-left: 2em\">" +macro.endfloat.HTML = "</div>" +macro.clearfloat.HTML = "<br style=\"clear: both\" />" +macro.emptyspan.HTML = "<span></span>" diff --git a/tools/qdoc3/doc/config/qdoc-online.qdocconf b/tools/qdoc3/doc/config/qdoc-online.qdocconf new file mode 100644 index 0000000..7fd8ed5 --- /dev/null +++ b/tools/qdoc3/doc/config/qdoc-online.qdocconf @@ -0,0 +1,2 @@ +include(qdoc-project.qdocconf) +include(qt-html-templates-online.qdocconf) diff --git a/tools/qdoc3/doc/config/qdoc-project.qdocconf b/tools/qdoc3/doc/config/qdoc-project.qdocconf new file mode 100644 index 0000000..9694052 --- /dev/null +++ b/tools/qdoc3/doc/config/qdoc-project.qdocconf @@ -0,0 +1,47 @@ +include(compat.qdocconf) +include(macros.qdocconf) +include(qt-cpp-ignore.qdocconf) +include(qt-defines.qdocconf) + +indexes = $$QT_BUILD_TREE/doc/html/qt.index + +sourceencoding = UTF-8 +outputencoding = UTF-8 +naturallanguage = en_US + +project = QDoc +description = QDoc3 Manual +url = http://doc.qt.nokia.com/qdoc + +sources.fileextensions = "*.cpp *.qdoc *.mm *.qml" +headers.fileextensions = "*.h *.ch *.h++ *.hh *.hpp *.hxx" +examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml" +examples.imageextensions = "*.png *.jpeg *.jpg *.gif *.mng" + +sourcedirs = .. + +exampledirs = .. \ + ../examples \ + ../../../../examples + +imagedirs = ../../../doc/src/templates/images \ + images + +outputdir = $$QT_BUILD_TREE/tools/qdoc3/doc/html +tagfile = $$QT_BUILD_TREE/tools/qdoc3/doc/html/qdoc.tags + +qhp.projects = QDoc + +qhp.QDoc.file = qdoc.qhp +qhp.QDoc.namespace = com.trolltech.qdoc +qhp.QDoc.virtualFolder = qdoc +qhp.QDoc.indexTitle = QDoc Manual - Table of Contents +qhp.QDoc.indexRoot = + +qhp.QDoc.filterAttributes = qdoc qtrefdoc +qhp.QDoc.customFilters.QDoc.name = QDoc +qhp.QDoc.customFilters.QDoc.filterAttributes = qdoc +qhp.QDoc.subprojects = overviews +qhp.QDoc.subprojects.overviews.title = Overviews +qhp.QDoc.subprojects.overviews.indexTitle = All Overviews and HOWTOs +qhp.QDoc.subprojects.overviews.selectors = fake:page,group,module diff --git a/tools/qdoc3/doc/config/qdoc.qdocconf b/tools/qdoc3/doc/config/qdoc.qdocconf new file mode 100644 index 0000000..c238abe --- /dev/null +++ b/tools/qdoc3/doc/config/qdoc.qdocconf @@ -0,0 +1,2 @@ +include(qdoc-project.qdocconf) +include(qt-html-templates.qdocconf) diff --git a/tools/qdoc3/doc/config/qt-cpp-ignore.qdocconf b/tools/qdoc3/doc/config/qt-cpp-ignore.qdocconf new file mode 100644 index 0000000..044eef4 --- /dev/null +++ b/tools/qdoc3/doc/config/qt-cpp-ignore.qdocconf @@ -0,0 +1,98 @@ +Cpp.ignoretokens = QAXFACTORY_EXPORT \ + QDESIGNER_COMPONENTS_LIBRARY \ + QDESIGNER_EXTENSION_LIBRARY \ + QDESIGNER_SDK_LIBRARY \ + QDESIGNER_SHARED_LIBRARY \ + QDESIGNER_UILIB_LIBRARY \ + QM_EXPORT_CANVAS \ + QM_EXPORT_DNS \ + QM_EXPORT_DOM \ + QM_EXPORT_FTP \ + QM_EXPORT_HTTP \ + QM_EXPORT_ICONVIEW \ + QM_EXPORT_NETWORK \ + QM_EXPORT_OPENGL \ + QM_EXPORT_OPENVG \ + QM_EXPORT_SQL \ + QM_EXPORT_TABLE \ + QM_EXPORT_WORKSPACE \ + QM_EXPORT_XML \ + QT_ASCII_CAST_WARN \ + QT_ASCII_CAST_WARN_CONSTRUCTOR \ + QT_BEGIN_HEADER \ + QT_DESIGNER_STATIC \ + QT_END_HEADER \ + QT_FASTCALL \ + QT_WIDGET_PLUGIN_EXPORT \ + Q_COMPAT_EXPORT \ + Q_CORE_EXPORT \ + Q_CORE_EXPORT_INLINE \ + Q_EXPLICIT \ + Q_EXPORT \ + Q_EXPORT_CODECS_CN \ + Q_EXPORT_CODECS_JP \ + Q_EXPORT_CODECS_KR \ + Q_EXPORT_PLUGIN \ + Q_GFX_INLINE \ + Q_AUTOTEST_EXPORT \ + Q_GUI_EXPORT \ + Q_GUI_EXPORT_INLINE \ + Q_GUI_EXPORT_STYLE_CDE \ + Q_GUI_EXPORT_STYLE_COMPACT \ + Q_GUI_EXPORT_STYLE_MAC \ + Q_GUI_EXPORT_STYLE_MOTIF \ + Q_GUI_EXPORT_STYLE_MOTIFPLUS \ + Q_GUI_EXPORT_STYLE_PLATINUM \ + Q_GUI_EXPORT_STYLE_POCKETPC \ + Q_GUI_EXPORT_STYLE_SGI \ + Q_GUI_EXPORT_STYLE_WINDOWS \ + Q_GUI_EXPORT_STYLE_WINDOWSXP \ + QHELP_EXPORT \ + Q_INLINE_TEMPLATE \ + Q_INTERNAL_WIN_NO_THROW \ + Q_NETWORK_EXPORT \ + Q_OPENGL_EXPORT \ + Q_OPENVG_EXPORT \ + Q_OUTOFLINE_TEMPLATE \ + Q_SQL_EXPORT \ + Q_SVG_EXPORT \ + Q_SCRIPT_EXPORT \ + Q_SCRIPTTOOLS_EXPORT \ + Q_TESTLIB_EXPORT \ + Q_TYPENAME \ + Q_XML_EXPORT \ + Q_XMLSTREAM_EXPORT \ + Q_XMLPATTERNS_EXPORT \ + QDBUS_EXPORT \ + Q_DBUS_EXPORT \ + QT_BEGIN_NAMESPACE \ + QT_BEGIN_INCLUDE_NAMESPACE \ + QT_END_NAMESPACE \ + QT_END_INCLUDE_NAMESPACE \ + PHONON_EXPORT \ + Q_DECLARATIVE_EXPORT \ + Q_GADGET \ + QWEBKIT_EXPORT \ + Q_INVOKABLE +Cpp.ignoredirectives = Q_DECLARE_HANDLE \ + Q_DECLARE_INTERFACE \ + Q_DECLARE_METATYPE \ + Q_DECLARE_OPERATORS_FOR_FLAGS \ + Q_DECLARE_PRIVATE \ + Q_DECLARE_PUBLIC \ + Q_DECLARE_SHARED \ + Q_DECLARE_TR_FUNCTIONS \ + Q_DECLARE_TYPEINFO \ + Q_DISABLE_COPY \ + QT_FORWARD_DECLARE_CLASS \ + Q_DUMMY_COMPARISON_OPERATOR \ + Q_ENUMS \ + Q_FLAGS \ + Q_INTERFACES \ + __attribute__ \ + K_DECLARE_PRIVATE \ + PHONON_OBJECT \ + PHONON_HEIR \ + Q_PRIVATE_PROPERTY \ + Q_DECLARE_PRIVATE_D \ + Q_CLASSINFO diff --git a/tools/qdoc3/doc/config/qt-defines.qdocconf b/tools/qdoc3/doc/config/qt-defines.qdocconf new file mode 100644 index 0000000..50a355f --- /dev/null +++ b/tools/qdoc3/doc/config/qt-defines.qdocconf @@ -0,0 +1,17 @@ +defines = Q_QDOC \ + QT_.*_SUPPORT \ + QT_.*_LIB \ + QT_COMPAT \ + QT_KEYPAD_NAVIGATION \ + QT_NO_EGL \ + QT3_SUPPORT \ + Q_WS_.* \ + Q_OS_.* \ + Q_BYTE_ORDER \ + QT_DEPRECATED \ + Q_NO_USING_KEYWORD \ + __cplusplus + +versionsym = QT_VERSION_STR + +codeindent = 1 diff --git a/tools/qdoc3/doc/config/qt-html-default-styles.qdocconf b/tools/qdoc3/doc/config/qt-html-default-styles.qdocconf new file mode 100644 index 0000000..47e550b --- /dev/null +++ b/tools/qdoc3/doc/config/qt-html-default-styles.qdocconf @@ -0,0 +1,32 @@ +# Define the location of the templates to use. Style sheets and scripts are +# specified relative to the template directory and will be copied into +# subdirectories of the output directory. + +HTML.templatedir = . + +HTML.stylesheets = style/offline.css + +HTML.scripts = + +# Files not referenced in any qdoc file (last four needed by qtdemo) +# See also qhp.Qt.extraFiles +extraimages.HTML = qt-logo.png \ + arrow_down.png \ + breadcrumb.png \ + bullet_gt.png \ + bullet_dn.png \ + bullet_sq.png \ + bullet_up.png \ + horBar.png \ + sprites-combined.png + +# Include the style sheets and scripts used. + +HTML.headerstyles = \ + " <link rel=\"stylesheet\" type=\"text/css\" href=\"style/offline.css\" />\n" + +HTML.headerscripts = + +HTML.endheader = \ + "</head>\n" \ + "<body>\n" diff --git a/tools/qdoc3/doc/config/qt-html-online-styles.qdocconf b/tools/qdoc3/doc/config/qt-html-online-styles.qdocconf new file mode 100644 index 0000000..f915cb4 --- /dev/null +++ b/tools/qdoc3/doc/config/qt-html-online-styles.qdocconf @@ -0,0 +1,72 @@ +# Define the location of the templates to use. Style sheets and scripts are +# specified relative to the template directory and will be copied into +# subdirectories of the output directory. + +HTML.templatedir = . + +HTML.stylesheets = style/narrow.css \ + style/style.css \ + style/style_ie6.css \ + style/style_ie7.css \ + style/style_ie8.css \ + style/superfish.css + +# Adding jquery and functions - providing online tools and search features +HTML.scripts = scripts/functions.js \ + scripts/narrow.js \ + scripts/superfish.js \ + scripts/jquery.js + + +# Files not referenced in any qdoc file. +# See also qhp.Qt.extraFiles +extraimages.HTML = qt-logo.png \ + bg_l.png \ + bg_l_blank.png \ + bg_ll_blank.png \ + bg_ul_blank.png \ + header_bg.png \ + bg_r.png \ + box_bg.png \ + breadcrumb.png \ + bullet_gt.png \ + bullet_dn.png \ + bullet_sq.png \ + bullet_up.png \ + arrow_down.png \ + feedbackground.png \ + horBar.png \ + page.png \ + page_bg.png \ + sprites-combined.png \ + spinner.gif + +# Include the style sheets and scripts used. + +HTML.headerstyles = \ + " <link rel=\"stylesheet\" type=\"text/css\" href=\"style/style.css\" />\n" \ + " <script src=\"scripts/jquery.js\" type=\"text/javascript\"></script>\n" \ + " <script src=\"scripts/functions.js\" type=\"text/javascript\"></script>\n" \ + " <link rel=\"stylesheet\" type=\"text/css\" href=\"style/superfish.css\" />\n" \ + " <link rel=\"stylesheet\" type=\"text/css\" href=\"style/narrow.css\" />\n" \ + " <!--[if IE]>\n" \ + "<meta name=\"MSSmartTagsPreventParsing\" content=\"true\">\n" \ + "<meta http-equiv=\"imagetoolbar\" content=\"no\">\n" \ + "<![endif]-->\n" \ + "<!--[if lt IE 7]>\n" \ + "<link rel=\"stylesheet\" type=\"text/css\" href=\"style/style_ie6.css\">\n" \ + "<![endif]-->\n" \ + "<!--[if IE 7]>\n" \ + "<link rel=\"stylesheet\" type=\"text/css\" href=\"style/style_ie7.css\">\n" \ + "<![endif]-->\n" \ + "<!--[if IE 8]>\n" \ + "<link rel=\"stylesheet\" type=\"text/css\" href=\"style/style_ie8.css\">\n" \ + "<![endif]-->\n\n" + +HTML.headerscripts = \ + "<script src=\"scripts/superfish.js\" type=\"text/javascript\"></script>\n" \ + "<script src=\"scripts/narrow.js\" type=\"text/javascript\"></script>\n\n" + +HTML.endheader = \ + "</head>\n" \ + "<body class=\"\" onload=\"CheckEmptyAndLoadList();\">\n" diff --git a/tools/qdoc3/doc/config/qt-html-templates-online.qdocconf b/tools/qdoc3/doc/config/qt-html-templates-online.qdocconf new file mode 100644 index 0000000..cbf8851 --- /dev/null +++ b/tools/qdoc3/doc/config/qt-html-templates-online.qdocconf @@ -0,0 +1,115 @@ +include(qt-html-online-styles.qdocconf) + +HTML.postheader = \ + " <div class=\"header\" id=\"qtdocheader\">\n" \ + " <div class=\"content\"> \n" \ + " <div id=\"nav-logo\">\n" \ + " <a href=\"index.html\">Home</a></div>\n" \ + " <a href=\"index.html\" class=\"qtref\"><span>QDoc Reference Documentation</span></a>\n" \ + " <div id=\"narrowsearch\"></div>\n" \ + " <div id=\"nav-topright\">\n" \ + " <ul>\n" \ + " <li class=\"nav-topright-home\"><a href=\"http://qt.nokia.com/\">Qt HOME</a></li>\n" \ + " <li class=\"nav-topright-dev\"><a href=\"http://developer.qt.nokia.com/\">DEV</a></li>\n" \ + " <li class=\"nav-topright-labs\"><a href=\"http://labs.qt.nokia.com/blogs/\">LABS</a></li>\n" \ + " <li class=\"nav-topright-doc nav-topright-doc-active\"><a href=\"http://doc.qt.nokia.com/\">\n" \ + " DOC</a></li>\n" \ + " <li class=\"nav-topright-blog\"><a href=\"http://blog.qt.nokia.com/\">BLOG</a></li>\n" \ + " </ul>\n" \ + " </div>\n" \ + " <div id=\"shortCut\">\n" \ + " <ul>\n" \ + " <li class=\"shortCut-topleft-inactive\"><span><a href=\"index.html\">Qt 4.7</a></span></li>\n" \ + " <li class=\"shortCut-topleft-active\"><a href=\"http://doc.qt.nokia.com\">ALL VERSIONS" \ + " </a></li>\n" \ + " </ul>\n" \ + " </div>\n" \ + " </div>\n" \ + " </div>\n" \ + " <div class=\"wrapper\">\n" \ + " <div class=\"hd\">\n" \ + " <span></span>\n" \ + " </div>\n" \ + " <div class=\"bd group\">\n" \ + " <div class=\"wrap\">\n" \ + " <div class=\"toolbar\">\n" \ + " <div class=\"breadcrumb toolblock\">\n" \ + " <ul>\n" \ + " <li class=\"first\"><a href=\"index.html\">Home</a></li>\n" \ + " <!-- Breadcrumbs go here -->\n" + +HTML.postpostheader = \ + " </ul>\n" \ + " </div>\n" \ + " <div class=\"toolbuttons toolblock\">\n" \ + " <ul>\n" \ + " <li id=\"smallA\" class=\"t_button\">A</li>\n" \ + " <li id=\"medA\" class=\"t_button active\">A</li>\n" \ + " <li id=\"bigA\" class=\"t_button\">A</li>\n" \ + " <li id=\"print\" class=\"t_button\"><a href=\"javascript:this.print();\">\n" \ + " <span>Print</span></a></li>\n" \ + " </ul>\n" \ + " </div>\n" \ + " </div>\n" \ + " <div class=\"content mainContent\">\n" + +HTML.footer = \ + " </div>\n" \ + " </div>\n" \ + " </div> \n" \ + " <div class=\"ft\">\n" \ + " <span></span>\n" \ + " </div>\n" \ + " </div> \n" \ + " <div class=\"footer\">\n" \ + " <p>\n" \ + " <acronym title=\"Copyright\">©</acronym> 2008-2011 Nokia Corporation and/or its\n" \ + " subsidiaries. Nokia, Qt and their respective logos are trademarks of Nokia Corporation \n" \ + " in Finland and/or other countries worldwide.</p>\n" \ + " <p>\n" \ + " All other trademarks are property of their respective owners. <a title=\"Privacy Policy\"\n" \ + " href=\"http://qt.nokia.com/about/privacy-policy\">Privacy Policy</a></p>\n" \ + " <br />\n" \ + " <p>\n" \ + " Licensees holding valid Qt Commercial licenses may use this document in accordance with the" \ + " Qt Commercial License Agreement provided with the Software or, alternatively, in accordance" \ + " with the terms contained in a written agreement between you and Nokia.</p>\n" \ + " <p>\n" \ + " Alternatively, this document may be used under the terms of the <a href=\"http://www.gnu.org/licenses/fdl.html\">GNU\n" \ + " Free Documentation License version 1.3</a>\n" \ + " as published by the Free Software Foundation.</p>\n" \ + " </div>\n" + + +# Files not referenced in any qdoc file. +# See also extraimages.HTML +qhp.QDoc.extraFiles = index.html \ + images/bg_l.png \ + images/bg_l_blank.png \ + images/bg_ll_blank.png \ + images/bg_ul_blank.png \ + images/header_bg.png \ + images/bg_r.png \ + images/box_bg.png \ + images/breadcrumb.png \ + images/bullet_gt.png \ + images/bullet_dn.png \ + images/bullet_sq.png \ + images/bullet_up.png \ + images/arrow_down.png \ + images/feedbackground.png \ + images/horBar.png \ + images/page.png \ + images/page_bg.png \ + images/sprites-combined.png \ + images/spinner.gif \ + scripts/functions.js \ + scripts/jquery.js \ + scripts/narrow.js \ + scripts/superfish.js \ + style/narrow.css \ + style/superfish.css \ + style/style_ie6.css \ + style/style_ie7.css \ + style/style_ie8.css \ + style/style.css diff --git a/tools/qdoc3/doc/config/qt-html-templates.qdocconf b/tools/qdoc3/doc/config/qt-html-templates.qdocconf new file mode 100644 index 0000000..e0dc875 --- /dev/null +++ b/tools/qdoc3/doc/config/qt-html-templates.qdocconf @@ -0,0 +1,54 @@ +include(qt-html-default-styles.qdocconf) + +HTML.postheader = \ + "<div class=\"header\" id=\"qtdocheader\">\n" \ + " <div class=\"content\"> \n" \ + " <a href=\"index.html\" class=\"qtref\"><span>Qt Reference Documentation</span></a>\n" \ + " </div>\n" \ + " <div class=\"breadcrumb toolblock\">\n" \ + " <ul>\n" \ + " <li class=\"first\"><a href=\"index.html\">Home</a></li>\n" \ + " <!-- Breadcrumbs go here -->\n" + +HTML.postpostheader = \ + " </ul>\n" \ + " </div>\n" \ + "</div>\n" \ + "<div class=\"content mainContent\">\n" + +HTML.footer = \ + " <div class=\"ft\">\n" \ + " <span></span>\n" \ + " </div>\n" \ + "</div> \n" \ + "<div class=\"footer\">\n" \ + " <p>\n" \ + " <acronym title=\"Copyright\">©</acronym> 2008-2011 Nokia Corporation and/or its\n" \ + " subsidiaries. Nokia, Qt and their respective logos are trademarks of Nokia Corporation \n" \ + " in Finland and/or other countries worldwide.</p>\n" \ + " <p>\n" \ + " All other trademarks are property of their respective owners. <a title=\"Privacy Policy\"\n" \ + " href=\"http://qt.nokia.com/about/privacy-policy\">Privacy Policy</a></p>\n" \ + " <br />\n" \ + " <p>\n" \ + " Licensees holding valid Qt Commercial licenses may use this document in accordance with the" \ + " Qt Commercial License Agreement provided with the Software or, alternatively, in accordance" \ + " with the terms contained in a written agreement between you and Nokia.</p>\n" \ + " <p>\n" \ + " Alternatively, this document may be used under the terms of the <a href=\"http://www.gnu.org/licenses/fdl.html\">GNU\n" \ + " Free Documentation License version 1.3</a>\n" \ + " as published by the Free Software Foundation.</p>\n" \ + "</div>\n" \ + +# Files not referenced in any qdoc file. +# See also extraimages.HTML +qhp.QDoc.extraFiles = index.html \ + images/arrow_down.png \ + images/breadcrumb.png \ + images/bullet_gt.png \ + images/bullet_dn.png \ + images/bullet_sq.png \ + images/bullet_up.png \ + images/horBar.png \ + images/sprites-combined.png \ + style/offline.css diff --git a/tools/qdoc3/doc/config/scripts/functions.js b/tools/qdoc3/doc/config/scripts/functions.js new file mode 100755 index 0000000..62bc535 --- /dev/null +++ b/tools/qdoc3/doc/config/scripts/functions.js @@ -0,0 +1,258 @@ +// Removing search results +function hideSearchResults() { +/* hiding search results as the user clicks on the different categories */ + $('#resultdialog').removeClass('active'); + $("#resultlist").removeClass().addClass('all'); + $("#resultlinks").removeClass().addClass('all'); + $("#searchcount").removeClass().addClass('all'); +} +/* closing the searhc result dialog */ +$('#resultclose').click(function(e) { + e.preventDefault(); + hideSearchResults(); +}); + +$(document.body).click(function() { +}); + +/* START non link areas where cursor should change to pointing hand */ +$('.t_button').mouseover(function() { + $('.t_button').css('cursor','pointer'); +}); +/* END non link areas */ +/* Changing font size to smaller */ +$('#smallA').click(function() { + $('.mainContent .heading,.mainContent h1, .mainContent h2, .mainContent h3, .mainContent p, .mainContent li, .mainContent table').css('font-size','smaller'); + $('.t_button').removeClass('active') + $(this).addClass('active') +}); + +/* Reset font size */ +$('#medA').click(function() { + $('.mainContent .heading').css('font','600 16px/1 Arial'); + $('.mainContent h1').css('font','600 18px/1.2 Arial'); + $('.mainContent h2').css('font','600 16px/1.2 Arial'); + $('.mainContent h3').css('font','600 14px/1.2 Arial'); + $('.mainContent p').css('font','13px/20px Verdana'); + $('.mainContent li').css('font','400 13px/1 Verdana'); + $('.mainContent li').css('line-height','14px'); + $('.mainContent .toc li').css('font', 'normal 10px/1.2 Verdana'); + $('.mainContent table').css('font','13px/1.2 Verdana'); + $('.mainContent .heading').css('font','600 16px/1 Arial'); + $('.mainContent .indexboxcont li').css('font','600 13px/1 Verdana'); + $('.t_button').removeClass('active') + $(this).addClass('active') +}); +/* Changing font size to bigger */ +$('#bigA').click(function() { + $('.mainContent .heading,.mainContent h1, .mainContent h2, .mainContent h3, .mainContent p, .mainContent li, .mainContent table').css('font-size','large'); + $('.mainContent .heading,.mainContent h1, .mainContent h2, .mainContent h3, .mainContent p, .mainContent li, .mainContent table').css('line-height','25px'); + $('.t_button').removeClass('active') + $(this).addClass('active') +}); + +/* Show page content after closing feedback box */ +$('.feedclose').click(function() { + $('.bd').show(); + $('.hd').show(); + $('.footer').show(); + $('#feedbackBox').hide(); + $('#blurpage').hide(); +}); + +/* Hide page content and show feedback box */ +$('.feedback').click(function() { + $('.bd').hide(); + $('.hd').hide(); + $('.footer').hide(); + $('#feedbackBox').show(); + $('#blurpage').show(); +}); +/* Default search URL */ +var qturl = ""; + +/* The next function handles the response data (in xml) returned by the search engine */ + +// Process data sent back from the server. The data is structured as a XML. +/* +XML structure handled by function processNokiaData() +<page> - container for each page returned +<pageWords/> - contains keywords +<pageTitle/> - contains page title/header content +<pageUrl/> - contains page URL - URL relative to root +<pageType> - contains page type - APIPage/Article/Example +</page> +*/ + + +function processNokiaData(response){ +/* fetch the responce from the server using page as the root element */ + var propertyTags = response.getElementsByTagName('page'); + /* reset counters */ + var apiCount = 0; + var articleCount = 0; + var exampleCount = 0; + var full_li_element; + +/* remove any old results */ + $('#resultlist li').remove(); + + + /* running through the elements in the xml structure */ + for (var i=0; i<propertyTags.length; i++) { + /* for every element named pageWords*/ + for (var j=0; j< propertyTags[i].getElementsByTagName('pageWords').length; j++) { + /* start a new list element */ + full_li_element = '<li'; + /* if the pageType element reads APIPage, add class name api */ + if (propertyTags[i].getElementsByTagName('pageType')[0].firstChild.nodeValue == 'APIPage') { + full_li_element += ' class="api"'; + apiCount++; + } + /* if the pageType element reads Article, add class name article */ + else if (propertyTags[i].getElementsByTagName('pageType')[0].firstChild.nodeValue == 'Article') { + full_li_element += ' class="article"'; + articleCount++; + } + /* if the pageType element reads Example, add class name example */ + else if (propertyTags[i].getElementsByTagName('pageType')[0].firstChild.nodeValue == 'Example') { + full_li_element += ' class="example"'; + exampleCount++; + } + /* adding the link element*/ + full_li_element += '><a href="'+qturl; + /* adding the URL attribute*/ + full_li_element += propertyTags[i].getElementsByTagName('pageUrl')[j].firstChild.nodeValue; + /* adding the link title and closing the link and list elements */ + full_li_element += '">' + propertyTags[i].getElementsByTagName('pageWords')[0].firstChild.nodeValue + '</a></li>'; + /* appending the list element to the #resultlist div*/ + $('#resultlist').append(full_li_element); + } + } + + /* if the result is not empty */ + if (propertyTags.length > 0) { + /* add class name active to show the dialog */ + $('#resultdialog').addClass('active'); + /* setting number of hits*/ + $('#resultcount').html(propertyTags.length); + $('#apicount').html(apiCount); + $('#articlecount').html(articleCount); + $('#examplecount').html(exampleCount); + + } + else { + $('#pageType').addClass('red'); + } + + + + // Filtering results in display + $('p#resultlinks a').click(function(e) { + e.preventDefault(); + // Displays API ref pages + if (this.id == "showapiresults") { + $("#resultlist").removeClass().addClass('api'); + $("#resultlinks").removeClass().addClass('api'); + $("#searchcount").removeClass().addClass('api'); + } + // Displays Articles + else if (this.id == "showarticleresults") { + $("#resultlist").removeClass().addClass('article'); + $("#resultlinks").removeClass().addClass('article'); + $("#searchcount").removeClass().addClass('article'); + } + // Displays Examples + if (this.id == "showexampleresults") { + $("#resultlist").removeClass().addClass('example'); + $("#resultlinks").removeClass().addClass('example'); + $("#searchcount").removeClass().addClass('example'); + } + // Displays All + if (this.id == "showallresults") { + $("#resultlist").removeClass().addClass('all'); + $("#resultlinks").removeClass().addClass('all'); + $("#searchcount").removeClass().addClass('all'); + } + }); +} + +//build regular expression object to find empty string or any number of blank +var blankRE=/^\s*$/; + + +function CheckEmptyAndLoadList() +{ + /* Start Extracting information for feedback and adding this to the feedback form */ + var pageUrl = window.location.href; + var pageVal = $('title').html(); + $('#pageType').removeClass('red'); + $('#feedUrl').remove(); + $('#pageVal').remove(); + $('.menuAlert').remove(); + $('#feedform').append('<input id="feedUrl" name="feedUrl" value="'+pageUrl+'" style="display:none;">'); + $('#feedform').append('<input id="pageVal" name="pageVal" value="'+pageVal+'" style="display:none;">'); + /* End Extracting information for feedback and adding this to the feedback form */ + + /* extracts search query */ + var value = document.getElementById('pageType').value; + /* if the search is less than three chars long remove class names and remove elements from old search*/ + if((blankRE.test(value)) || (value.length < 3)) + { + $('#resultdialog').removeClass('active'); + $('#resultlist li').remove(); + } +} + +// Loads on doc ready - prepares search + $(document).ready(function () { + /* fetch page title*/ + var pageTitle = $('title').html(); + /* getting content from search box */ + var currentString = $('#pageType').val() ; + /* if the search box is not empty run CheckEmptyAndLoadList*/ + if(currentString.length < 1){ + CheckEmptyAndLoadList(); + } + + /* on key-up in the search box execute the following */ + $('#pageType').keyup(function () { + /* extract the search box content */ + var searchString = $('#pageType').val() ; + /* if the string is less than three characters */ + if ((searchString == null) || (searchString.length < 3)) { + /* remove classes and elements*/ + $('#pageType').removeClass('loading'); + $('.searching').remove(); + /* run CheckEmptyAndLoadList */ + CheckEmptyAndLoadList(); + + $('.report').remove(); + return; + } + /* if timer checks out */ + if (this.timer) clearTimeout(this.timer); + this.timer = setTimeout(function () { + /* add loading image by adding loading class */ + $('#pageType').addClass('loading'); + $('.searching').remove(); + + /* run the actual search */ + $.ajax({ + contentType: "application/x-www-form-urlencoded", + url: 'http://' + location.host + '/nokiasearch/GetDataServlet', + data: 'searchString='+searchString, + dataType:'xml', + type: 'post', + success: function (response, textStatus) { + /* on success remove loading img */ + $('.searching').remove(); + $('#pageType').removeClass('loading'); + + processNokiaData(response); + + } + }); + }, 500); /* timer set to 500 ms */ + }); + });
\ No newline at end of file diff --git a/tools/qdoc3/doc/config/scripts/jquery.js b/tools/qdoc3/doc/config/scripts/jquery.js new file mode 100755 index 0000000..0c7294c --- /dev/null +++ b/tools/qdoc3/doc/config/scripts/jquery.js @@ -0,0 +1,152 @@ +/*! + * jQuery JavaScript Library v1.4.1 + * http://jquery.com/ + * + * Copyright 2010, John Resig + * Dual licensed under the MIT or GPL Version 2 licenses. + * http://jquery.org/license + * + * Includes Sizzle.js + * http://sizzlejs.com/ + * Copyright 2010, The Dojo Foundation + * Released under the MIT, BSD, and GPL Licenses. + * + * Date: Mon Jan 25 19:43:33 2010 -0500 + */ +(function(z,v){function la(){if(!c.isReady){try{r.documentElement.doScroll("left")}catch(a){setTimeout(la,1);return}c.ready()}}function Ma(a,b){b.src?c.ajax({url:b.src,async:false,dataType:"script"}):c.globalEval(b.text||b.textContent||b.innerHTML||"");b.parentNode&&b.parentNode.removeChild(b)}function X(a,b,d,f,e,i){var j=a.length;if(typeof b==="object"){for(var n in b)X(a,n,b[n],f,e,d);return a}if(d!==v){f=!i&&f&&c.isFunction(d);for(n=0;n<j;n++)e(a[n],b,f?d.call(a[n],n,e(a[n],b)):d,i);return a}return j? +e(a[0],b):null}function J(){return(new Date).getTime()}function Y(){return false}function Z(){return true}function ma(a,b,d){d[0].type=a;return c.event.handle.apply(b,d)}function na(a){var b,d=[],f=[],e=arguments,i,j,n,o,m,s,x=c.extend({},c.data(this,"events").live);if(!(a.button&&a.type==="click")){for(o in x){j=x[o];if(j.live===a.type||j.altLive&&c.inArray(a.type,j.altLive)>-1){i=j.data;i.beforeFilter&&i.beforeFilter[a.type]&&!i.beforeFilter[a.type](a)||f.push(j.selector)}else delete x[o]}i=c(a.target).closest(f, +a.currentTarget);m=0;for(s=i.length;m<s;m++)for(o in x){j=x[o];n=i[m].elem;f=null;if(i[m].selector===j.selector){if(j.live==="mouseenter"||j.live==="mouseleave")f=c(a.relatedTarget).closest(j.selector)[0];if(!f||f!==n)d.push({elem:n,fn:j})}}m=0;for(s=d.length;m<s;m++){i=d[m];a.currentTarget=i.elem;a.data=i.fn.data;if(i.fn.apply(i.elem,e)===false){b=false;break}}return b}}function oa(a,b){return"live."+(a?a+".":"")+b.replace(/\./g,"`").replace(/ /g,"&")}function pa(a){return!a||!a.parentNode||a.parentNode.nodeType=== +11}function qa(a,b){var d=0;b.each(function(){if(this.nodeName===(a[d]&&a[d].nodeName)){var f=c.data(a[d++]),e=c.data(this,f);if(f=f&&f.events){delete e.handle;e.events={};for(var i in f)for(var j in f[i])c.event.add(this,i,f[i][j],f[i][j].data)}}})}function ra(a,b,d){var f,e,i;if(a.length===1&&typeof a[0]==="string"&&a[0].length<512&&a[0].indexOf("<option")<0&&(c.support.checkClone||!sa.test(a[0]))){e=true;if(i=c.fragments[a[0]])if(i!==1)f=i}if(!f){b=b&&b[0]?b[0].ownerDocument||b[0]:r;f=b.createDocumentFragment(); +c.clean(a,b,f,d)}if(e)c.fragments[a[0]]=i?f:1;return{fragment:f,cacheable:e}}function K(a,b){var d={};c.each(ta.concat.apply([],ta.slice(0,b)),function(){d[this]=a});return d}function ua(a){return"scrollTo"in a&&a.document?a:a.nodeType===9?a.defaultView||a.parentWindow:false}var c=function(a,b){return new c.fn.init(a,b)},Na=z.jQuery,Oa=z.$,r=z.document,S,Pa=/^[^<]*(<[\w\W]+>)[^>]*$|^#([\w-]+)$/,Qa=/^.[^:#\[\.,]*$/,Ra=/\S/,Sa=/^(\s|\u00A0)+|(\s|\u00A0)+$/g,Ta=/^<(\w+)\s*\/?>(?:<\/\1>)?$/,O=navigator.userAgent, +va=false,P=[],L,$=Object.prototype.toString,aa=Object.prototype.hasOwnProperty,ba=Array.prototype.push,Q=Array.prototype.slice,wa=Array.prototype.indexOf;c.fn=c.prototype={init:function(a,b){var d,f;if(!a)return this;if(a.nodeType){this.context=this[0]=a;this.length=1;return this}if(typeof a==="string")if((d=Pa.exec(a))&&(d[1]||!b))if(d[1]){f=b?b.ownerDocument||b:r;if(a=Ta.exec(a))if(c.isPlainObject(b)){a=[r.createElement(a[1])];c.fn.attr.call(a,b,true)}else a=[f.createElement(a[1])];else{a=ra([d[1]], +[f]);a=(a.cacheable?a.fragment.cloneNode(true):a.fragment).childNodes}}else{if(b=r.getElementById(d[2])){if(b.id!==d[2])return S.find(a);this.length=1;this[0]=b}this.context=r;this.selector=a;return this}else if(!b&&/^\w+$/.test(a)){this.selector=a;this.context=r;a=r.getElementsByTagName(a)}else return!b||b.jquery?(b||S).find(a):c(b).find(a);else if(c.isFunction(a))return S.ready(a);if(a.selector!==v){this.selector=a.selector;this.context=a.context}return c.isArray(a)?this.setArray(a):c.makeArray(a, +this)},selector:"",jquery:"1.4.1",length:0,size:function(){return this.length},toArray:function(){return Q.call(this,0)},get:function(a){return a==null?this.toArray():a<0?this.slice(a)[0]:this[a]},pushStack:function(a,b,d){a=c(a||null);a.prevObject=this;a.context=this.context;if(b==="find")a.selector=this.selector+(this.selector?" ":"")+d;else if(b)a.selector=this.selector+"."+b+"("+d+")";return a},setArray:function(a){this.length=0;ba.apply(this,a);return this},each:function(a,b){return c.each(this, +a,b)},ready:function(a){c.bindReady();if(c.isReady)a.call(r,c);else P&&P.push(a);return this},eq:function(a){return a===-1?this.slice(a):this.slice(a,+a+1)},first:function(){return this.eq(0)},last:function(){return this.eq(-1)},slice:function(){return this.pushStack(Q.apply(this,arguments),"slice",Q.call(arguments).join(","))},map:function(a){return this.pushStack(c.map(this,function(b,d){return a.call(b,d,b)}))},end:function(){return this.prevObject||c(null)},push:ba,sort:[].sort,splice:[].splice}; +c.fn.init.prototype=c.fn;c.extend=c.fn.extend=function(){var a=arguments[0]||{},b=1,d=arguments.length,f=false,e,i,j,n;if(typeof a==="boolean"){f=a;a=arguments[1]||{};b=2}if(typeof a!=="object"&&!c.isFunction(a))a={};if(d===b){a=this;--b}for(;b<d;b++)if((e=arguments[b])!=null)for(i in e){j=a[i];n=e[i];if(a!==n)if(f&&n&&(c.isPlainObject(n)||c.isArray(n))){j=j&&(c.isPlainObject(j)||c.isArray(j))?j:c.isArray(n)?[]:{};a[i]=c.extend(f,j,n)}else if(n!==v)a[i]=n}return a};c.extend({noConflict:function(a){z.$= +Oa;if(a)z.jQuery=Na;return c},isReady:false,ready:function(){if(!c.isReady){if(!r.body)return setTimeout(c.ready,13);c.isReady=true;if(P){for(var a,b=0;a=P[b++];)a.call(r,c);P=null}c.fn.triggerHandler&&c(r).triggerHandler("ready")}},bindReady:function(){if(!va){va=true;if(r.readyState==="complete")return c.ready();if(r.addEventListener){r.addEventListener("DOMContentLoaded",L,false);z.addEventListener("load",c.ready,false)}else if(r.attachEvent){r.attachEvent("onreadystatechange",L);z.attachEvent("onload", +c.ready);var a=false;try{a=z.frameElement==null}catch(b){}r.documentElement.doScroll&&a&&la()}}},isFunction:function(a){return $.call(a)==="[object Function]"},isArray:function(a){return $.call(a)==="[object Array]"},isPlainObject:function(a){if(!a||$.call(a)!=="[object Object]"||a.nodeType||a.setInterval)return false;if(a.constructor&&!aa.call(a,"constructor")&&!aa.call(a.constructor.prototype,"isPrototypeOf"))return false;var b;for(b in a);return b===v||aa.call(a,b)},isEmptyObject:function(a){for(var b in a)return false; +return true},error:function(a){throw a;},parseJSON:function(a){if(typeof a!=="string"||!a)return null;if(/^[\],:{}\s]*$/.test(a.replace(/\\(?:["\\\/bfnrt]|u[0-9a-fA-F]{4})/g,"@").replace(/"[^"\\\n\r]*"|true|false|null|-?\d+(?:\.\d*)?(?:[eE][+\-]?\d+)?/g,"]").replace(/(?:^|:|,)(?:\s*\[)+/g,"")))return z.JSON&&z.JSON.parse?z.JSON.parse(a):(new Function("return "+a))();else c.error("Invalid JSON: "+a)},noop:function(){},globalEval:function(a){if(a&&Ra.test(a)){var b=r.getElementsByTagName("head")[0]|| +r.documentElement,d=r.createElement("script");d.type="text/javascript";if(c.support.scriptEval)d.appendChild(r.createTextNode(a));else d.text=a;b.insertBefore(d,b.firstChild);b.removeChild(d)}},nodeName:function(a,b){return a.nodeName&&a.nodeName.toUpperCase()===b.toUpperCase()},each:function(a,b,d){var f,e=0,i=a.length,j=i===v||c.isFunction(a);if(d)if(j)for(f in a){if(b.apply(a[f],d)===false)break}else for(;e<i;){if(b.apply(a[e++],d)===false)break}else if(j)for(f in a){if(b.call(a[f],f,a[f])===false)break}else for(d= +a[0];e<i&&b.call(d,e,d)!==false;d=a[++e]);return a},trim:function(a){return(a||"").replace(Sa,"")},makeArray:function(a,b){b=b||[];if(a!=null)a.length==null||typeof a==="string"||c.isFunction(a)||typeof a!=="function"&&a.setInterval?ba.call(b,a):c.merge(b,a);return b},inArray:function(a,b){if(b.indexOf)return b.indexOf(a);for(var d=0,f=b.length;d<f;d++)if(b[d]===a)return d;return-1},merge:function(a,b){var d=a.length,f=0;if(typeof b.length==="number")for(var e=b.length;f<e;f++)a[d++]=b[f];else for(;b[f]!== +v;)a[d++]=b[f++];a.length=d;return a},grep:function(a,b,d){for(var f=[],e=0,i=a.length;e<i;e++)!d!==!b(a[e],e)&&f.push(a[e]);return f},map:function(a,b,d){for(var f=[],e,i=0,j=a.length;i<j;i++){e=b(a[i],i,d);if(e!=null)f[f.length]=e}return f.concat.apply([],f)},guid:1,proxy:function(a,b,d){if(arguments.length===2)if(typeof b==="string"){d=a;a=d[b];b=v}else if(b&&!c.isFunction(b)){d=b;b=v}if(!b&&a)b=function(){return a.apply(d||this,arguments)};if(a)b.guid=a.guid=a.guid||b.guid||c.guid++;return b}, +uaMatch:function(a){a=a.toLowerCase();a=/(webkit)[ \/]([\w.]+)/.exec(a)||/(opera)(?:.*version)?[ \/]([\w.]+)/.exec(a)||/(msie) ([\w.]+)/.exec(a)||!/compatible/.test(a)&&/(mozilla)(?:.*? rv:([\w.]+))?/.exec(a)||[];return{browser:a[1]||"",version:a[2]||"0"}},browser:{}});O=c.uaMatch(O);if(O.browser){c.browser[O.browser]=true;c.browser.version=O.version}if(c.browser.webkit)c.browser.safari=true;if(wa)c.inArray=function(a,b){return wa.call(b,a)};S=c(r);if(r.addEventListener)L=function(){r.removeEventListener("DOMContentLoaded", +L,false);c.ready()};else if(r.attachEvent)L=function(){if(r.readyState==="complete"){r.detachEvent("onreadystatechange",L);c.ready()}};(function(){c.support={};var a=r.documentElement,b=r.createElement("script"),d=r.createElement("div"),f="script"+J();d.style.display="none";d.innerHTML=" <link/><table></table><a href='/a' style='color:red;float:left;opacity:.55;'>a</a><input type='checkbox'/>";var e=d.getElementsByTagName("*"),i=d.getElementsByTagName("a")[0];if(!(!e||!e.length||!i)){c.support= +{leadingWhitespace:d.firstChild.nodeType===3,tbody:!d.getElementsByTagName("tbody").length,htmlSerialize:!!d.getElementsByTagName("link").length,style:/red/.test(i.getAttribute("style")),hrefNormalized:i.getAttribute("href")==="/a",opacity:/^0.55$/.test(i.style.opacity),cssFloat:!!i.style.cssFloat,checkOn:d.getElementsByTagName("input")[0].value==="on",optSelected:r.createElement("select").appendChild(r.createElement("option")).selected,checkClone:false,scriptEval:false,noCloneEvent:true,boxModel:null}; +b.type="text/javascript";try{b.appendChild(r.createTextNode("window."+f+"=1;"))}catch(j){}a.insertBefore(b,a.firstChild);if(z[f]){c.support.scriptEval=true;delete z[f]}a.removeChild(b);if(d.attachEvent&&d.fireEvent){d.attachEvent("onclick",function n(){c.support.noCloneEvent=false;d.detachEvent("onclick",n)});d.cloneNode(true).fireEvent("onclick")}d=r.createElement("div");d.innerHTML="<input type='radio' name='radiotest' checked='checked'/>";a=r.createDocumentFragment();a.appendChild(d.firstChild); +c.support.checkClone=a.cloneNode(true).cloneNode(true).lastChild.checked;c(function(){var n=r.createElement("div");n.style.width=n.style.paddingLeft="1px";r.body.appendChild(n);c.boxModel=c.support.boxModel=n.offsetWidth===2;r.body.removeChild(n).style.display="none"});a=function(n){var o=r.createElement("div");n="on"+n;var m=n in o;if(!m){o.setAttribute(n,"return;");m=typeof o[n]==="function"}return m};c.support.submitBubbles=a("submit");c.support.changeBubbles=a("change");a=b=d=e=i=null}})();c.props= +{"for":"htmlFor","class":"className",readonly:"readOnly",maxlength:"maxLength",cellspacing:"cellSpacing",rowspan:"rowSpan",colspan:"colSpan",tabindex:"tabIndex",usemap:"useMap",frameborder:"frameBorder"};var G="jQuery"+J(),Ua=0,xa={},Va={};c.extend({cache:{},expando:G,noData:{embed:true,object:true,applet:true},data:function(a,b,d){if(!(a.nodeName&&c.noData[a.nodeName.toLowerCase()])){a=a==z?xa:a;var f=a[G],e=c.cache;if(!b&&!f)return null;f||(f=++Ua);if(typeof b==="object"){a[G]=f;e=e[f]=c.extend(true, +{},b)}else e=e[f]?e[f]:typeof d==="undefined"?Va:(e[f]={});if(d!==v){a[G]=f;e[b]=d}return typeof b==="string"?e[b]:e}},removeData:function(a,b){if(!(a.nodeName&&c.noData[a.nodeName.toLowerCase()])){a=a==z?xa:a;var d=a[G],f=c.cache,e=f[d];if(b){if(e){delete e[b];c.isEmptyObject(e)&&c.removeData(a)}}else{try{delete a[G]}catch(i){a.removeAttribute&&a.removeAttribute(G)}delete f[d]}}}});c.fn.extend({data:function(a,b){if(typeof a==="undefined"&&this.length)return c.data(this[0]);else if(typeof a==="object")return this.each(function(){c.data(this, +a)});var d=a.split(".");d[1]=d[1]?"."+d[1]:"";if(b===v){var f=this.triggerHandler("getData"+d[1]+"!",[d[0]]);if(f===v&&this.length)f=c.data(this[0],a);return f===v&&d[1]?this.data(d[0]):f}else return this.trigger("setData"+d[1]+"!",[d[0],b]).each(function(){c.data(this,a,b)})},removeData:function(a){return this.each(function(){c.removeData(this,a)})}});c.extend({queue:function(a,b,d){if(a){b=(b||"fx")+"queue";var f=c.data(a,b);if(!d)return f||[];if(!f||c.isArray(d))f=c.data(a,b,c.makeArray(d));else f.push(d); +return f}},dequeue:function(a,b){b=b||"fx";var d=c.queue(a,b),f=d.shift();if(f==="inprogress")f=d.shift();if(f){b==="fx"&&d.unshift("inprogress");f.call(a,function(){c.dequeue(a,b)})}}});c.fn.extend({queue:function(a,b){if(typeof a!=="string"){b=a;a="fx"}if(b===v)return c.queue(this[0],a);return this.each(function(){var d=c.queue(this,a,b);a==="fx"&&d[0]!=="inprogress"&&c.dequeue(this,a)})},dequeue:function(a){return this.each(function(){c.dequeue(this,a)})},delay:function(a,b){a=c.fx?c.fx.speeds[a]|| +a:a;b=b||"fx";return this.queue(b,function(){var d=this;setTimeout(function(){c.dequeue(d,b)},a)})},clearQueue:function(a){return this.queue(a||"fx",[])}});var ya=/[\n\t]/g,ca=/\s+/,Wa=/\r/g,Xa=/href|src|style/,Ya=/(button|input)/i,Za=/(button|input|object|select|textarea)/i,$a=/^(a|area)$/i,za=/radio|checkbox/;c.fn.extend({attr:function(a,b){return X(this,a,b,true,c.attr)},removeAttr:function(a){return this.each(function(){c.attr(this,a,"");this.nodeType===1&&this.removeAttribute(a)})},addClass:function(a){if(c.isFunction(a))return this.each(function(o){var m= +c(this);m.addClass(a.call(this,o,m.attr("class")))});if(a&&typeof a==="string")for(var b=(a||"").split(ca),d=0,f=this.length;d<f;d++){var e=this[d];if(e.nodeType===1)if(e.className)for(var i=" "+e.className+" ",j=0,n=b.length;j<n;j++){if(i.indexOf(" "+b[j]+" ")<0)e.className+=" "+b[j]}else e.className=a}return this},removeClass:function(a){if(c.isFunction(a))return this.each(function(o){var m=c(this);m.removeClass(a.call(this,o,m.attr("class")))});if(a&&typeof a==="string"||a===v)for(var b=(a||"").split(ca), +d=0,f=this.length;d<f;d++){var e=this[d];if(e.nodeType===1&&e.className)if(a){for(var i=(" "+e.className+" ").replace(ya," "),j=0,n=b.length;j<n;j++)i=i.replace(" "+b[j]+" "," ");e.className=i.substring(1,i.length-1)}else e.className=""}return this},toggleClass:function(a,b){var d=typeof a,f=typeof b==="boolean";if(c.isFunction(a))return this.each(function(e){var i=c(this);i.toggleClass(a.call(this,e,i.attr("class"),b),b)});return this.each(function(){if(d==="string")for(var e,i=0,j=c(this),n=b,o= +a.split(ca);e=o[i++];){n=f?n:!j.hasClass(e);j[n?"addClass":"removeClass"](e)}else if(d==="undefined"||d==="boolean"){this.className&&c.data(this,"__className__",this.className);this.className=this.className||a===false?"":c.data(this,"__className__")||""}})},hasClass:function(a){a=" "+a+" ";for(var b=0,d=this.length;b<d;b++)if((" "+this[b].className+" ").replace(ya," ").indexOf(a)>-1)return true;return false},val:function(a){if(a===v){var b=this[0];if(b){if(c.nodeName(b,"option"))return(b.attributes.value|| +{}).specified?b.value:b.text;if(c.nodeName(b,"select")){var d=b.selectedIndex,f=[],e=b.options;b=b.type==="select-one";if(d<0)return null;var i=b?d:0;for(d=b?d+1:e.length;i<d;i++){var j=e[i];if(j.selected){a=c(j).val();if(b)return a;f.push(a)}}return f}if(za.test(b.type)&&!c.support.checkOn)return b.getAttribute("value")===null?"on":b.value;return(b.value||"").replace(Wa,"")}return v}var n=c.isFunction(a);return this.each(function(o){var m=c(this),s=a;if(this.nodeType===1){if(n)s=a.call(this,o,m.val()); +if(typeof s==="number")s+="";if(c.isArray(s)&&za.test(this.type))this.checked=c.inArray(m.val(),s)>=0;else if(c.nodeName(this,"select")){var x=c.makeArray(s);c("option",this).each(function(){this.selected=c.inArray(c(this).val(),x)>=0});if(!x.length)this.selectedIndex=-1}else this.value=s}})}});c.extend({attrFn:{val:true,css:true,html:true,text:true,data:true,width:true,height:true,offset:true},attr:function(a,b,d,f){if(!a||a.nodeType===3||a.nodeType===8)return v;if(f&&b in c.attrFn)return c(a)[b](d); +f=a.nodeType!==1||!c.isXMLDoc(a);var e=d!==v;b=f&&c.props[b]||b;if(a.nodeType===1){var i=Xa.test(b);if(b in a&&f&&!i){if(e){b==="type"&&Ya.test(a.nodeName)&&a.parentNode&&c.error("type property can't be changed");a[b]=d}if(c.nodeName(a,"form")&&a.getAttributeNode(b))return a.getAttributeNode(b).nodeValue;if(b==="tabIndex")return(b=a.getAttributeNode("tabIndex"))&&b.specified?b.value:Za.test(a.nodeName)||$a.test(a.nodeName)&&a.href?0:v;return a[b]}if(!c.support.style&&f&&b==="style"){if(e)a.style.cssText= +""+d;return a.style.cssText}e&&a.setAttribute(b,""+d);a=!c.support.hrefNormalized&&f&&i?a.getAttribute(b,2):a.getAttribute(b);return a===null?v:a}return c.style(a,b,d)}});var ab=function(a){return a.replace(/[^\w\s\.\|`]/g,function(b){return"\\"+b})};c.event={add:function(a,b,d,f){if(!(a.nodeType===3||a.nodeType===8)){if(a.setInterval&&a!==z&&!a.frameElement)a=z;if(!d.guid)d.guid=c.guid++;if(f!==v){d=c.proxy(d);d.data=f}var e=c.data(a,"events")||c.data(a,"events",{}),i=c.data(a,"handle"),j;if(!i){j= +function(){return typeof c!=="undefined"&&!c.event.triggered?c.event.handle.apply(j.elem,arguments):v};i=c.data(a,"handle",j)}if(i){i.elem=a;b=b.split(/\s+/);for(var n,o=0;n=b[o++];){var m=n.split(".");n=m.shift();if(o>1){d=c.proxy(d);if(f!==v)d.data=f}d.type=m.slice(0).sort().join(".");var s=e[n],x=this.special[n]||{};if(!s){s=e[n]={};if(!x.setup||x.setup.call(a,f,m,d)===false)if(a.addEventListener)a.addEventListener(n,i,false);else a.attachEvent&&a.attachEvent("on"+n,i)}if(x.add)if((m=x.add.call(a, +d,f,m,s))&&c.isFunction(m)){m.guid=m.guid||d.guid;m.data=m.data||d.data;m.type=m.type||d.type;d=m}s[d.guid]=d;this.global[n]=true}a=null}}},global:{},remove:function(a,b,d){if(!(a.nodeType===3||a.nodeType===8)){var f=c.data(a,"events"),e,i,j;if(f){if(b===v||typeof b==="string"&&b.charAt(0)===".")for(i in f)this.remove(a,i+(b||""));else{if(b.type){d=b.handler;b=b.type}b=b.split(/\s+/);for(var n=0;i=b[n++];){var o=i.split(".");i=o.shift();var m=!o.length,s=c.map(o.slice(0).sort(),ab);s=new RegExp("(^|\\.)"+ +s.join("\\.(?:.*\\.)?")+"(\\.|$)");var x=this.special[i]||{};if(f[i]){if(d){j=f[i][d.guid];delete f[i][d.guid]}else for(var A in f[i])if(m||s.test(f[i][A].type))delete f[i][A];x.remove&&x.remove.call(a,o,j);for(e in f[i])break;if(!e){if(!x.teardown||x.teardown.call(a,o)===false)if(a.removeEventListener)a.removeEventListener(i,c.data(a,"handle"),false);else a.detachEvent&&a.detachEvent("on"+i,c.data(a,"handle"));e=null;delete f[i]}}}}for(e in f)break;if(!e){if(A=c.data(a,"handle"))A.elem=null;c.removeData(a, +"events");c.removeData(a,"handle")}}}},trigger:function(a,b,d,f){var e=a.type||a;if(!f){a=typeof a==="object"?a[G]?a:c.extend(c.Event(e),a):c.Event(e);if(e.indexOf("!")>=0){a.type=e=e.slice(0,-1);a.exclusive=true}if(!d){a.stopPropagation();this.global[e]&&c.each(c.cache,function(){this.events&&this.events[e]&&c.event.trigger(a,b,this.handle.elem)})}if(!d||d.nodeType===3||d.nodeType===8)return v;a.result=v;a.target=d;b=c.makeArray(b);b.unshift(a)}a.currentTarget=d;(f=c.data(d,"handle"))&&f.apply(d, +b);f=d.parentNode||d.ownerDocument;try{if(!(d&&d.nodeName&&c.noData[d.nodeName.toLowerCase()]))if(d["on"+e]&&d["on"+e].apply(d,b)===false)a.result=false}catch(i){}if(!a.isPropagationStopped()&&f)c.event.trigger(a,b,f,true);else if(!a.isDefaultPrevented()){d=a.target;var j;if(!(c.nodeName(d,"a")&&e==="click")&&!(d&&d.nodeName&&c.noData[d.nodeName.toLowerCase()])){try{if(d[e]){if(j=d["on"+e])d["on"+e]=null;this.triggered=true;d[e]()}}catch(n){}if(j)d["on"+e]=j;this.triggered=false}}},handle:function(a){var b, +d;a=arguments[0]=c.event.fix(a||z.event);a.currentTarget=this;d=a.type.split(".");a.type=d.shift();b=!d.length&&!a.exclusive;var f=new RegExp("(^|\\.)"+d.slice(0).sort().join("\\.(?:.*\\.)?")+"(\\.|$)");d=(c.data(this,"events")||{})[a.type];for(var e in d){var i=d[e];if(b||f.test(i.type)){a.handler=i;a.data=i.data;i=i.apply(this,arguments);if(i!==v){a.result=i;if(i===false){a.preventDefault();a.stopPropagation()}}if(a.isImmediatePropagationStopped())break}}return a.result},props:"altKey attrChange attrName bubbles button cancelable charCode clientX clientY ctrlKey currentTarget data detail eventPhase fromElement handler keyCode layerX layerY metaKey newValue offsetX offsetY originalTarget pageX pageY prevValue relatedNode relatedTarget screenX screenY shiftKey srcElement target toElement view wheelDelta which".split(" "), +fix:function(a){if(a[G])return a;var b=a;a=c.Event(b);for(var d=this.props.length,f;d;){f=this.props[--d];a[f]=b[f]}if(!a.target)a.target=a.srcElement||r;if(a.target.nodeType===3)a.target=a.target.parentNode;if(!a.relatedTarget&&a.fromElement)a.relatedTarget=a.fromElement===a.target?a.toElement:a.fromElement;if(a.pageX==null&&a.clientX!=null){b=r.documentElement;d=r.body;a.pageX=a.clientX+(b&&b.scrollLeft||d&&d.scrollLeft||0)-(b&&b.clientLeft||d&&d.clientLeft||0);a.pageY=a.clientY+(b&&b.scrollTop|| +d&&d.scrollTop||0)-(b&&b.clientTop||d&&d.clientTop||0)}if(!a.which&&(a.charCode||a.charCode===0?a.charCode:a.keyCode))a.which=a.charCode||a.keyCode;if(!a.metaKey&&a.ctrlKey)a.metaKey=a.ctrlKey;if(!a.which&&a.button!==v)a.which=a.button&1?1:a.button&2?3:a.button&4?2:0;return a},guid:1E8,proxy:c.proxy,special:{ready:{setup:c.bindReady,teardown:c.noop},live:{add:function(a,b){c.extend(a,b||{});a.guid+=b.selector+b.live;b.liveProxy=a;c.event.add(this,b.live,na,b)},remove:function(a){if(a.length){var b= +0,d=new RegExp("(^|\\.)"+a[0]+"(\\.|$)");c.each(c.data(this,"events").live||{},function(){d.test(this.type)&&b++});b<1&&c.event.remove(this,a[0],na)}},special:{}},beforeunload:{setup:function(a,b,d){if(this.setInterval)this.onbeforeunload=d;return false},teardown:function(a,b){if(this.onbeforeunload===b)this.onbeforeunload=null}}}};c.Event=function(a){if(!this.preventDefault)return new c.Event(a);if(a&&a.type){this.originalEvent=a;this.type=a.type}else this.type=a;this.timeStamp=J();this[G]=true}; +c.Event.prototype={preventDefault:function(){this.isDefaultPrevented=Z;var a=this.originalEvent;if(a){a.preventDefault&&a.preventDefault();a.returnValue=false}},stopPropagation:function(){this.isPropagationStopped=Z;var a=this.originalEvent;if(a){a.stopPropagation&&a.stopPropagation();a.cancelBubble=true}},stopImmediatePropagation:function(){this.isImmediatePropagationStopped=Z;this.stopPropagation()},isDefaultPrevented:Y,isPropagationStopped:Y,isImmediatePropagationStopped:Y};var Aa=function(a){for(var b= +a.relatedTarget;b&&b!==this;)try{b=b.parentNode}catch(d){break}if(b!==this){a.type=a.data;c.event.handle.apply(this,arguments)}},Ba=function(a){a.type=a.data;c.event.handle.apply(this,arguments)};c.each({mouseenter:"mouseover",mouseleave:"mouseout"},function(a,b){c.event.special[a]={setup:function(d){c.event.add(this,b,d&&d.selector?Ba:Aa,a)},teardown:function(d){c.event.remove(this,b,d&&d.selector?Ba:Aa)}}});if(!c.support.submitBubbles)c.event.special.submit={setup:function(a,b,d){if(this.nodeName.toLowerCase()!== +"form"){c.event.add(this,"click.specialSubmit."+d.guid,function(f){var e=f.target,i=e.type;if((i==="submit"||i==="image")&&c(e).closest("form").length)return ma("submit",this,arguments)});c.event.add(this,"keypress.specialSubmit."+d.guid,function(f){var e=f.target,i=e.type;if((i==="text"||i==="password")&&c(e).closest("form").length&&f.keyCode===13)return ma("submit",this,arguments)})}else return false},remove:function(a,b){c.event.remove(this,"click.specialSubmit"+(b?"."+b.guid:""));c.event.remove(this, +"keypress.specialSubmit"+(b?"."+b.guid:""))}};if(!c.support.changeBubbles){var da=/textarea|input|select/i;function Ca(a){var b=a.type,d=a.value;if(b==="radio"||b==="checkbox")d=a.checked;else if(b==="select-multiple")d=a.selectedIndex>-1?c.map(a.options,function(f){return f.selected}).join("-"):"";else if(a.nodeName.toLowerCase()==="select")d=a.selectedIndex;return d}function ea(a,b){var d=a.target,f,e;if(!(!da.test(d.nodeName)||d.readOnly)){f=c.data(d,"_change_data");e=Ca(d);if(a.type!=="focusout"|| +d.type!=="radio")c.data(d,"_change_data",e);if(!(f===v||e===f))if(f!=null||e){a.type="change";return c.event.trigger(a,b,d)}}}c.event.special.change={filters:{focusout:ea,click:function(a){var b=a.target,d=b.type;if(d==="radio"||d==="checkbox"||b.nodeName.toLowerCase()==="select")return ea.call(this,a)},keydown:function(a){var b=a.target,d=b.type;if(a.keyCode===13&&b.nodeName.toLowerCase()!=="textarea"||a.keyCode===32&&(d==="checkbox"||d==="radio")||d==="select-multiple")return ea.call(this,a)},beforeactivate:function(a){a= +a.target;a.nodeName.toLowerCase()==="input"&&a.type==="radio"&&c.data(a,"_change_data",Ca(a))}},setup:function(a,b,d){for(var f in T)c.event.add(this,f+".specialChange."+d.guid,T[f]);return da.test(this.nodeName)},remove:function(a,b){for(var d in T)c.event.remove(this,d+".specialChange"+(b?"."+b.guid:""),T[d]);return da.test(this.nodeName)}};var T=c.event.special.change.filters}r.addEventListener&&c.each({focus:"focusin",blur:"focusout"},function(a,b){function d(f){f=c.event.fix(f);f.type=b;return c.event.handle.call(this, +f)}c.event.special[b]={setup:function(){this.addEventListener(a,d,true)},teardown:function(){this.removeEventListener(a,d,true)}}});c.each(["bind","one"],function(a,b){c.fn[b]=function(d,f,e){if(typeof d==="object"){for(var i in d)this[b](i,f,d[i],e);return this}if(c.isFunction(f)){e=f;f=v}var j=b==="one"?c.proxy(e,function(n){c(this).unbind(n,j);return e.apply(this,arguments)}):e;return d==="unload"&&b!=="one"?this.one(d,f,e):this.each(function(){c.event.add(this,d,j,f)})}});c.fn.extend({unbind:function(a, +b){if(typeof a==="object"&&!a.preventDefault){for(var d in a)this.unbind(d,a[d]);return this}return this.each(function(){c.event.remove(this,a,b)})},trigger:function(a,b){return this.each(function(){c.event.trigger(a,b,this)})},triggerHandler:function(a,b){if(this[0]){a=c.Event(a);a.preventDefault();a.stopPropagation();c.event.trigger(a,b,this[0]);return a.result}},toggle:function(a){for(var b=arguments,d=1;d<b.length;)c.proxy(a,b[d++]);return this.click(c.proxy(a,function(f){var e=(c.data(this,"lastToggle"+ +a.guid)||0)%d;c.data(this,"lastToggle"+a.guid,e+1);f.preventDefault();return b[e].apply(this,arguments)||false}))},hover:function(a,b){return this.mouseenter(a).mouseleave(b||a)}});c.each(["live","die"],function(a,b){c.fn[b]=function(d,f,e){var i,j=0;if(c.isFunction(f)){e=f;f=v}for(d=(d||"").split(/\s+/);(i=d[j++])!=null;){i=i==="focus"?"focusin":i==="blur"?"focusout":i==="hover"?d.push("mouseleave")&&"mouseenter":i;b==="live"?c(this.context).bind(oa(i,this.selector),{data:f,selector:this.selector, +live:i},e):c(this.context).unbind(oa(i,this.selector),e?{guid:e.guid+this.selector+i}:null)}return this}});c.each("blur focus focusin focusout load resize scroll unload click dblclick mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave change select submit keydown keypress keyup error".split(" "),function(a,b){c.fn[b]=function(d){return d?this.bind(b,d):this.trigger(b)};if(c.attrFn)c.attrFn[b]=true});z.attachEvent&&!z.addEventListener&&z.attachEvent("onunload",function(){for(var a in c.cache)if(c.cache[a].handle)try{c.event.remove(c.cache[a].handle.elem)}catch(b){}}); +(function(){function a(g){for(var h="",k,l=0;g[l];l++){k=g[l];if(k.nodeType===3||k.nodeType===4)h+=k.nodeValue;else if(k.nodeType!==8)h+=a(k.childNodes)}return h}function b(g,h,k,l,q,p){q=0;for(var u=l.length;q<u;q++){var t=l[q];if(t){t=t[g];for(var y=false;t;){if(t.sizcache===k){y=l[t.sizset];break}if(t.nodeType===1&&!p){t.sizcache=k;t.sizset=q}if(t.nodeName.toLowerCase()===h){y=t;break}t=t[g]}l[q]=y}}}function d(g,h,k,l,q,p){q=0;for(var u=l.length;q<u;q++){var t=l[q];if(t){t=t[g];for(var y=false;t;){if(t.sizcache=== +k){y=l[t.sizset];break}if(t.nodeType===1){if(!p){t.sizcache=k;t.sizset=q}if(typeof h!=="string"){if(t===h){y=true;break}}else if(o.filter(h,[t]).length>0){y=t;break}}t=t[g]}l[q]=y}}}var f=/((?:\((?:\([^()]+\)|[^()]+)+\)|\[(?:\[[^[\]]*\]|['"][^'"]*['"]|[^[\]'"]+)+\]|\\.|[^ >+~,(\[\\]+)+|[>+~])(\s*,\s*)?((?:.|\r|\n)*)/g,e=0,i=Object.prototype.toString,j=false,n=true;[0,0].sort(function(){n=false;return 0});var o=function(g,h,k,l){k=k||[];var q=h=h||r;if(h.nodeType!==1&&h.nodeType!==9)return[];if(!g|| +typeof g!=="string")return k;for(var p=[],u,t,y,R,H=true,M=w(h),I=g;(f.exec(""),u=f.exec(I))!==null;){I=u[3];p.push(u[1]);if(u[2]){R=u[3];break}}if(p.length>1&&s.exec(g))if(p.length===2&&m.relative[p[0]])t=fa(p[0]+p[1],h);else for(t=m.relative[p[0]]?[h]:o(p.shift(),h);p.length;){g=p.shift();if(m.relative[g])g+=p.shift();t=fa(g,t)}else{if(!l&&p.length>1&&h.nodeType===9&&!M&&m.match.ID.test(p[0])&&!m.match.ID.test(p[p.length-1])){u=o.find(p.shift(),h,M);h=u.expr?o.filter(u.expr,u.set)[0]:u.set[0]}if(h){u= +l?{expr:p.pop(),set:A(l)}:o.find(p.pop(),p.length===1&&(p[0]==="~"||p[0]==="+")&&h.parentNode?h.parentNode:h,M);t=u.expr?o.filter(u.expr,u.set):u.set;if(p.length>0)y=A(t);else H=false;for(;p.length;){var D=p.pop();u=D;if(m.relative[D])u=p.pop();else D="";if(u==null)u=h;m.relative[D](y,u,M)}}else y=[]}y||(y=t);y||o.error(D||g);if(i.call(y)==="[object Array]")if(H)if(h&&h.nodeType===1)for(g=0;y[g]!=null;g++){if(y[g]&&(y[g]===true||y[g].nodeType===1&&E(h,y[g])))k.push(t[g])}else for(g=0;y[g]!=null;g++)y[g]&& +y[g].nodeType===1&&k.push(t[g]);else k.push.apply(k,y);else A(y,k);if(R){o(R,q,k,l);o.uniqueSort(k)}return k};o.uniqueSort=function(g){if(C){j=n;g.sort(C);if(j)for(var h=1;h<g.length;h++)g[h]===g[h-1]&&g.splice(h--,1)}return g};o.matches=function(g,h){return o(g,null,null,h)};o.find=function(g,h,k){var l,q;if(!g)return[];for(var p=0,u=m.order.length;p<u;p++){var t=m.order[p];if(q=m.leftMatch[t].exec(g)){var y=q[1];q.splice(1,1);if(y.substr(y.length-1)!=="\\"){q[1]=(q[1]||"").replace(/\\/g,"");l=m.find[t](q, +h,k);if(l!=null){g=g.replace(m.match[t],"");break}}}}l||(l=h.getElementsByTagName("*"));return{set:l,expr:g}};o.filter=function(g,h,k,l){for(var q=g,p=[],u=h,t,y,R=h&&h[0]&&w(h[0]);g&&h.length;){for(var H in m.filter)if((t=m.leftMatch[H].exec(g))!=null&&t[2]){var M=m.filter[H],I,D;D=t[1];y=false;t.splice(1,1);if(D.substr(D.length-1)!=="\\"){if(u===p)p=[];if(m.preFilter[H])if(t=m.preFilter[H](t,u,k,p,l,R)){if(t===true)continue}else y=I=true;if(t)for(var U=0;(D=u[U])!=null;U++)if(D){I=M(D,t,U,u);var Da= +l^!!I;if(k&&I!=null)if(Da)y=true;else u[U]=false;else if(Da){p.push(D);y=true}}if(I!==v){k||(u=p);g=g.replace(m.match[H],"");if(!y)return[];break}}}if(g===q)if(y==null)o.error(g);else break;q=g}return u};o.error=function(g){throw"Syntax error, unrecognized expression: "+g;};var m=o.selectors={order:["ID","NAME","TAG"],match:{ID:/#((?:[\w\u00c0-\uFFFF-]|\\.)+)/,CLASS:/\.((?:[\w\u00c0-\uFFFF-]|\\.)+)/,NAME:/\[name=['"]*((?:[\w\u00c0-\uFFFF-]|\\.)+)['"]*\]/,ATTR:/\[\s*((?:[\w\u00c0-\uFFFF-]|\\.)+)\s*(?:(\S?=)\s*(['"]*)(.*?)\3|)\s*\]/, +TAG:/^((?:[\w\u00c0-\uFFFF\*-]|\\.)+)/,CHILD:/:(only|nth|last|first)-child(?:\((even|odd|[\dn+-]*)\))?/,POS:/:(nth|eq|gt|lt|first|last|even|odd)(?:\((\d*)\))?(?=[^-]|$)/,PSEUDO:/:((?:[\w\u00c0-\uFFFF-]|\\.)+)(?:\((['"]?)((?:\([^\)]+\)|[^\(\)]*)+)\2\))?/},leftMatch:{},attrMap:{"class":"className","for":"htmlFor"},attrHandle:{href:function(g){return g.getAttribute("href")}},relative:{"+":function(g,h){var k=typeof h==="string",l=k&&!/\W/.test(h);k=k&&!l;if(l)h=h.toLowerCase();l=0;for(var q=g.length, +p;l<q;l++)if(p=g[l]){for(;(p=p.previousSibling)&&p.nodeType!==1;);g[l]=k||p&&p.nodeName.toLowerCase()===h?p||false:p===h}k&&o.filter(h,g,true)},">":function(g,h){var k=typeof h==="string";if(k&&!/\W/.test(h)){h=h.toLowerCase();for(var l=0,q=g.length;l<q;l++){var p=g[l];if(p){k=p.parentNode;g[l]=k.nodeName.toLowerCase()===h?k:false}}}else{l=0;for(q=g.length;l<q;l++)if(p=g[l])g[l]=k?p.parentNode:p.parentNode===h;k&&o.filter(h,g,true)}},"":function(g,h,k){var l=e++,q=d;if(typeof h==="string"&&!/\W/.test(h)){var p= +h=h.toLowerCase();q=b}q("parentNode",h,l,g,p,k)},"~":function(g,h,k){var l=e++,q=d;if(typeof h==="string"&&!/\W/.test(h)){var p=h=h.toLowerCase();q=b}q("previousSibling",h,l,g,p,k)}},find:{ID:function(g,h,k){if(typeof h.getElementById!=="undefined"&&!k)return(g=h.getElementById(g[1]))?[g]:[]},NAME:function(g,h){if(typeof h.getElementsByName!=="undefined"){var k=[];h=h.getElementsByName(g[1]);for(var l=0,q=h.length;l<q;l++)h[l].getAttribute("name")===g[1]&&k.push(h[l]);return k.length===0?null:k}}, +TAG:function(g,h){return h.getElementsByTagName(g[1])}},preFilter:{CLASS:function(g,h,k,l,q,p){g=" "+g[1].replace(/\\/g,"")+" ";if(p)return g;p=0;for(var u;(u=h[p])!=null;p++)if(u)if(q^(u.className&&(" "+u.className+" ").replace(/[\t\n]/g," ").indexOf(g)>=0))k||l.push(u);else if(k)h[p]=false;return false},ID:function(g){return g[1].replace(/\\/g,"")},TAG:function(g){return g[1].toLowerCase()},CHILD:function(g){if(g[1]==="nth"){var h=/(-?)(\d*)n((?:\+|-)?\d*)/.exec(g[2]==="even"&&"2n"||g[2]==="odd"&& +"2n+1"||!/\D/.test(g[2])&&"0n+"+g[2]||g[2]);g[2]=h[1]+(h[2]||1)-0;g[3]=h[3]-0}g[0]=e++;return g},ATTR:function(g,h,k,l,q,p){h=g[1].replace(/\\/g,"");if(!p&&m.attrMap[h])g[1]=m.attrMap[h];if(g[2]==="~=")g[4]=" "+g[4]+" ";return g},PSEUDO:function(g,h,k,l,q){if(g[1]==="not")if((f.exec(g[3])||"").length>1||/^\w/.test(g[3]))g[3]=o(g[3],null,null,h);else{g=o.filter(g[3],h,k,true^q);k||l.push.apply(l,g);return false}else if(m.match.POS.test(g[0])||m.match.CHILD.test(g[0]))return true;return g},POS:function(g){g.unshift(true); +return g}},filters:{enabled:function(g){return g.disabled===false&&g.type!=="hidden"},disabled:function(g){return g.disabled===true},checked:function(g){return g.checked===true},selected:function(g){return g.selected===true},parent:function(g){return!!g.firstChild},empty:function(g){return!g.firstChild},has:function(g,h,k){return!!o(k[3],g).length},header:function(g){return/h\d/i.test(g.nodeName)},text:function(g){return"text"===g.type},radio:function(g){return"radio"===g.type},checkbox:function(g){return"checkbox"=== +g.type},file:function(g){return"file"===g.type},password:function(g){return"password"===g.type},submit:function(g){return"submit"===g.type},image:function(g){return"image"===g.type},reset:function(g){return"reset"===g.type},button:function(g){return"button"===g.type||g.nodeName.toLowerCase()==="button"},input:function(g){return/input|select|textarea|button/i.test(g.nodeName)}},setFilters:{first:function(g,h){return h===0},last:function(g,h,k,l){return h===l.length-1},even:function(g,h){return h%2=== +0},odd:function(g,h){return h%2===1},lt:function(g,h,k){return h<k[3]-0},gt:function(g,h,k){return h>k[3]-0},nth:function(g,h,k){return k[3]-0===h},eq:function(g,h,k){return k[3]-0===h}},filter:{PSEUDO:function(g,h,k,l){var q=h[1],p=m.filters[q];if(p)return p(g,k,h,l);else if(q==="contains")return(g.textContent||g.innerText||a([g])||"").indexOf(h[3])>=0;else if(q==="not"){h=h[3];k=0;for(l=h.length;k<l;k++)if(h[k]===g)return false;return true}else o.error("Syntax error, unrecognized expression: "+ +q)},CHILD:function(g,h){var k=h[1],l=g;switch(k){case "only":case "first":for(;l=l.previousSibling;)if(l.nodeType===1)return false;if(k==="first")return true;l=g;case "last":for(;l=l.nextSibling;)if(l.nodeType===1)return false;return true;case "nth":k=h[2];var q=h[3];if(k===1&&q===0)return true;h=h[0];var p=g.parentNode;if(p&&(p.sizcache!==h||!g.nodeIndex)){var u=0;for(l=p.firstChild;l;l=l.nextSibling)if(l.nodeType===1)l.nodeIndex=++u;p.sizcache=h}g=g.nodeIndex-q;return k===0?g===0:g%k===0&&g/k>= +0}},ID:function(g,h){return g.nodeType===1&&g.getAttribute("id")===h},TAG:function(g,h){return h==="*"&&g.nodeType===1||g.nodeName.toLowerCase()===h},CLASS:function(g,h){return(" "+(g.className||g.getAttribute("class"))+" ").indexOf(h)>-1},ATTR:function(g,h){var k=h[1];g=m.attrHandle[k]?m.attrHandle[k](g):g[k]!=null?g[k]:g.getAttribute(k);k=g+"";var l=h[2];h=h[4];return g==null?l==="!=":l==="="?k===h:l==="*="?k.indexOf(h)>=0:l==="~="?(" "+k+" ").indexOf(h)>=0:!h?k&&g!==false:l==="!="?k!==h:l==="^="? +k.indexOf(h)===0:l==="$="?k.substr(k.length-h.length)===h:l==="|="?k===h||k.substr(0,h.length+1)===h+"-":false},POS:function(g,h,k,l){var q=m.setFilters[h[2]];if(q)return q(g,k,h,l)}}},s=m.match.POS;for(var x in m.match){m.match[x]=new RegExp(m.match[x].source+/(?![^\[]*\])(?![^\(]*\))/.source);m.leftMatch[x]=new RegExp(/(^(?:.|\r|\n)*?)/.source+m.match[x].source.replace(/\\(\d+)/g,function(g,h){return"\\"+(h-0+1)}))}var A=function(g,h){g=Array.prototype.slice.call(g,0);if(h){h.push.apply(h,g);return h}return g}; +try{Array.prototype.slice.call(r.documentElement.childNodes,0)}catch(B){A=function(g,h){h=h||[];if(i.call(g)==="[object Array]")Array.prototype.push.apply(h,g);else if(typeof g.length==="number")for(var k=0,l=g.length;k<l;k++)h.push(g[k]);else for(k=0;g[k];k++)h.push(g[k]);return h}}var C;if(r.documentElement.compareDocumentPosition)C=function(g,h){if(!g.compareDocumentPosition||!h.compareDocumentPosition){if(g==h)j=true;return g.compareDocumentPosition?-1:1}g=g.compareDocumentPosition(h)&4?-1:g=== +h?0:1;if(g===0)j=true;return g};else if("sourceIndex"in r.documentElement)C=function(g,h){if(!g.sourceIndex||!h.sourceIndex){if(g==h)j=true;return g.sourceIndex?-1:1}g=g.sourceIndex-h.sourceIndex;if(g===0)j=true;return g};else if(r.createRange)C=function(g,h){if(!g.ownerDocument||!h.ownerDocument){if(g==h)j=true;return g.ownerDocument?-1:1}var k=g.ownerDocument.createRange(),l=h.ownerDocument.createRange();k.setStart(g,0);k.setEnd(g,0);l.setStart(h,0);l.setEnd(h,0);g=k.compareBoundaryPoints(Range.START_TO_END, +l);if(g===0)j=true;return g};(function(){var g=r.createElement("div"),h="script"+(new Date).getTime();g.innerHTML="<a name='"+h+"'/>";var k=r.documentElement;k.insertBefore(g,k.firstChild);if(r.getElementById(h)){m.find.ID=function(l,q,p){if(typeof q.getElementById!=="undefined"&&!p)return(q=q.getElementById(l[1]))?q.id===l[1]||typeof q.getAttributeNode!=="undefined"&&q.getAttributeNode("id").nodeValue===l[1]?[q]:v:[]};m.filter.ID=function(l,q){var p=typeof l.getAttributeNode!=="undefined"&&l.getAttributeNode("id"); +return l.nodeType===1&&p&&p.nodeValue===q}}k.removeChild(g);k=g=null})();(function(){var g=r.createElement("div");g.appendChild(r.createComment(""));if(g.getElementsByTagName("*").length>0)m.find.TAG=function(h,k){k=k.getElementsByTagName(h[1]);if(h[1]==="*"){h=[];for(var l=0;k[l];l++)k[l].nodeType===1&&h.push(k[l]);k=h}return k};g.innerHTML="<a href='#'></a>";if(g.firstChild&&typeof g.firstChild.getAttribute!=="undefined"&&g.firstChild.getAttribute("href")!=="#")m.attrHandle.href=function(h){return h.getAttribute("href", +2)};g=null})();r.querySelectorAll&&function(){var g=o,h=r.createElement("div");h.innerHTML="<p class='TEST'></p>";if(!(h.querySelectorAll&&h.querySelectorAll(".TEST").length===0)){o=function(l,q,p,u){q=q||r;if(!u&&q.nodeType===9&&!w(q))try{return A(q.querySelectorAll(l),p)}catch(t){}return g(l,q,p,u)};for(var k in g)o[k]=g[k];h=null}}();(function(){var g=r.createElement("div");g.innerHTML="<div class='test e'></div><div class='test'></div>";if(!(!g.getElementsByClassName||g.getElementsByClassName("e").length=== +0)){g.lastChild.className="e";if(g.getElementsByClassName("e").length!==1){m.order.splice(1,0,"CLASS");m.find.CLASS=function(h,k,l){if(typeof k.getElementsByClassName!=="undefined"&&!l)return k.getElementsByClassName(h[1])};g=null}}})();var E=r.compareDocumentPosition?function(g,h){return g.compareDocumentPosition(h)&16}:function(g,h){return g!==h&&(g.contains?g.contains(h):true)},w=function(g){return(g=(g?g.ownerDocument||g:0).documentElement)?g.nodeName!=="HTML":false},fa=function(g,h){var k=[], +l="",q;for(h=h.nodeType?[h]:h;q=m.match.PSEUDO.exec(g);){l+=q[0];g=g.replace(m.match.PSEUDO,"")}g=m.relative[g]?g+"*":g;q=0;for(var p=h.length;q<p;q++)o(g,h[q],k);return o.filter(l,k)};c.find=o;c.expr=o.selectors;c.expr[":"]=c.expr.filters;c.unique=o.uniqueSort;c.getText=a;c.isXMLDoc=w;c.contains=E})();var bb=/Until$/,cb=/^(?:parents|prevUntil|prevAll)/,db=/,/;Q=Array.prototype.slice;var Ea=function(a,b,d){if(c.isFunction(b))return c.grep(a,function(e,i){return!!b.call(e,i,e)===d});else if(b.nodeType)return c.grep(a, +function(e){return e===b===d});else if(typeof b==="string"){var f=c.grep(a,function(e){return e.nodeType===1});if(Qa.test(b))return c.filter(b,f,!d);else b=c.filter(b,f)}return c.grep(a,function(e){return c.inArray(e,b)>=0===d})};c.fn.extend({find:function(a){for(var b=this.pushStack("","find",a),d=0,f=0,e=this.length;f<e;f++){d=b.length;c.find(a,this[f],b);if(f>0)for(var i=d;i<b.length;i++)for(var j=0;j<d;j++)if(b[j]===b[i]){b.splice(i--,1);break}}return b},has:function(a){var b=c(a);return this.filter(function(){for(var d= +0,f=b.length;d<f;d++)if(c.contains(this,b[d]))return true})},not:function(a){return this.pushStack(Ea(this,a,false),"not",a)},filter:function(a){return this.pushStack(Ea(this,a,true),"filter",a)},is:function(a){return!!a&&c.filter(a,this).length>0},closest:function(a,b){if(c.isArray(a)){var d=[],f=this[0],e,i={},j;if(f&&a.length){e=0;for(var n=a.length;e<n;e++){j=a[e];i[j]||(i[j]=c.expr.match.POS.test(j)?c(j,b||this.context):j)}for(;f&&f.ownerDocument&&f!==b;){for(j in i){e=i[j];if(e.jquery?e.index(f)> +-1:c(f).is(e)){d.push({selector:j,elem:f});delete i[j]}}f=f.parentNode}}return d}var o=c.expr.match.POS.test(a)?c(a,b||this.context):null;return this.map(function(m,s){for(;s&&s.ownerDocument&&s!==b;){if(o?o.index(s)>-1:c(s).is(a))return s;s=s.parentNode}return null})},index:function(a){if(!a||typeof a==="string")return c.inArray(this[0],a?c(a):this.parent().children());return c.inArray(a.jquery?a[0]:a,this)},add:function(a,b){a=typeof a==="string"?c(a,b||this.context):c.makeArray(a);b=c.merge(this.get(), +a);return this.pushStack(pa(a[0])||pa(b[0])?b:c.unique(b))},andSelf:function(){return this.add(this.prevObject)}});c.each({parent:function(a){return(a=a.parentNode)&&a.nodeType!==11?a:null},parents:function(a){return c.dir(a,"parentNode")},parentsUntil:function(a,b,d){return c.dir(a,"parentNode",d)},next:function(a){return c.nth(a,2,"nextSibling")},prev:function(a){return c.nth(a,2,"previousSibling")},nextAll:function(a){return c.dir(a,"nextSibling")},prevAll:function(a){return c.dir(a,"previousSibling")}, +nextUntil:function(a,b,d){return c.dir(a,"nextSibling",d)},prevUntil:function(a,b,d){return c.dir(a,"previousSibling",d)},siblings:function(a){return c.sibling(a.parentNode.firstChild,a)},children:function(a){return c.sibling(a.firstChild)},contents:function(a){return c.nodeName(a,"iframe")?a.contentDocument||a.contentWindow.document:c.makeArray(a.childNodes)}},function(a,b){c.fn[a]=function(d,f){var e=c.map(this,b,d);bb.test(a)||(f=d);if(f&&typeof f==="string")e=c.filter(f,e);e=this.length>1?c.unique(e): +e;if((this.length>1||db.test(f))&&cb.test(a))e=e.reverse();return this.pushStack(e,a,Q.call(arguments).join(","))}});c.extend({filter:function(a,b,d){if(d)a=":not("+a+")";return c.find.matches(a,b)},dir:function(a,b,d){var f=[];for(a=a[b];a&&a.nodeType!==9&&(d===v||a.nodeType!==1||!c(a).is(d));){a.nodeType===1&&f.push(a);a=a[b]}return f},nth:function(a,b,d){b=b||1;for(var f=0;a;a=a[d])if(a.nodeType===1&&++f===b)break;return a},sibling:function(a,b){for(var d=[];a;a=a.nextSibling)a.nodeType===1&&a!== +b&&d.push(a);return d}});var Fa=/ jQuery\d+="(?:\d+|null)"/g,V=/^\s+/,Ga=/(<([\w:]+)[^>]*?)\/>/g,eb=/^(?:area|br|col|embed|hr|img|input|link|meta|param)$/i,Ha=/<([\w:]+)/,fb=/<tbody/i,gb=/<|&\w+;/,sa=/checked\s*(?:[^=]|=\s*.checked.)/i,Ia=function(a,b,d){return eb.test(d)?a:b+"></"+d+">"},F={option:[1,"<select multiple='multiple'>","</select>"],legend:[1,"<fieldset>","</fieldset>"],thead:[1,"<table>","</table>"],tr:[2,"<table><tbody>","</tbody></table>"],td:[3,"<table><tbody><tr>","</tr></tbody></table>"], +col:[2,"<table><tbody></tbody><colgroup>","</colgroup></table>"],area:[1,"<map>","</map>"],_default:[0,"",""]};F.optgroup=F.option;F.tbody=F.tfoot=F.colgroup=F.caption=F.thead;F.th=F.td;if(!c.support.htmlSerialize)F._default=[1,"div<div>","</div>"];c.fn.extend({text:function(a){if(c.isFunction(a))return this.each(function(b){var d=c(this);d.text(a.call(this,b,d.text()))});if(typeof a!=="object"&&a!==v)return this.empty().append((this[0]&&this[0].ownerDocument||r).createTextNode(a));return c.getText(this)}, +wrapAll:function(a){if(c.isFunction(a))return this.each(function(d){c(this).wrapAll(a.call(this,d))});if(this[0]){var b=c(a,this[0].ownerDocument).eq(0).clone(true);this[0].parentNode&&b.insertBefore(this[0]);b.map(function(){for(var d=this;d.firstChild&&d.firstChild.nodeType===1;)d=d.firstChild;return d}).append(this)}return this},wrapInner:function(a){if(c.isFunction(a))return this.each(function(b){c(this).wrapInner(a.call(this,b))});return this.each(function(){var b=c(this),d=b.contents();d.length? +d.wrapAll(a):b.append(a)})},wrap:function(a){return this.each(function(){c(this).wrapAll(a)})},unwrap:function(){return this.parent().each(function(){c.nodeName(this,"body")||c(this).replaceWith(this.childNodes)}).end()},append:function(){return this.domManip(arguments,true,function(a){this.nodeType===1&&this.appendChild(a)})},prepend:function(){return this.domManip(arguments,true,function(a){this.nodeType===1&&this.insertBefore(a,this.firstChild)})},before:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments, +false,function(b){this.parentNode.insertBefore(b,this)});else if(arguments.length){var a=c(arguments[0]);a.push.apply(a,this.toArray());return this.pushStack(a,"before",arguments)}},after:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,false,function(b){this.parentNode.insertBefore(b,this.nextSibling)});else if(arguments.length){var a=this.pushStack(this,"after",arguments);a.push.apply(a,c(arguments[0]).toArray());return a}},clone:function(a){var b=this.map(function(){if(!c.support.noCloneEvent&& +!c.isXMLDoc(this)){var d=this.outerHTML,f=this.ownerDocument;if(!d){d=f.createElement("div");d.appendChild(this.cloneNode(true));d=d.innerHTML}return c.clean([d.replace(Fa,"").replace(V,"")],f)[0]}else return this.cloneNode(true)});if(a===true){qa(this,b);qa(this.find("*"),b.find("*"))}return b},html:function(a){if(a===v)return this[0]&&this[0].nodeType===1?this[0].innerHTML.replace(Fa,""):null;else if(typeof a==="string"&&!/<script/i.test(a)&&(c.support.leadingWhitespace||!V.test(a))&&!F[(Ha.exec(a)|| +["",""])[1].toLowerCase()]){a=a.replace(Ga,Ia);try{for(var b=0,d=this.length;b<d;b++)if(this[b].nodeType===1){c.cleanData(this[b].getElementsByTagName("*"));this[b].innerHTML=a}}catch(f){this.empty().append(a)}}else c.isFunction(a)?this.each(function(e){var i=c(this),j=i.html();i.empty().append(function(){return a.call(this,e,j)})}):this.empty().append(a);return this},replaceWith:function(a){if(this[0]&&this[0].parentNode){if(c.isFunction(a))return this.each(function(b){var d=c(this),f=d.html();d.replaceWith(a.call(this, +b,f))});else a=c(a).detach();return this.each(function(){var b=this.nextSibling,d=this.parentNode;c(this).remove();b?c(b).before(a):c(d).append(a)})}else return this.pushStack(c(c.isFunction(a)?a():a),"replaceWith",a)},detach:function(a){return this.remove(a,true)},domManip:function(a,b,d){function f(s){return c.nodeName(s,"table")?s.getElementsByTagName("tbody")[0]||s.appendChild(s.ownerDocument.createElement("tbody")):s}var e,i,j=a[0],n=[];if(!c.support.checkClone&&arguments.length===3&&typeof j=== +"string"&&sa.test(j))return this.each(function(){c(this).domManip(a,b,d,true)});if(c.isFunction(j))return this.each(function(s){var x=c(this);a[0]=j.call(this,s,b?x.html():v);x.domManip(a,b,d)});if(this[0]){e=a[0]&&a[0].parentNode&&a[0].parentNode.nodeType===11?{fragment:a[0].parentNode}:ra(a,this,n);if(i=e.fragment.firstChild){b=b&&c.nodeName(i,"tr");for(var o=0,m=this.length;o<m;o++)d.call(b?f(this[o],i):this[o],e.cacheable||this.length>1||o>0?e.fragment.cloneNode(true):e.fragment)}n&&c.each(n, +Ma)}return this}});c.fragments={};c.each({appendTo:"append",prependTo:"prepend",insertBefore:"before",insertAfter:"after",replaceAll:"replaceWith"},function(a,b){c.fn[a]=function(d){var f=[];d=c(d);for(var e=0,i=d.length;e<i;e++){var j=(e>0?this.clone(true):this).get();c.fn[b].apply(c(d[e]),j);f=f.concat(j)}return this.pushStack(f,a,d.selector)}});c.each({remove:function(a,b){if(!a||c.filter(a,[this]).length){if(!b&&this.nodeType===1){c.cleanData(this.getElementsByTagName("*"));c.cleanData([this])}this.parentNode&& +this.parentNode.removeChild(this)}},empty:function(){for(this.nodeType===1&&c.cleanData(this.getElementsByTagName("*"));this.firstChild;)this.removeChild(this.firstChild)}},function(a,b){c.fn[a]=function(){return this.each(b,arguments)}});c.extend({clean:function(a,b,d,f){b=b||r;if(typeof b.createElement==="undefined")b=b.ownerDocument||b[0]&&b[0].ownerDocument||r;var e=[];c.each(a,function(i,j){if(typeof j==="number")j+="";if(j){if(typeof j==="string"&&!gb.test(j))j=b.createTextNode(j);else if(typeof j=== +"string"){j=j.replace(Ga,Ia);var n=(Ha.exec(j)||["",""])[1].toLowerCase(),o=F[n]||F._default,m=o[0];i=b.createElement("div");for(i.innerHTML=o[1]+j+o[2];m--;)i=i.lastChild;if(!c.support.tbody){m=fb.test(j);n=n==="table"&&!m?i.firstChild&&i.firstChild.childNodes:o[1]==="<table>"&&!m?i.childNodes:[];for(o=n.length-1;o>=0;--o)c.nodeName(n[o],"tbody")&&!n[o].childNodes.length&&n[o].parentNode.removeChild(n[o])}!c.support.leadingWhitespace&&V.test(j)&&i.insertBefore(b.createTextNode(V.exec(j)[0]),i.firstChild); +j=c.makeArray(i.childNodes)}if(j.nodeType)e.push(j);else e=c.merge(e,j)}});if(d)for(a=0;e[a];a++)if(f&&c.nodeName(e[a],"script")&&(!e[a].type||e[a].type.toLowerCase()==="text/javascript"))f.push(e[a].parentNode?e[a].parentNode.removeChild(e[a]):e[a]);else{e[a].nodeType===1&&e.splice.apply(e,[a+1,0].concat(c.makeArray(e[a].getElementsByTagName("script"))));d.appendChild(e[a])}return e},cleanData:function(a){for(var b=0,d;(d=a[b])!=null;b++){c.event.remove(d);c.removeData(d)}}});var hb=/z-?index|font-?weight|opacity|zoom|line-?height/i, +Ja=/alpha\([^)]*\)/,Ka=/opacity=([^)]*)/,ga=/float/i,ha=/-([a-z])/ig,ib=/([A-Z])/g,jb=/^-?\d+(?:px)?$/i,kb=/^-?\d/,lb={position:"absolute",visibility:"hidden",display:"block"},mb=["Left","Right"],nb=["Top","Bottom"],ob=r.defaultView&&r.defaultView.getComputedStyle,La=c.support.cssFloat?"cssFloat":"styleFloat",ia=function(a,b){return b.toUpperCase()};c.fn.css=function(a,b){return X(this,a,b,true,function(d,f,e){if(e===v)return c.curCSS(d,f);if(typeof e==="number"&&!hb.test(f))e+="px";c.style(d,f,e)})}; +c.extend({style:function(a,b,d){if(!a||a.nodeType===3||a.nodeType===8)return v;if((b==="width"||b==="height")&&parseFloat(d)<0)d=v;var f=a.style||a,e=d!==v;if(!c.support.opacity&&b==="opacity"){if(e){f.zoom=1;b=parseInt(d,10)+""==="NaN"?"":"alpha(opacity="+d*100+")";a=f.filter||c.curCSS(a,"filter")||"";f.filter=Ja.test(a)?a.replace(Ja,b):b}return f.filter&&f.filter.indexOf("opacity=")>=0?parseFloat(Ka.exec(f.filter)[1])/100+"":""}if(ga.test(b))b=La;b=b.replace(ha,ia);if(e)f[b]=d;return f[b]},css:function(a, +b,d,f){if(b==="width"||b==="height"){var e,i=b==="width"?mb:nb;function j(){e=b==="width"?a.offsetWidth:a.offsetHeight;f!=="border"&&c.each(i,function(){f||(e-=parseFloat(c.curCSS(a,"padding"+this,true))||0);if(f==="margin")e+=parseFloat(c.curCSS(a,"margin"+this,true))||0;else e-=parseFloat(c.curCSS(a,"border"+this+"Width",true))||0})}a.offsetWidth!==0?j():c.swap(a,lb,j);return Math.max(0,Math.round(e))}return c.curCSS(a,b,d)},curCSS:function(a,b,d){var f,e=a.style;if(!c.support.opacity&&b==="opacity"&& +a.currentStyle){f=Ka.test(a.currentStyle.filter||"")?parseFloat(RegExp.$1)/100+"":"";return f===""?"1":f}if(ga.test(b))b=La;if(!d&&e&&e[b])f=e[b];else if(ob){if(ga.test(b))b="float";b=b.replace(ib,"-$1").toLowerCase();e=a.ownerDocument.defaultView;if(!e)return null;if(a=e.getComputedStyle(a,null))f=a.getPropertyValue(b);if(b==="opacity"&&f==="")f="1"}else if(a.currentStyle){d=b.replace(ha,ia);f=a.currentStyle[b]||a.currentStyle[d];if(!jb.test(f)&&kb.test(f)){b=e.left;var i=a.runtimeStyle.left;a.runtimeStyle.left= +a.currentStyle.left;e.left=d==="fontSize"?"1em":f||0;f=e.pixelLeft+"px";e.left=b;a.runtimeStyle.left=i}}return f},swap:function(a,b,d){var f={};for(var e in b){f[e]=a.style[e];a.style[e]=b[e]}d.call(a);for(e in b)a.style[e]=f[e]}});if(c.expr&&c.expr.filters){c.expr.filters.hidden=function(a){var b=a.offsetWidth,d=a.offsetHeight,f=a.nodeName.toLowerCase()==="tr";return b===0&&d===0&&!f?true:b>0&&d>0&&!f?false:c.curCSS(a,"display")==="none"};c.expr.filters.visible=function(a){return!c.expr.filters.hidden(a)}}var pb= +J(),qb=/<script(.|\s)*?\/script>/gi,rb=/select|textarea/i,sb=/color|date|datetime|email|hidden|month|number|password|range|search|tel|text|time|url|week/i,N=/=\?(&|$)/,ja=/\?/,tb=/(\?|&)_=.*?(&|$)/,ub=/^(\w+:)?\/\/([^\/?#]+)/,vb=/%20/g;c.fn.extend({_load:c.fn.load,load:function(a,b,d){if(typeof a!=="string")return this._load(a);else if(!this.length)return this;var f=a.indexOf(" ");if(f>=0){var e=a.slice(f,a.length);a=a.slice(0,f)}f="GET";if(b)if(c.isFunction(b)){d=b;b=null}else if(typeof b==="object"){b= +c.param(b,c.ajaxSettings.traditional);f="POST"}var i=this;c.ajax({url:a,type:f,dataType:"html",data:b,complete:function(j,n){if(n==="success"||n==="notmodified")i.html(e?c("<div />").append(j.responseText.replace(qb,"")).find(e):j.responseText);d&&i.each(d,[j.responseText,n,j])}});return this},serialize:function(){return c.param(this.serializeArray())},serializeArray:function(){return this.map(function(){return this.elements?c.makeArray(this.elements):this}).filter(function(){return this.name&&!this.disabled&& +(this.checked||rb.test(this.nodeName)||sb.test(this.type))}).map(function(a,b){a=c(this).val();return a==null?null:c.isArray(a)?c.map(a,function(d){return{name:b.name,value:d}}):{name:b.name,value:a}}).get()}});c.each("ajaxStart ajaxStop ajaxComplete ajaxError ajaxSuccess ajaxSend".split(" "),function(a,b){c.fn[b]=function(d){return this.bind(b,d)}});c.extend({get:function(a,b,d,f){if(c.isFunction(b)){f=f||d;d=b;b=null}return c.ajax({type:"GET",url:a,data:b,success:d,dataType:f})},getScript:function(a, +b){return c.get(a,null,b,"script")},getJSON:function(a,b,d){return c.get(a,b,d,"json")},post:function(a,b,d,f){if(c.isFunction(b)){f=f||d;d=b;b={}}return c.ajax({type:"POST",url:a,data:b,success:d,dataType:f})},ajaxSetup:function(a){c.extend(c.ajaxSettings,a)},ajaxSettings:{url:location.href,global:true,type:"GET",contentType:"application/x-www-form-urlencoded",processData:true,async:true,xhr:z.XMLHttpRequest&&(z.location.protocol!=="file:"||!z.ActiveXObject)?function(){return new z.XMLHttpRequest}: +function(){try{return new z.ActiveXObject("Microsoft.XMLHTTP")}catch(a){}},accepts:{xml:"application/xml, text/xml",html:"text/html",script:"text/javascript, application/javascript",json:"application/json, text/javascript",text:"text/plain",_default:"*/*"}},lastModified:{},etag:{},ajax:function(a){function b(){e.success&&e.success.call(o,n,j,w);e.global&&f("ajaxSuccess",[w,e])}function d(){e.complete&&e.complete.call(o,w,j);e.global&&f("ajaxComplete",[w,e]);e.global&&!--c.active&&c.event.trigger("ajaxStop")} +function f(q,p){(e.context?c(e.context):c.event).trigger(q,p)}var e=c.extend(true,{},c.ajaxSettings,a),i,j,n,o=a&&a.context||e,m=e.type.toUpperCase();if(e.data&&e.processData&&typeof e.data!=="string")e.data=c.param(e.data,e.traditional);if(e.dataType==="jsonp"){if(m==="GET")N.test(e.url)||(e.url+=(ja.test(e.url)?"&":"?")+(e.jsonp||"callback")+"=?");else if(!e.data||!N.test(e.data))e.data=(e.data?e.data+"&":"")+(e.jsonp||"callback")+"=?";e.dataType="json"}if(e.dataType==="json"&&(e.data&&N.test(e.data)|| +N.test(e.url))){i=e.jsonpCallback||"jsonp"+pb++;if(e.data)e.data=(e.data+"").replace(N,"="+i+"$1");e.url=e.url.replace(N,"="+i+"$1");e.dataType="script";z[i]=z[i]||function(q){n=q;b();d();z[i]=v;try{delete z[i]}catch(p){}A&&A.removeChild(B)}}if(e.dataType==="script"&&e.cache===null)e.cache=false;if(e.cache===false&&m==="GET"){var s=J(),x=e.url.replace(tb,"$1_="+s+"$2");e.url=x+(x===e.url?(ja.test(e.url)?"&":"?")+"_="+s:"")}if(e.data&&m==="GET")e.url+=(ja.test(e.url)?"&":"?")+e.data;e.global&&!c.active++&& +c.event.trigger("ajaxStart");s=(s=ub.exec(e.url))&&(s[1]&&s[1]!==location.protocol||s[2]!==location.host);if(e.dataType==="script"&&m==="GET"&&s){var A=r.getElementsByTagName("head")[0]||r.documentElement,B=r.createElement("script");B.src=e.url;if(e.scriptCharset)B.charset=e.scriptCharset;if(!i){var C=false;B.onload=B.onreadystatechange=function(){if(!C&&(!this.readyState||this.readyState==="loaded"||this.readyState==="complete")){C=true;b();d();B.onload=B.onreadystatechange=null;A&&B.parentNode&& +A.removeChild(B)}}}A.insertBefore(B,A.firstChild);return v}var E=false,w=e.xhr();if(w){e.username?w.open(m,e.url,e.async,e.username,e.password):w.open(m,e.url,e.async);try{if(e.data||a&&a.contentType)w.setRequestHeader("Content-Type",e.contentType);if(e.ifModified){c.lastModified[e.url]&&w.setRequestHeader("If-Modified-Since",c.lastModified[e.url]);c.etag[e.url]&&w.setRequestHeader("If-None-Match",c.etag[e.url])}s||w.setRequestHeader("X-Requested-With","XMLHttpRequest");w.setRequestHeader("Accept", +e.dataType&&e.accepts[e.dataType]?e.accepts[e.dataType]+", */*":e.accepts._default)}catch(fa){}if(e.beforeSend&&e.beforeSend.call(o,w,e)===false){e.global&&!--c.active&&c.event.trigger("ajaxStop");w.abort();return false}e.global&&f("ajaxSend",[w,e]);var g=w.onreadystatechange=function(q){if(!w||w.readyState===0||q==="abort"){E||d();E=true;if(w)w.onreadystatechange=c.noop}else if(!E&&w&&(w.readyState===4||q==="timeout")){E=true;w.onreadystatechange=c.noop;j=q==="timeout"?"timeout":!c.httpSuccess(w)? +"error":e.ifModified&&c.httpNotModified(w,e.url)?"notmodified":"success";var p;if(j==="success")try{n=c.httpData(w,e.dataType,e)}catch(u){j="parsererror";p=u}if(j==="success"||j==="notmodified")i||b();else c.handleError(e,w,j,p);d();q==="timeout"&&w.abort();if(e.async)w=null}};try{var h=w.abort;w.abort=function(){w&&h.call(w);g("abort")}}catch(k){}e.async&&e.timeout>0&&setTimeout(function(){w&&!E&&g("timeout")},e.timeout);try{w.send(m==="POST"||m==="PUT"||m==="DELETE"?e.data:null)}catch(l){c.handleError(e, +w,null,l);d()}e.async||g();return w}},handleError:function(a,b,d,f){if(a.error)a.error.call(a.context||a,b,d,f);if(a.global)(a.context?c(a.context):c.event).trigger("ajaxError",[b,a,f])},active:0,httpSuccess:function(a){try{return!a.status&&location.protocol==="file:"||a.status>=200&&a.status<300||a.status===304||a.status===1223||a.status===0}catch(b){}return false},httpNotModified:function(a,b){var d=a.getResponseHeader("Last-Modified"),f=a.getResponseHeader("Etag");if(d)c.lastModified[b]=d;if(f)c.etag[b]= +f;return a.status===304||a.status===0},httpData:function(a,b,d){var f=a.getResponseHeader("content-type")||"",e=b==="xml"||!b&&f.indexOf("xml")>=0;a=e?a.responseXML:a.responseText;e&&a.documentElement.nodeName==="parsererror"&&c.error("parsererror");if(d&&d.dataFilter)a=d.dataFilter(a,b);if(typeof a==="string")if(b==="json"||!b&&f.indexOf("json")>=0)a=c.parseJSON(a);else if(b==="script"||!b&&f.indexOf("javascript")>=0)c.globalEval(a);return a},param:function(a,b){function d(j,n){if(c.isArray(n))c.each(n, +function(o,m){b?f(j,m):d(j+"["+(typeof m==="object"||c.isArray(m)?o:"")+"]",m)});else!b&&n!=null&&typeof n==="object"?c.each(n,function(o,m){d(j+"["+o+"]",m)}):f(j,n)}function f(j,n){n=c.isFunction(n)?n():n;e[e.length]=encodeURIComponent(j)+"="+encodeURIComponent(n)}var e=[];if(b===v)b=c.ajaxSettings.traditional;if(c.isArray(a)||a.jquery)c.each(a,function(){f(this.name,this.value)});else for(var i in a)d(i,a[i]);return e.join("&").replace(vb,"+")}});var ka={},wb=/toggle|show|hide/,xb=/^([+-]=)?([\d+-.]+)(.*)$/, +W,ta=[["height","marginTop","marginBottom","paddingTop","paddingBottom"],["width","marginLeft","marginRight","paddingLeft","paddingRight"],["opacity"]];c.fn.extend({show:function(a,b){if(a||a===0)return this.animate(K("show",3),a,b);else{a=0;for(b=this.length;a<b;a++){var d=c.data(this[a],"olddisplay");this[a].style.display=d||"";if(c.css(this[a],"display")==="none"){d=this[a].nodeName;var f;if(ka[d])f=ka[d];else{var e=c("<"+d+" />").appendTo("body");f=e.css("display");if(f==="none")f="block";e.remove(); +ka[d]=f}c.data(this[a],"olddisplay",f)}}a=0;for(b=this.length;a<b;a++)this[a].style.display=c.data(this[a],"olddisplay")||"";return this}},hide:function(a,b){if(a||a===0)return this.animate(K("hide",3),a,b);else{a=0;for(b=this.length;a<b;a++){var d=c.data(this[a],"olddisplay");!d&&d!=="none"&&c.data(this[a],"olddisplay",c.css(this[a],"display"))}a=0;for(b=this.length;a<b;a++)this[a].style.display="none";return this}},_toggle:c.fn.toggle,toggle:function(a,b){var d=typeof a==="boolean";if(c.isFunction(a)&& +c.isFunction(b))this._toggle.apply(this,arguments);else a==null||d?this.each(function(){var f=d?a:c(this).is(":hidden");c(this)[f?"show":"hide"]()}):this.animate(K("toggle",3),a,b);return this},fadeTo:function(a,b,d){return this.filter(":hidden").css("opacity",0).show().end().animate({opacity:b},a,d)},animate:function(a,b,d,f){var e=c.speed(b,d,f);if(c.isEmptyObject(a))return this.each(e.complete);return this[e.queue===false?"each":"queue"](function(){var i=c.extend({},e),j,n=this.nodeType===1&&c(this).is(":hidden"), +o=this;for(j in a){var m=j.replace(ha,ia);if(j!==m){a[m]=a[j];delete a[j];j=m}if(a[j]==="hide"&&n||a[j]==="show"&&!n)return i.complete.call(this);if((j==="height"||j==="width")&&this.style){i.display=c.css(this,"display");i.overflow=this.style.overflow}if(c.isArray(a[j])){(i.specialEasing=i.specialEasing||{})[j]=a[j][1];a[j]=a[j][0]}}if(i.overflow!=null)this.style.overflow="hidden";i.curAnim=c.extend({},a);c.each(a,function(s,x){var A=new c.fx(o,i,s);if(wb.test(x))A[x==="toggle"?n?"show":"hide":x](a); +else{var B=xb.exec(x),C=A.cur(true)||0;if(B){x=parseFloat(B[2]);var E=B[3]||"px";if(E!=="px"){o.style[s]=(x||1)+E;C=(x||1)/A.cur(true)*C;o.style[s]=C+E}if(B[1])x=(B[1]==="-="?-1:1)*x+C;A.custom(C,x,E)}else A.custom(C,x,"")}});return true})},stop:function(a,b){var d=c.timers;a&&this.queue([]);this.each(function(){for(var f=d.length-1;f>=0;f--)if(d[f].elem===this){b&&d[f](true);d.splice(f,1)}});b||this.dequeue();return this}});c.each({slideDown:K("show",1),slideUp:K("hide",1),slideToggle:K("toggle", +1),fadeIn:{opacity:"show"},fadeOut:{opacity:"hide"}},function(a,b){c.fn[a]=function(d,f){return this.animate(b,d,f)}});c.extend({speed:function(a,b,d){var f=a&&typeof a==="object"?a:{complete:d||!d&&b||c.isFunction(a)&&a,duration:a,easing:d&&b||b&&!c.isFunction(b)&&b};f.duration=c.fx.off?0:typeof f.duration==="number"?f.duration:c.fx.speeds[f.duration]||c.fx.speeds._default;f.old=f.complete;f.complete=function(){f.queue!==false&&c(this).dequeue();c.isFunction(f.old)&&f.old.call(this)};return f},easing:{linear:function(a, +b,d,f){return d+f*a},swing:function(a,b,d,f){return(-Math.cos(a*Math.PI)/2+0.5)*f+d}},timers:[],fx:function(a,b,d){this.options=b;this.elem=a;this.prop=d;if(!b.orig)b.orig={}}});c.fx.prototype={update:function(){this.options.step&&this.options.step.call(this.elem,this.now,this);(c.fx.step[this.prop]||c.fx.step._default)(this);if((this.prop==="height"||this.prop==="width")&&this.elem.style)this.elem.style.display="block"},cur:function(a){if(this.elem[this.prop]!=null&&(!this.elem.style||this.elem.style[this.prop]== +null))return this.elem[this.prop];return(a=parseFloat(c.css(this.elem,this.prop,a)))&&a>-10000?a:parseFloat(c.curCSS(this.elem,this.prop))||0},custom:function(a,b,d){function f(i){return e.step(i)}this.startTime=J();this.start=a;this.end=b;this.unit=d||this.unit||"px";this.now=this.start;this.pos=this.state=0;var e=this;f.elem=this.elem;if(f()&&c.timers.push(f)&&!W)W=setInterval(c.fx.tick,13)},show:function(){this.options.orig[this.prop]=c.style(this.elem,this.prop);this.options.show=true;this.custom(this.prop=== +"width"||this.prop==="height"?1:0,this.cur());c(this.elem).show()},hide:function(){this.options.orig[this.prop]=c.style(this.elem,this.prop);this.options.hide=true;this.custom(this.cur(),0)},step:function(a){var b=J(),d=true;if(a||b>=this.options.duration+this.startTime){this.now=this.end;this.pos=this.state=1;this.update();this.options.curAnim[this.prop]=true;for(var f in this.options.curAnim)if(this.options.curAnim[f]!==true)d=false;if(d){if(this.options.display!=null){this.elem.style.overflow= +this.options.overflow;a=c.data(this.elem,"olddisplay");this.elem.style.display=a?a:this.options.display;if(c.css(this.elem,"display")==="none")this.elem.style.display="block"}this.options.hide&&c(this.elem).hide();if(this.options.hide||this.options.show)for(var e in this.options.curAnim)c.style(this.elem,e,this.options.orig[e]);this.options.complete.call(this.elem)}return false}else{e=b-this.startTime;this.state=e/this.options.duration;a=this.options.easing||(c.easing.swing?"swing":"linear");this.pos= +c.easing[this.options.specialEasing&&this.options.specialEasing[this.prop]||a](this.state,e,0,1,this.options.duration);this.now=this.start+(this.end-this.start)*this.pos;this.update()}return true}};c.extend(c.fx,{tick:function(){for(var a=c.timers,b=0;b<a.length;b++)a[b]()||a.splice(b--,1);a.length||c.fx.stop()},stop:function(){clearInterval(W);W=null},speeds:{slow:600,fast:200,_default:400},step:{opacity:function(a){c.style(a.elem,"opacity",a.now)},_default:function(a){if(a.elem.style&&a.elem.style[a.prop]!= +null)a.elem.style[a.prop]=(a.prop==="width"||a.prop==="height"?Math.max(0,a.now):a.now)+a.unit;else a.elem[a.prop]=a.now}}});if(c.expr&&c.expr.filters)c.expr.filters.animated=function(a){return c.grep(c.timers,function(b){return a===b.elem}).length};c.fn.offset="getBoundingClientRect"in r.documentElement?function(a){var b=this[0];if(a)return this.each(function(e){c.offset.setOffset(this,a,e)});if(!b||!b.ownerDocument)return null;if(b===b.ownerDocument.body)return c.offset.bodyOffset(b);var d=b.getBoundingClientRect(), +f=b.ownerDocument;b=f.body;f=f.documentElement;return{top:d.top+(self.pageYOffset||c.support.boxModel&&f.scrollTop||b.scrollTop)-(f.clientTop||b.clientTop||0),left:d.left+(self.pageXOffset||c.support.boxModel&&f.scrollLeft||b.scrollLeft)-(f.clientLeft||b.clientLeft||0)}}:function(a){var b=this[0];if(a)return this.each(function(s){c.offset.setOffset(this,a,s)});if(!b||!b.ownerDocument)return null;if(b===b.ownerDocument.body)return c.offset.bodyOffset(b);c.offset.initialize();var d=b.offsetParent,f= +b,e=b.ownerDocument,i,j=e.documentElement,n=e.body;f=(e=e.defaultView)?e.getComputedStyle(b,null):b.currentStyle;for(var o=b.offsetTop,m=b.offsetLeft;(b=b.parentNode)&&b!==n&&b!==j;){if(c.offset.supportsFixedPosition&&f.position==="fixed")break;i=e?e.getComputedStyle(b,null):b.currentStyle;o-=b.scrollTop;m-=b.scrollLeft;if(b===d){o+=b.offsetTop;m+=b.offsetLeft;if(c.offset.doesNotAddBorder&&!(c.offset.doesAddBorderForTableAndCells&&/^t(able|d|h)$/i.test(b.nodeName))){o+=parseFloat(i.borderTopWidth)|| +0;m+=parseFloat(i.borderLeftWidth)||0}f=d;d=b.offsetParent}if(c.offset.subtractsBorderForOverflowNotVisible&&i.overflow!=="visible"){o+=parseFloat(i.borderTopWidth)||0;m+=parseFloat(i.borderLeftWidth)||0}f=i}if(f.position==="relative"||f.position==="static"){o+=n.offsetTop;m+=n.offsetLeft}if(c.offset.supportsFixedPosition&&f.position==="fixed"){o+=Math.max(j.scrollTop,n.scrollTop);m+=Math.max(j.scrollLeft,n.scrollLeft)}return{top:o,left:m}};c.offset={initialize:function(){var a=r.body,b=r.createElement("div"), +d,f,e,i=parseFloat(c.curCSS(a,"marginTop",true))||0;c.extend(b.style,{position:"absolute",top:0,left:0,margin:0,border:0,width:"1px",height:"1px",visibility:"hidden"});b.innerHTML="<div style='position:absolute;top:0;left:0;margin:0;border:5px solid #000;padding:0;width:1px;height:1px;'><div></div></div><table style='position:absolute;top:0;left:0;margin:0;border:5px solid #000;padding:0;width:1px;height:1px;' cellpadding='0' cellspacing='0'><tr><td></td></tr></table>";a.insertBefore(b,a.firstChild); +d=b.firstChild;f=d.firstChild;e=d.nextSibling.firstChild.firstChild;this.doesNotAddBorder=f.offsetTop!==5;this.doesAddBorderForTableAndCells=e.offsetTop===5;f.style.position="fixed";f.style.top="20px";this.supportsFixedPosition=f.offsetTop===20||f.offsetTop===15;f.style.position=f.style.top="";d.style.overflow="hidden";d.style.position="relative";this.subtractsBorderForOverflowNotVisible=f.offsetTop===-5;this.doesNotIncludeMarginInBodyOffset=a.offsetTop!==i;a.removeChild(b);c.offset.initialize=c.noop}, +bodyOffset:function(a){var b=a.offsetTop,d=a.offsetLeft;c.offset.initialize();if(c.offset.doesNotIncludeMarginInBodyOffset){b+=parseFloat(c.curCSS(a,"marginTop",true))||0;d+=parseFloat(c.curCSS(a,"marginLeft",true))||0}return{top:b,left:d}},setOffset:function(a,b,d){if(/static/.test(c.curCSS(a,"position")))a.style.position="relative";var f=c(a),e=f.offset(),i=parseInt(c.curCSS(a,"top",true),10)||0,j=parseInt(c.curCSS(a,"left",true),10)||0;if(c.isFunction(b))b=b.call(a,d,e);d={top:b.top-e.top+i,left:b.left- +e.left+j};"using"in b?b.using.call(a,d):f.css(d)}};c.fn.extend({position:function(){if(!this[0])return null;var a=this[0],b=this.offsetParent(),d=this.offset(),f=/^body|html$/i.test(b[0].nodeName)?{top:0,left:0}:b.offset();d.top-=parseFloat(c.curCSS(a,"marginTop",true))||0;d.left-=parseFloat(c.curCSS(a,"marginLeft",true))||0;f.top+=parseFloat(c.curCSS(b[0],"borderTopWidth",true))||0;f.left+=parseFloat(c.curCSS(b[0],"borderLeftWidth",true))||0;return{top:d.top-f.top,left:d.left-f.left}},offsetParent:function(){return this.map(function(){for(var a= +this.offsetParent||r.body;a&&!/^body|html$/i.test(a.nodeName)&&c.css(a,"position")==="static";)a=a.offsetParent;return a})}});c.each(["Left","Top"],function(a,b){var d="scroll"+b;c.fn[d]=function(f){var e=this[0],i;if(!e)return null;if(f!==v)return this.each(function(){if(i=ua(this))i.scrollTo(!a?f:c(i).scrollLeft(),a?f:c(i).scrollTop());else this[d]=f});else return(i=ua(e))?"pageXOffset"in i?i[a?"pageYOffset":"pageXOffset"]:c.support.boxModel&&i.document.documentElement[d]||i.document.body[d]:e[d]}}); +c.each(["Height","Width"],function(a,b){var d=b.toLowerCase();c.fn["inner"+b]=function(){return this[0]?c.css(this[0],d,false,"padding"):null};c.fn["outer"+b]=function(f){return this[0]?c.css(this[0],d,false,f?"margin":"border"):null};c.fn[d]=function(f){var e=this[0];if(!e)return f==null?null:this;if(c.isFunction(f))return this.each(function(i){var j=c(this);j[d](f.call(this,i,j[d]()))});return"scrollTo"in e&&e.document?e.document.compatMode==="CSS1Compat"&&e.document.documentElement["client"+b]|| +e.document.body["client"+b]:e.nodeType===9?Math.max(e.documentElement["client"+b],e.body["scroll"+b],e.documentElement["scroll"+b],e.body["offset"+b],e.documentElement["offset"+b]):f===v?c.css(e,d):this.css(d,typeof f==="string"?f:f+"px")}});z.jQuery=z.$=c})(window); diff --git a/tools/qdoc3/doc/config/scripts/narrow.js b/tools/qdoc3/doc/config/scripts/narrow.js new file mode 100644 index 0000000..a5e8b97 --- /dev/null +++ b/tools/qdoc3/doc/config/scripts/narrow.js @@ -0,0 +1,133 @@ +/* This function generates menus and search box in narrow/slim fit mode */ +var narrowInit = function() { + /* 1: Create search form */ + var narrowSearch = $('<div id="narrowsearch"></div>'); + var searchform = $("#qtdocsearch"); + narrowSearch.append(searchform); + $("#qtdocheader .content .qtref").after(narrowSearch); + + /* 2: Create dropdowns */ + var narrowmenu = $('<ul id="narrowmenu" class="sf-menu"></ul>'); + + /* Lookup */ + var lookuptext = $("#lookup h2").attr("title"); + $("#lookup ul").removeAttr("id"); + $("#lookup ul li").removeAttr("class"); + $("#lookup ul li").removeAttr("style"); + var lookupul = $("#lookup ul"); + var lookuplist = $('<li></li>'); + var lookuplink = $('<a href="#"></a>'); + lookuplink.append(lookuptext); + lookuplist.append(lookuplink); + lookuplist.append(lookupul); + narrowmenu.append(lookuplist); + + /* Topics */ + var topicstext = $("#topics h2").attr("title"); + $("#topics ul").removeAttr("id"); + $("#topics ul li").removeAttr("class"); + $("#topics ul li").removeAttr("style"); + var topicsul = $("#topics ul"); + var topicslist = $('<li></li>'); + var topicslink = $('<a href="#"></a>'); + topicslink.append(topicstext); + topicslist.append(topicslink); + topicslist.append(topicsul); + narrowmenu.append(topicslist); + + /* Examples */ + var examplestext = $("#examples h2").attr("title"); + $("#examples ul").removeAttr("id"); + $("#examples ul li").removeAttr("class"); + $("#examples ul li").removeAttr("style"); + var examplesul = $("#examples ul"); + var exampleslist = $('<li></li>'); + var exampleslink = $('<a href="#"></a>'); + exampleslink.append(examplestext); + exampleslist.append(exampleslink); + exampleslist.append(examplesul); + narrowmenu.append(exampleslist); + + $("#shortCut").after(narrowmenu); + $('ul#narrowmenu').superfish({ + delay: 100, + autoArrows: false, + disableHI: true + }); +} + +/* Executes on doc ready */ +$(document).ready(function(){ + /* check if body has the narrow class */ + if ($('body').hasClass('narrow')) { + /* run narrowInit */ + narrowInit(); + } + + /* messure window width and add class if it is smaller than 600 px */ + if($(window).width()<600) { + $('body').addClass('narrow'); + /* if the search box contains */ + if ($("#narrowsearch").length == 0) { + /* run narrowInit */ + narrowInit(); + } + } + else { /* if the window is wider than 600 px, narrow is removed */ + $('body').removeClass('narrow'); + if ($("#narrowsearch").length == 0) { + } + } +}); +/* binding resize event to this funciton */ +$(window).bind('resize', function () { + /* if the window is wider than 600 px, narrow class is added */ + if($(window).width()<600) { + $('body').addClass('narrow'); + if ($("#narrowsearch").length == 0) { + narrowInit(); + } + } + else { + /* else we remove the narrow class */ + $('body').removeClass('narrow'); + } +}); + + $('#narrowsearch').keyup(function () { + /* extract the search box content */ + var searchString = $('#narrowsearch').val(); + /* if the string is less than three characters */ + if ((searchString == null) || (searchString.length < 3)) { + /* remove classes and elements*/ + $('#narrowsearch').removeClass('loading'); + $('.searching').remove(); + /* run CheckEmptyAndLoadList */ + CheckEmptyAndLoadList(); + + $('.report').remove(); + return; + } + /* if timer checks out */ + if (this.timer) clearTimeout(this.timer); + this.timer = setTimeout(function () { + /* add loading image by adding loading class */ + $('#narrowsearch').addClass('loading'); + $('.searching').remove(); + + /* run the actual search */ + $.ajax({ + contentType: "application/x-www-form-urlencoded", + url: 'http://' + location.host + '/nokiasearch/GetDataServlet', + data: 'searchString='+searchString, + dataType:'xml', + type: 'post', + success: function (response, textStatus) { + /* on success remove loading img */ + $('.searching').remove(); + $('#narrowsearch').removeClass('loading'); + processNokiaData(response); + } + }); + }, 500); /* timer set to 500 ms */ + });
\ No newline at end of file diff --git a/tools/qdoc3/doc/config/scripts/superfish.js b/tools/qdoc3/doc/config/scripts/superfish.js new file mode 100644 index 0000000..c6a9c7d --- /dev/null +++ b/tools/qdoc3/doc/config/scripts/superfish.js @@ -0,0 +1,121 @@ + +/* + * Superfish v1.4.8 - jQuery menu widget + * Copyright (c) 2008 Joel Birch + * + * Dual licensed under the MIT and GPL licenses: + * http://www.opensource.org/licenses/mit-license.php + * http://www.gnu.org/licenses/gpl.html + * + * CHANGELOG: http://users.tpg.com.au/j_birch/plugins/superfish/changelog.txt + */ + +;(function($){ + $.fn.superfish = function(op){ + + var sf = $.fn.superfish, + c = sf.c, + $arrow = $(['<span class="',c.arrowClass,'"> »</span>'].join('')), + over = function(){ + var $$ = $(this), menu = getMenu($$); + clearTimeout(menu.sfTimer); + $$.showSuperfishUl().siblings().hideSuperfishUl(); + }, + out = function(){ + var $$ = $(this), menu = getMenu($$), o = sf.op; + clearTimeout(menu.sfTimer); + menu.sfTimer=setTimeout(function(){ + o.retainPath=($.inArray($$[0],o.$path)>-1); + $$.hideSuperfishUl(); + if (o.$path.length && $$.parents(['li.',o.hoverClass].join('')).length<1){over.call(o.$path);} + },o.delay); + }, + getMenu = function($menu){ + var menu = $menu.parents(['ul.',c.menuClass,':first'].join(''))[0]; + sf.op = sf.o[menu.serial]; + return menu; + }, + addArrow = function($a){ $a.addClass(c.anchorClass).append($arrow.clone()); }; + + return this.each(function() { + var s = this.serial = sf.o.length; + var o = $.extend({},sf.defaults,op); + o.$path = $('li.'+o.pathClass,this).slice(0,o.pathLevels).each(function(){ + $(this).addClass([o.hoverClass,c.bcClass].join(' ')) + .filter('li:has(ul)').removeClass(o.pathClass); + }); + sf.o[s] = sf.op = o; + + $('li:has(ul)',this)[($.fn.hoverIntent && !o.disableHI) ? 'hoverIntent' : 'hover'](over,out).each(function() { + if (o.autoArrows) addArrow( $('>a:first-child',this) ); + }) + .not('.'+c.bcClass) + .hideSuperfishUl(); + + var $a = $('a',this); + $a.each(function(i){ + var $li = $a.eq(i).parents('li'); + $a.eq(i).focus(function(){over.call($li);}).blur(function(){out.call($li);}); + }); + o.onInit.call(this); + + }).each(function() { + var menuClasses = [c.menuClass]; + if (sf.op.dropShadows && !($.browser.msie && $.browser.version < 7)) menuClasses.push(c.shadowClass); + $(this).addClass(menuClasses.join(' ')); + }); + }; + + var sf = $.fn.superfish; + sf.o = []; + sf.op = {}; + sf.IE7fix = function(){ + var o = sf.op; + if ($.browser.msie && $.browser.version > 6 && o.dropShadows && o.animation.opacity!=undefined) + this.toggleClass(sf.c.shadowClass+'-off'); + }; + sf.c = { + bcClass : 'sf-breadcrumb', + menuClass : 'sf-js-enabled', + anchorClass : 'sf-with-ul', + arrowClass : 'sf-sub-indicator', + shadowClass : 'sf-shadow' + }; + sf.defaults = { + hoverClass : 'sfHover', + pathClass : 'overideThisToUse', + pathLevels : 1, + delay : 800, + animation : {opacity:'show'}, + speed : 'normal', + autoArrows : true, + dropShadows : true, + disableHI : false, // true disables hoverIntent detection + onInit : function(){}, // callback functions + onBeforeShow: function(){}, + onShow : function(){}, + onHide : function(){} + }; + $.fn.extend({ + hideSuperfishUl : function(){ + var o = sf.op, + not = (o.retainPath===true) ? o.$path : ''; + o.retainPath = false; + var $ul = $(['li.',o.hoverClass].join(''),this).add(this).not(not).removeClass(o.hoverClass) + .find('>ul').hide().css('visibility','hidden'); + o.onHide.call($ul); + return this; + }, + showSuperfishUl : function(){ + var o = sf.op, + sh = sf.c.shadowClass+'-off', + $ul = this.addClass(o.hoverClass) + .find('>ul:hidden').css('visibility','visible'); + sf.IE7fix.call($ul); + o.onBeforeShow.call($ul); + $ul.animate(o.animation,o.speed,function(){ sf.IE7fix.call($ul); o.onShow.call($ul); }); + return this; + } + }); + +})(jQuery); diff --git a/tools/qdoc3/doc/config/style/narrow.css b/tools/qdoc3/doc/config/style/narrow.css new file mode 100644 index 0000000..39b4740 --- /dev/null +++ b/tools/qdoc3/doc/config/style/narrow.css @@ -0,0 +1,271 @@ + /* start narrow mode */ + + body.narrow + { + background-image: none; + } + + .narrow a { + color: #00732f; + } + + .narrow .header, .narrow .header .content, .narrow .footer, .narrow .wrapper { + margin: 0 7px; + min-width: 300px; + } + + .narrow .footer { + margin: 0px; + } + + .creator .header, .creator .header .content, .creator .footer, .creator .wrapper { + margin: 0px; + min-width: 300px; + } + .narrow .header + { + width: 100%; + margin: 0; + height: auto; + background: #fff url(../images/header_bg.png) repeat-x 0 100%; + padding: 10px 0 5px 0; + overflow: visible; + } + + .narrow .header .content + { + } + + .narrow .header #nav-logo + { + display: none; + } + + .narrow .header .qtref + { + width: auto; + height: auto; + color: #00732f; + position: static; + float: left; + margin-left: 25px; + font: bold 18px/1 Arial; + } + + .narrow .header .qtref a + { + color: #00732F; + } + + .narrow .header .qtref span + { + background-image: none; + text-indent: 0; + width: 260px; + } + + .narrow .header #nav-topright + { + display: none; + } + + .narrow .header #shortCut + { + clear: both; + font-weight: normal; + position: static; + float: left; + margin: 15px 0 0 25px; + overflow: hidden; + padding: 0; + height: auto; + } + + .narrow .header #shortCut ul + { + float: none; + margin: 0; + width: auto; + font-size: 11px; + } + + .narrow .header #shortCut ul li + { + background-image: none; + } + + .narrow .header #shortCut ul .shortCut-topleft-active, + .narrow .header #shortCut ul .shortCut-topleft-inactive + { + background-image: none; + height: auto; + padding: 0; + width: auto; + } + .narrow .header #shortCut ul li a + { + color: #00732F; + } + + .narrow .wrapper .hd + { + background: url(../images/bg_ul_blank.png) no-repeat 0 0; + } + + .narrow .wrapper .bd + { + background: url(../images/bg_l_blank.png) repeat-y 0 0; + } + + .narrow .wrapper .ft + { + background: url(../images/bg_ll_blank.png) no-repeat 0 0; + } + + .narrow .sidebar + { + display: none; + } + + .narrow .wrap + { + margin: 0 5px 0 5px; + } + + .creator .wrap + { + margin: 0px; + background:#FFFFFF; + } + .narrow .wrap .toolbar + { + border-bottom: none; + } + + .narrow .wrap .content + { + padding-top: 15px; + } + .creator .wrap .content + { + padding-top: 10px; + } + .creator .wrap .content .guide + { + padding-top: 15px; + } + .narrow .wrap .feedback + { + display: none; + } + + .narrow .wrap .breadcrumb ul li { + font-weight: normal; + } + + .narrow .wrap .breadcrumb ul li a { + color: #00732f; + } + + .narrow .wrap .breadcrumb ul li.last a { + color: #363534; + } + + #narrowsearch { + display: none; + } + + .narrow #narrowsearch { + display: block; + float: right; + margin-right: 25px; + _position: relative; + } + + .narrow #narrowsearch fieldset { + _position: absolute; + _margin-top: -1px; + } + + .narrow #narrowsearch { + background: url("http://doc.qt.nokia.com/prototype/html/images/sprites-combined.png") no-repeat scroll -6px -348px transparent; + height: 21px; + padding: 2px 0 0 5px; + width: 167px; + } + + .narrow #narrowsearch input { + border: none; + font: 13px/1.2 Verdana; + height: 19px; + outline: none; + padding: 0; + width: 158px; + *border: 1px solid #fff; + *height: 17px; + _height: 18px; + } + .narrow .indexbox .indexIcon { + display: none; + } + + .narrow .indexboxcont .section { + width: 64%; + padding-left: 0; + } + + .narrow .indexboxcont .sectionlist { + width: 32.5%; + } + + #narrowmenu { + display: none; + float: right; + margin: 15px 40px 0 0; + font-size: 11px; + position: relative; + } + + .narrow #narrowmenu { + display: block; + } + + #narrowmenu a { + line-height: 1.1; + background: url(../images/arrow_down.png) no-repeat 100% 50%; + white-space: nowrap; + padding: 0 16px 0 5px; + } + + #narrowmenu li { + margin-left: 20px; + } + + #narrowmenu li li { + margin: 0 0 5px 0; + } + + #narrowmenu li li a { + padding: 0; + background-image: none; + } + + #narrowmenu li, + #narrowmenu li ul { + background-color: #fff; + margin-top:-1px; + } + + #narrowmenu li ul { + width: auto; + padding: 5px; + } + + .sf-menu li:hover ul, .sf-menu li.sfHover ul { + top: 1.2em; + } + + /* end narrow mode */ + .creator #narrowsearch, .creator #narrowmenu{ + display:none; + } diff --git a/tools/qdoc3/doc/config/style/offline.css b/tools/qdoc3/doc/config/style/offline.css new file mode 100644 index 0000000..3689ee8 --- /dev/null +++ b/tools/qdoc3/doc/config/style/offline.css @@ -0,0 +1,673 @@ +@media screen +{ + +/* basic elements */ + html + { + color: #000000; + background: #FFFFFF; + } + table + { + border-collapse: collapse; + border-spacing: 0; + } + fieldset, img + { + border: 0; + max-width:100%; + } + address, caption, cite, code, dfn, em, strong, th, var, optgroup + { + font-style: inherit; + font-weight: inherit; + } + del, ins + { + text-decoration: none; + } + li + { + list-style: none; + } + ol li + { + list-style: decimal; + } + caption, th + { + text-align: left; + } + h1, h2, h3, h4, h5, h6 + { + font-size: 100%; + } + q:before, q:after + { + content: ''; + } + abbr, acronym + { + border: 0; + font-variant: normal; + } + sup, sub + { + vertical-align: baseline; + } + tt, .qmlreadonly span, .qmldefault span + { + word-spacing:0.5em; + } + legend + { + color: #000000; + } + strong + { + font-weight: bold; + } + em + { + font-style: italic; + } + + body + { + margin-left: 0.5em; + margin-right: 0.5em; + } + a + { + color: #00732F; + text-decoration: none; + } + hr + { + background-color: #E6E6E6; + border: 1px solid #E6E6E6; + height: 1px; + width: 100%; + text-align: left; + margin: 1.5em 0 1.5em 0; + } + + pre + { + border: 1px solid #DDDDDD; + -moz-border-radius: 0.7em 0.7em 0.7em 0.7em; + -webkit-border-radius: 0.7em 0.7em 0.7em 0.7em; + border-radius: 0.7em 0.7em 0.7em 0.7em; + margin: 0 1.5em 1em 1em; + padding: 1em 1em 1em 1em; + overflow-x: auto; + } + table, pre + { + -moz-border-radius: 0.7em 0.7em 0.7em 0.7em; + -webkit-border-radius: 0.7em 0.7em 0.7em 0.7em; + border-radius: 0.7em 0.7em 0.7em 0.7em; + background-color: #F6F6F6; + border: 1px solid #E6E6E6; + border-collapse: separate; + margin-bottom: 2.5em; + } + pre { + font-size: 90%; + display: block; + overflow:hidden; + } + thead + { + margin-top: 0.5em; + font-weight: bold + } + th + { + padding: 0.5em 1.5em 0.5em 1.5em; + background-color: #E1E1E1; + border-left: 1px solid #E6E6E6; + } + td + { + padding: 0.25em 1.5em 0.25em 2em; + } + + td.rightAlign + { + padding: 0.25em 0.5em 0.25em 1em; + } + table tr.odd + { + border-left: 1px solid #E6E6E6; + background-color: #F6F6F6; + color: #66666E; + } + table tr.even + { + border-left: 1px solid #E6E6E6; + background-color: #ffffff; + color: #66666E; + } + + div.float-left + { + float: left; margin-right: 2em + } + div.float-right + { + float: right; margin-left: 2em + } + + span.comment + { + color: #008B00; + font-style: italic + } + span.string, span.char + { + color: #000084; + } + span.number + { + color: #a46200; + } + span.operator + { + color: #202020; + } + span.keyword + { + color: #840000; + } + span.name + { + color: black + } + span.type + { + font-weight: bold + } + span.type a:visited + { + color: #0F5300; + } + span.preprocessor + { + color: #404040 + } +/* end basic elements */ + +/* font style elements */ + .heading + { + font-weight: bold; + font-size: 125%; + } + .subtitle + { + font-size: 110% + } + .small-subtitle + { + font-size: 100% + } + .red + { + color:red; + } +/* end font style elements */ + +/* global settings*/ + .header, .footer + { + display: block; + clear: both; + overflow: hidden; + } +/* end global settings*/ + +/* header elements */ + .header .qtref + { + color: #00732F; + font-weight: bold; + font-size: 130%; + } + + .header .content + { + margin-bottom: 0.5em + } + + .naviNextPrevious + { + display: none + } + .header .breadcrumb + { + font-size: 90%; + padding: 0.5em 0 0.5em 1em; + margin: 0; + background-color: #fafafa; + height: 1.35em; + border-bottom: 1px solid #d1d1d1; + } + + .header .breadcrumb ul + { + margin: 0; + padding: 0; + } + + .header .content + { + word-wrap: break-word; + } + + .header .breadcrumb ul li + { + float: left; + background: url(../images/breadcrumb.png) no-repeat 0 3px; + padding-left: 1.5em; + margin-left: 1.5em; + } + + .header .breadcrumb ul li.last + { + font-weight: normal; + } + + .header .breadcrumb ul li a + { + color: #00732F; + } + + .header .breadcrumb ul li.first + { + background-image: none; + padding-left: 0; + margin-left: 0; + } + + .header .content ol li { + background: none; + margin-bottom: 1.0em; + margin-left: 1.2em; + padding-left: 0 + } + + .header .content li + { + background: url(../images/bullet_sq.png) no-repeat 0 5px; + margin-bottom: 1em; + padding-left: 1.2em; + } + +/* end header elements */ + +/* content elements */ + .content h1 + { + font-weight: bold; + font-size: 150% + } + + .content h2 + { + font-weight: bold; + font-size: 135%; + width: 100%; + } + .content h3 + { + font-weight: bold; + font-size: 120%; + width: 100%; + } + .content table p + { + margin: 0 + } + .content ul + { + padding-left: 2.5em; + } + .content li + { + padding-top: 0.25em; + padding-bottom: 0.25em; + } + .content ul img { + vertical-align: middle; + } + + .content a:visited + { + color: #4c0033; + text-decoration: none; + } + + .content a:visited:hover + { + color: #4c0033; + text-decoration: underline; + } + + a:hover + { + color: #4c0033; + text-decoration: underline; + } + descr p a + { + text-decoration: underline; + } + + .descr p a:visited + { + text-decoration: underline; + } + + .alphaChar{ + width:95%; + background-color:#F6F6F6; + border:1px solid #E6E6E6; + -moz-border-radius: 7px 7px 7px 7px; + border-radius: 7px 7px 7px 7px; + -webkit-border-radius: 7px 7px 7px 7px; + font-size:12pt; + padding-left:10px; + margin-top:10px; + margin-bottom:10px; + } + .flowList{ + /*vertical-align:top;*/ + /*margin:20px auto;*/ + + column-count:3; + -webkit-column-count:3; + -moz-column-count:3; +/* + column-width:100%; + -webkit-column-width:200px; + -col-column-width:200px; +*/ + column-gap:41px; + -webkit-column-gap:41px; + -moz-column-gap:41px; + + column-rule: 1px dashed #ccc; + -webkit-column-rule: 1px dashed #ccc; + -moz-column-rule: 1px dashed #ccc; + } + + .flowList dl{ + } + .flowList dd{ + /*display:inline-block;*/ + margin-left:10px; + min-width:250px; + line-height: 1.5; + min-width:100%; + min-height:15px; + } + + .flowList dd a{ + } + + .content .flowList p{ + padding:0px; + } + + .content .alignedsummary + { + margin: 15px; + } + + + .qmltype + { + text-align: center; + font-size: 120%; + } + .qmlreadonly + { + padding-left: 5px; + float: right; + color: #254117; + } + + .qmldefault + { + padding-left: 5px; + float: right; + color: red; + } + + .qmldoc + { + } + + .generic .alphaChar{ + margin-top:5px; + } + + .generic .odd .alphaChar{ + background-color: #F6F6F6; + } + + .generic .even .alphaChar{ + background-color: #FFFFFF; + } + + .memItemRight{ + padding: 0.25em 1.5em 0.25em 0; + } + .highlightedCode + { + margin: 1.0em; + } + .annotated td { + padding: 0.25em 0.5em 0.25em 0.5em; + } + + .header .content .toc ul + { + padding-left: 0px; + } + + .content .toc h3 { + border-bottom: 0px; + margin-top: 0px; + } + + .content .toc h3 a:hover { + color: #00732F; + text-decoration: none; + } + + .content .toc .level2 + { + margin-left: 1.5em; + } + + .content .toc .level3 + { + margin-left: 3.0em; + } + + .content ul li + { + background: url(../images/bullet_sq.png) no-repeat 0 0.7em; + padding-left: 1em + } + + .content .toc li + { + background: url(../images/bullet_dn.png) no-repeat 0 5px; + padding-left: 1em + } + + .relpage + { + -moz-border-radius: 7px 7px 7px 7px; + -webkit-border-radius: 7px 7px 7px 7px; + border-radius: 7px 7px 7px 7px; + border: 1px solid #DDDDDD; + padding: 25px 25px; + clear: both; + } + .relpage ul + { + float: none; + padding: 1.5em; + } + + h3.fn, span.fn + { + -moz-border-radius:7px 7px 7px 7px; + -webkit-border-radius:7px 7px 7px 7px; + border-radius:7px 7px 7px 7px; + background-color: #F6F6F6; + border-width: 1px; + border-style: solid; + border-color: #E6E6E6; + font-weight: bold; + word-spacing:3px; + padding:3px 5px; + } + + .functionIndex { + font-size:12pt; + word-spacing:10px; + margin-bottom:10px; + background-color: #F6F6F6; + border-width: 1px; + border-style: solid; + border-color: #E6E6E6; + -moz-border-radius: 7px 7px 7px 7px; + -webkit-border-radius: 7px 7px 7px 7px; + border-radius: 7px 7px 7px 7px; + width:100%; + } + + .centerAlign + { + text-align:center; + } + + .rightAlign + { + text-align:right; + } + + .leftAlign + { + text-align:left; + } + + .topAlign{ + vertical-align:top + } + + .functionIndex a{ + display:inline-block; + } + +/* end content elements */ +/* footer elements */ + + .footer + { + color: #393735; + font-size: 0.75em; + text-align: center; + padding-top: 1.5em; + padding-bottom: 1em; + background-color: #E6E7E8; + margin: 0; + } + .footer p + { + margin: 0.25em + } + .small + { + font-size: 0.5em; + } +/* end footer elements */ + + .item { + float: left; + position: relative; + width: 100%; + overflow: hidden; + } + + + .item .primary { + margin-right: 220px; + position: relative; + } + + .item hr { + margin-left: -220px; + } + + .item .secondary { + float: right; + width: 200px; + position: relative; + } + + .item .cols { + clear: both; + display: block; + } + + .item .cols .col { + float: left; + margin-left: 1.5%; + } + + .item .cols .col.first { + margin-left: 0; + } + + .item .cols.two .col { + width: 45%; + } + + .item .box { + margin: 0 0 10px 0; + } + + .item .box h3 { + margin: 0 0 10px 0; + } + + .cols.unclear { + clear:none; + } +} + +/* end of screen media */ + +/* start of print media */ + +@media print +{ + input, textarea, .header, .footer, .toolbar, .feedback, .wrapper .hd, .wrapper .bd .sidebar, .wrapper .ft, #feedbackBox, #blurpage, .toc, .breadcrumb, .toolbar, .floatingResult + { + display: none; + background: none; + } + .content + { + background: none; + display: block; + width: 100%; margin: 0; float: none; + } +} +/* end of print media */ diff --git a/tools/qdoc3/doc/config/style/style.css b/tools/qdoc3/doc/config/style/style.css new file mode 100644 index 0000000..48ecedc --- /dev/null +++ b/tools/qdoc3/doc/config/style/style.css @@ -0,0 +1,1733 @@ +@media screen +{ + +/* basic elements */ + html + { + color: #000000; + background: #FFFFFF; + } + body, div, dl, dt, dd, ul, ol, li, h1, h2, h3, h4, h5, h6, pre, code, form, fieldset, legend, input, button, textarea, p, blockquote, th, td + { + margin: 0; + padding: 0; + } + table + { + border-collapse: collapse; + border-spacing: 0; + } + fieldset, img + { + border: 0; + max-width:100%; + } + address, caption, cite, code, dfn, em, strong, th, var, optgroup + { + font-style: inherit; + font-weight: inherit; + } + del, ins + { + text-decoration: none; + } + li + { + list-style: none; + } + ol li + { + list-style: decimal; + } + caption, th + { + text-align: left; + } + h1, h2, h3, h4, h5, h6 + { + font-size: 100%; + } + q:before, q:after + { + content: ''; + } + abbr, acronym + { + border: 0; + font-variant: normal; + } + sup, sub + { + vertical-align: baseline; + } + tt, .qmlreadonly span, .qmldefault span + { + word-spacing:5px; + } + legend + { + color: #000000; + } + input, button, textarea, select, optgroup, option + { + font-family: inherit; + font-size: inherit; + font-style: inherit; + font-weight: inherit; + } + input, button, textarea, select + { + font-size: 100%; + } + strong + { + font-weight: bold; + } + em + { + font-style: italic; + } + + /* adding Qt theme */ + html + { + /* background-color: #e5e5e5;*/ + } + body + { + background: #e6e7e8 url(../images/page_bg.png) repeat-x 0 0; + font: normal 13px/1.2 Verdana; + color: #363534; + } + a + { + color: #00732F; + text-decoration: none; + } + hr + { + background-color: #E6E6E6; + border: 1px solid #E6E6E6; + height: 1px; + width: 100%; + text-align: left; + margin: 15px 0px 15px 0px; + } + + pre + { + border: 1px solid #DDDDDD; + -moz-border-radius: 7px 7px 7px 7px; + -webkit-border-radius: 7px 7px 7px 7px; + border-radius: 7px 7px 7px 7px; + margin: 0 20px 10px 10px; + padding: 20px 15px 20px 20px; + overflow-x: auto; + } + table, pre + { + -moz-border-radius: 7px 7px 7px 7px; + -webkit-border-radius: 7px 7px 7px 7px; + border-radius: 7px 7px 7px 7px; + background-color: #F6F6F6; + border: 1px solid #E6E6E6; + border-collapse: separate; + font-size: 11px; + margin-bottom: 25px; + } + pre.highlightedCode { + display: block; + overflow:hidden; + } + thead + { + margin-top: 5px; + font:600 12px/1.2 Arial; + } + th + { + padding: 5px 15px 5px 15px; + background-color: #E1E1E1; + border-left: 1px solid #E6E6E6; + } + td + { + padding: 3px 15px 3px 20px; + } + tr.odd td:hover, tr.even td:hover {} + + td.rightAlign + { + padding: 3px 5px 3px 10px; + } + table tr.odd + { + border-left: 1px solid #E6E6E6; + background-color: #F6F6F6; + color: #66666E; + } + table tr.even + { + border-left: 1px solid #E6E6E6; + background-color: #ffffff; + color: #66666E; + } + table tr.odd td:hover, table tr.even td:hover + { + /* background-color: #E6E6E6;*/ /* disabled until further notice */ + } + + div.float-left + { + float: left; margin-right: 2em + } + div.float-right + { + float: right; margin-left: 2em + } + + span.comment + { + color: #008B00; + font-style: italic + } + span.string, span.char + { + color: #000084; + } + span.number + { + color: #a46200; + } + span.operator + { + color: #202020; + } + span.keyword + { + color: #840000; + } + span.name + { + color: black + } + span.type + { + font-weight: bold + } + span.type a:visited + { + color: #0F5300; + } + span.preprocessor + { + color: #404040 + } +/* end basic elements */ + +/* font style elements */ + .heading + { + font: normal bold 16px/1.2 Arial; + padding-bottom: 15px; + } + .subtitle + { + font-size: 13px; + } + .small-subtitle + { + font-size: 13px; + } + .red + { + color:red; + } + .figCaption{ + color:#363534; + font:italic 11px/1.2 Verdana; + padding-top:0; + } +/* end font style elements */ + +/* global settings*/ + .header, .footer, .wrapper + { + min-width: 600px; + max-width: 1500px; + margin: 0 30px; + } + .header, .footer + { + display: block; + clear: both; + overflow: hidden; + } + .header:after, .footer:after, .breadcrumb:after, .wrap .content:after, .group:after + { + content: "."; + display: block; + height: 0; + clear: both; + visibility: hidden; + } +/* end global settings*/ + +/* header elements */ + .header + { + height: 115px; + position: relative; + } + .header .icon + { + position: absolute; + top: 13px; + left: 0; + } + .header .qtref + { + position: absolute; + top: 28px; + left: 88px; + width: 302px; + height: 22px; + } + .header .qtref span + { + display: block; + width: 302px; + height: 22px; + text-indent: -999em; + background: url(../images/sprites-combined.png) no-repeat -78px -235px; + } + .content a:visited + { + color: #4c0033; + text-decoration: none; + } + .content a:visited:hover + { + color: #4c0033; + text-decoration: underline; + } + + #nav-topright + { + height: 70px; + } + + #nav-topright ul + { + list-style-type: none; + float: right; + width: 370px; + margin-top: 11px; + } + + #nav-topright li + { + display: inline-block; + margin-right: 20px; + float: left; + } + + #nav-topright li.nav-topright-last + { + margin-right: 0; + } + + #nav-topright li a + { + background: transparent url(../images/sprites-combined.png) no-repeat; + height: 18px; + display: block; + overflow: hidden; + text-indent: -9999px; + } + + #nav-topright li.nav-topright-home a + { + width: 65px; + background-position: -2px -91px; + } + + #nav-topright li.nav-topright-home a:hover + { + background-position: -2px -117px; + } + + #nav-topright li.nav-topright-dev a + { + width: 30px; + background-position: -76px -91px; + } + + #nav-topright li.nav-topright-dev a:hover + { + background-position: -76px -117px; + } + + + #nav-topright li.nav-topright-labs a + { + width: 40px; + background-position: -114px -91px; + } + + #nav-topright li.nav-topright-labs a:hover + { + background-position: -114px -117px; + } + + #nav-topright li.nav-topright-doc a + { + width: 32px; + background-position: -162px -91px; + } + + #nav-topright li.nav-topright-doc a:hover, #nav-topright li.nav-topright-doc-active a + { + background-position: -162px -117px; + } + + #nav-topright li.nav-topright-blog a + { + width: 40px; + background-position: -203px -91px; + } + + #nav-topright li.nav-topright-blog a:hover, #nav-topright li.nav-topright-blog-active a + { + background-position: -203px -117px; + } + + #nav-topright li.nav-topright-shop a + { + width: 40px; + background-position: -252px -91px; + } + + #nav-topright li.nav-topright-shop a:hover, #nav-topright li.nav-topright-shop-active a + { + background-position: -252px -117px; + } + + #nav-logo + { + background: transparent url(../images/sprites-combined.png ) no-repeat 0 -225px; + left: -3px; + position: absolute; + width: 75px; + height: 75px; + top: 13px; + } + #nav-logo a + { + width: 75px; + height: 75px; + display: block; + text-indent: -9999px; + overflow: hidden; + } + + .shortCut-topleft-inactive + { + padding-left: 3px; + padding-right: 3px; + background: transparent url( ../images/sprites-combined.png) no-repeat 0px -58px; + height: 20px; + } + .shortCut-topleft-inactive span + { + font-variant: normal; + } + .shortCut-topleft-inactive span a:hover, .shortCut-topleft-active a:hover + { + text-decoration:none; + } + #shortCut + { + padding-top: 10px; + font-weight: bolder; + color: #b0adab; + } + #shortCut ul + { + list-style-type: none; + float: left; + width: 347px; + margin-left: 100px; + } + #shortCut li + { + display: inline-block; + margin-right: 25px; + float: left; + white-space: nowrap; + } + #shortCut li a + { + color: #b0adab; + } + #shortCut li a:hover + { + color: #44a51c; + } +/* end header elements */ + +/* content and sidebar elements */ + .wrapper + { + background: url(../images/bg_r.png) repeat-y 100% 0; + } + + .wrapper .hd + { + padding-left: 16px; + height: 15px; + background: url(../images/page.png) no-repeat 0px -15px; + overflow: hidden; + } + + .wrapper .hd span + { + height: 15px; + display: block; + overflow: hidden; + background: url(../images/page.png) no-repeat 100% -30px; + } + + .wrapper .bd + { + background: url(../images/bg_l_blank.png) repeat-y 0 0; + position: relative; + } + + .wrapper .ft + { + padding-left: 16px; + height: 15px; + background: url(../images/page.png) no-repeat 0 -75px; + overflow: hidden; + } + + .wrapper .ft span + { + height: 15px; + display: block; + background: url(../images/page.png) no-repeat 100% -60px; + overflow: hidden; + } + .navTop{ + float:right; + display:block; + padding-right:15px; + } +/* end content and sidebar elements */ + +/* sidebar elements */ + .sidebar + { + float: left; + margin-left: 5px; + width: 200px; + font-size: 11px; + } + + .sidebar .searchlabel + { + padding: 0 0 2px 17px; + font: normal bold 11px/1.2 Verdana; + } + + .sidebar .search + { + padding: 0 15px 0 16px; + } + + .sidebar .search form + { + background: url(../images/sprites-combined.png) no-repeat -6px -348px; + height:21px; + padding:2px 0 0 5px; + width:167px; + } + + .sidebar .search form input#pageType + { + width: 158px; + height: 19px; + padding: 0; + border: 0px; + outline: none; + font: 13px/1.2 Verdana; + } + + .sidebar .box + { + padding: 17px 15px 5px 16px; + } + + .sidebar .box .first + { + background-image: none; + } + + .sidebar .box h2 + { + font: bold 16px/1.2 Arial; + padding: 0; + } + .sidebar .box h2 span + { + overflow: hidden; + display: inline-block; + } + .sidebar .box#lookup h2 + { + background-image: none; + } + .sidebar #lookup.box h2 span + { + } + .sidebar .box#topics h2 + { + background-image: none; + } + .sidebar #topics.box h2 span + { + } + .sidebar .box#examples h2 + { + background-image: none; + } + .sidebar #examples.box h2 span + { + } + + .sidebar .box .list + { + display: block; + max-height:200px; + min-height:120px; + overflow-y:auto; + overflow-x:none; + } + .list li a:hover + { + text-decoration: underline; + } + .sidebar .box ul + { + padding-bottom:5px; + padding-left:10px; + padding-top:5px; + } + .sidebar .box ul li + { + padding-left: 12px; + background: url(../images/bullet_gt.png) no-repeat 0 5px; + margin-bottom: 5px; + } + .sidebar .bottombar + { + background: url(../images/box_bg.png) repeat-x 0 bottom; + } + .sidebar .box ul li.noMatch + { + background: none; + color:#FF2A00; + font-style:italic; + } + .sidebar .box ul li.hit + { + background: none; + color:#AAD2F0; + font-style:italic; + } + .sidebar .search form input.loading + { + background:url("../images/spinner.gif") no-repeat scroll right center transparent; + } + + .sidebar .search form { + _height: 23px; + _width: 169px; + } + + #resultdialog { + display: none; + position: absolute; + *left: 30px; + _left: 0; + *top: 35px; + _top: 30px; + _zoom: 1; + background-color: #fff; + border: 1px solid #666; + z-index: 4; + margin-top: 5px; + _margin: 0 0 0 -20px; + padding: 10px; + width: 30%; + _width: 196px; + height: 250px; + overflow: auto; + -webkit-border-radius: .5em; + -moz-border-radius: .5em; + border-radius: .5em; + -webkit-box-shadow: 0 4px 6px 0 rgba(0,0,0,.2); + -moz-box-shadow: 0 4px 6px 0 rgba(0,0,0,.2); + box-shadow: 0 4px 6px 0 rgba(0,0,0,.2); + font-size: 11px; + } + + #resultdialog a + { + color: #00732f; + } + + #resultdialog.active { + display: block; + } + + .narrow #resultdialog { + width: 60%; + _width: 360px; + } + + .narrow #resultdialog.active { + right: 10px; + *left: auto; + _left: auto; + _right: -20px; + } + + + #resultdialog #resultclose { + float: right; + } + + #resultdialog p, + #resultdialog ul { + clear: both; + margin: 3px 0; + } + + p#searchcount span { + display: none; + } + + p#searchcount.all span#resultcount, + p#searchcount.api span#apicount, + p#searchcount.article span#articlecount, + p#searchcount.example span#examplecount { + display: inline; + } + + #resultlist li { + display: none; + } + + #resultlist.api li.api, + #resultlist.article li.article, + #resultlist.example li.example, + #resultlist.all li { + display: block; + } + + #resultlinks.api a#showapiresults, + #resultlinks.api a#showapiresults:hover, + #resultlinks.article a#showarticleresults, + #resultlinks.article a#showarticleresults:hover, + #resultlinks.example a#showexampleresults, + #resultlinks.example a#showexampleresults:hover, + #resultlinks.all a#showallresults, + #resultlinks.all a#showallresults:hover { + color: #B0ADAB; + } + .floatingResult{ + z-index:1; + position:relative; + padding-top:0px; + background-color:white; + border:solid 1px black; + height:250px; + width:600px; + overflow-x:hidden; + overflow-y:auto; + } + + .floatingResult:hover{ + display:block; + } + .floatingResult:hover{ + } +/* end sidebar elements */ + +/* content elements */ + .wrap + { + margin: 0 5px 0 5px; + overflow: visible; + } + + .wrap .toolbar + { + background-color: #fafafa; + border-bottom: 1px solid #d1d1d1; + height: 20px; + position: relative; + } + .wrap .toolbar .toolblock + { + position: absolute; + } + .wrap .toolbar .breadcrumb + { + font-size: 11px; + line-height: 1.2; + padding: 0 0 10px 21px; + height: 10px; + } + .wrap .toolbar .toolbuttons + { + padding: 0 0 10px 21px; + right: 5px; + vertical-align: middle; + overflow: hidden; + } + .wrap .toolbar .toolbuttons .active + { + color: #00732F; + } + .wrap .toolbar .toolbuttons ul + { + float: right; + } + .wrap .toolbar .toolbuttons li + { + float: left; + text-indent: -10px; + margin-top: -5px; + margin-right: 15px; + font-weight: bold; + color: #B0ADAB; + font: bold 10px/1.2 Verdana; + } + + .toolbuttons #print + { + border-left: 1px solid #c5c4c4; + margin-top: 0; + padding-left: 7px; + text-indent: 0; + } + .toolbuttons #print a + { + width: 16px; + height: 16px; + } + + .toolbuttons #print a span + { + width: 16px; + height: 16px; + text-indent: -999em; + display: block; + overflow: hidden; + background: url(../images/sprites-combined.png) no-repeat -137px -311px; + } + + .toolbuttons #smallA + { + font-size: 10pt; + } + .toolbuttons #medA + { + font-size: 12pt; + } + .toolbuttons #bigA + { + font-size: 14pt; + margin-right: 7px; + } + + #smallA:hover, #medA:hover, #bigA:hover + { + color: #00732F; + } + + .wrap .content + { + padding: 30px; + word-wrap:break-word; + } + + .wrap .breadcrumb ul + { + } + .wrap .breadcrumb ul li + { + float: left; + background: url(../images/breadcrumb.png) no-repeat 0 3px; + padding-left: 15px; + margin-left: 15px; + font-weight: bold; + } + .wrap .breadcrumb ul li.last + { + font-weight: normal; + } + .wrap .breadcrumb ul li a + { + color: #363534; + } + .wrap .breadcrumb ul li.first + { + background-image: none; + padding-left: 0; + margin-left: 0; + } + + .wrap .content ol li { + background:none; + font:normal 10pt/1.2 Verdana; + + margin-bottom:10px; + margin-left:12px; + /*list-style-type:disc;*/ + } + + .wrap .content ol li + { + background:none; + margin-bottom: 10px; + padding-left:0px; + margin-left:52px; + } + + .wrap .content li + { + background: url(../images/bullet_sq.png) no-repeat 0 5px; + font: normal 400 10pt/1.2 Verdana; + margin-bottom: 10px; + padding-left:12px; + } + + .content li:hover {} + + .wrap .content h1 + { + font: bold 18px/1.2 Arial; + } + .wrap .content h2 + { + font:600 16px/1.2 Arial; + margin-top:15px; + width:100%; + } + .wrap .content h3 + { + font: bold 14px/1.2 Arial; + font:600 16px/1.2 Arial; + margin-top:15px; + width:100%; + } + .wrap .content p + { + line-height: 20px; + padding: 5px; + } + .wrap .content table p + { + line-height: 20px; + } + .wrap .content ul + { + padding-left: 25px; + padding-top: 10px; + } + .wrap .content ul img { + vertical-align:middle; + } + a:hover + { + color: #4c0033; + text-decoration: underline; + } + descr p a + { + text-decoration: underline; + } + + .descr p a:visited + { + text-decoration: underline; + } + .feedback + { + float: none; + position: absolute; + right: 15px; + bottom: 10px; + font: normal 8px/1 Verdana; + color: #B0ADAB; + } + .feedback:hover + { + float: right; + font: normal 8px/1 Verdana; + color: #00732F; + text-decoration: underline; + } + .alphaChar{ + width:95%; + background-color:#F6F6F6; + border:1px solid #E6E6E6; + -moz-border-radius: 7px 7px 7px 7px; + border-radius: 7px 7px 7px 7px; + -webkit-border-radius: 7px 7px 7px 7px; + font-size:12pt; + padding-left:10px; + margin-top:10px; + margin-bottom:10px; + } + .flowList{ + /*vertical-align:top;*/ + /*margin:20px auto;*/ + + column-count:3; + -webkit-column-count:3; + -moz-column-count:3; +/* + column-width:100%; + -webkit-column-width:200px; + -col-column-width:200px; +*/ + column-gap:41px; + -webkit-column-gap:41px; + -moz-column-gap:41px; + + column-rule: 1px dashed #ccc; + -webkit-column-rule: 1px dashed #ccc; + -moz-column-rule: 1px dashed #ccc; + } + + .flowList dl{ + } + .flowList dd{ + /*display:inline-block;*/ + margin-left:10px; + min-width:250px; + line-height: 1.5; + min-width:100%; + min-height:15px; + } + + .flowList dd a{ + } + + .wrap .content .flowList p{ + padding:0px; + } + + .content .alignedsummary + { + margin: 15px; + } + + + .qmltype + { + text-align: center; + font-size: 160%; + } + .qmlreadonly + { + padding-left: 5px; + float: right; + color: #254117; + } + + .qmldefault + { + padding-left: 5px; + float: right; + color: red; + } + + .qmldoc + { + } + + *.qmlitem p + { + } + #feedbackBox + { + display: none; + -moz-border-radius: 7px 7px 7px 7px; + -webkit-border-radius: 7px 7px 7px 7px; + border-radius: 7px 7px 7px 7px; + border: 1px solid #DDDDDD; + position: fixed; + top: 100px; + left: 33%; + height: 230px; + width: 400px; + padding: 5px; + background-color: #e6e7e8; + z-index: 4; + } + #feedcloseX + { + display: inline; + padding: 5px 5px 0 0; + margin-bottom: 3px; + color: #363534; + font-weight:bold; + float: right; + text-decoration: none; + } + + #feedbox + { + display: inline; + width: 370px; + height: 120px; + margin: 0px 25px 10px 15px; + } + #noteHead + { + font-weight:bold; + padding:10px 10px 10px 20px; + } + #feedsubmit + { + display: inline; + float: right; + margin: 4px 32px 0 0; + } + + .note + { + font-size:7pt; + padding-bottom:3px; + padding-left:20px; + } + + #blurpage + { + display: none; + position: fixed; + float: none; + top: 0px; + left: 0px; + right: 0px; + bottom: 0px; + background: transparent url(../images/feedbackground.png) 0 0; + z-index: 3; + } + .toc + { + float: right; + -moz-border-radius: 7px 7px 7px 7px; + -webkit-border-radius: 7px 7px 7px 7px; + border-radius: 7px 7px 7px 7px; + background-color: #F6F6F6; + border: 1px solid #DDDDDD; + margin: 0 20px 10px 10px; + padding: 20px 15px 20px 20px; + height: auto; + width: 200px; + } + + .toc h3, .generic a + { + font: bold 12px/1.2 Arial; + } + + .generic{ + } + .generic td{ + /* padding:5px;*/ + } + .generic .alphaChar{ + margin-top:5px; + } + + .generic .odd .alphaChar{ + background-color: #F6F6F6; + } + + .generic .even .alphaChar{ + background-color: #FFFFFF; + } + + .alignedsummary{} + .propsummary{} + .memItemLeft{} + .memItemRight{ + padding:3px 15px 3px 0; + } + .bottomAlign{} + .highlightedCode + { + margin:10px; + } + .LegaleseLeft{} + .valuelist{} + .annotated td{ + padding: 3px 5px 3px 5px; + } + .obsolete{} + .compat{} + .flags{} + .qmlsummary{} + .qmlitem{} + .qmlproto{} + .qmlname{} + .qmlreadonly{} + .qmldefault{} + .qmldoc{} + .qt-style{} + .redFont{} + code{} + + .wrap .content .toc ul + { + padding-left: 0px; + } + + .wrap .content .toc h3{ + border-bottom:0px; + margin-top:0px; + } + + .wrap .content .toc h3 a:hover{ + color:#00732F; + text-decoration:none; + } + + + .wrap .content .toc .level2 + { + margin-left: 15px; + } + + .wrap .content .toc .level3 + { + margin-left: 30px; + } + + .content .toc li + { + font: normal 10px/1.2 Verdana; + background: url(../images/bullet_dn.png) no-repeat 0 5px; + } + .relpage + { + -moz-border-radius: 7px 7px 7px 7px; + -webkit-border-radius: 7px 7px 7px 7px; + border-radius: 7px 7px 7px 7px; + border: 1px solid #DDDDDD; + padding: 25px 25px; + clear: both; + } + .relpage ul + { + float: none; + padding: 15px; + } + .content .relpage li + { + font: normal 11px/1.2 Verdana; + } + h3.fn, span.fn + { + -moz-border-radius:7px 7px 7px 7px; + -webkit-border-radius:7px 7px 7px 7px; + border-radius:7px 7px 7px 7px; + background-color: #F6F6F6; + border-width: 1px; + border-style: solid; + border-color: #E6E6E6; + font-weight: bold; + word-spacing:3px; + padding:3px 5px; + } + + .functionIndex { + font-size:12pt; + word-spacing:10px; + margin-bottom:10px; + background-color: #F6F6F6; + border-width: 1px; + border-style: solid; + border-color: #E6E6E6; + -moz-border-radius: 7px 7px 7px 7px; + -webkit-border-radius: 7px 7px 7px 7px; + border-radius: 7px 7px 7px 7px; + width:100%; + } + + .centerAlign + { + text-align:center; + } + + .rightAlign + { + text-align:right; + } + + .leftAlign + { + text-align:left; + } + + .topAlign{ + vertical-align:top + } + + .functionIndex a{ + display:inline-block; + } +/* end content elements */ + +/* footer elements */ + .footer + { + min-height: 100px; + color: #797775; + font: normal 9px/1 Verdana; + text-align: center; + padding-top: 40px; + background-color: #E6E7E8; + margin: 0; + } + .small + { + font: normal 9px/1 Verdana; + } +/* end footer elements */ + + /* start index box */ + .indexbox + { + width: 100%; + display:inline-block; + } + + .indexboxcont + { + display: block; + + } + + .indexboxbar + { + background: transparent url(../images/horBar.png ) repeat-x left bottom; + margin-bottom: 25px; + + + } + + .indexboxcont .section + { + display: inline-block; + width: 49%; + *width:42%; + _width:42%; + padding:0 2% 0 1%; + vertical-align:top; + } + + .indexboxcont .indexIcon + { + width: 11%; + *width:18%; + _width:18%; + overflow:hidden; + } + + .indexboxcont .section { + float: left; + } + + .indexboxcont .section p + { + padding-top: 20px; + padding-bottom: 20px; + } + .indexboxcont .sectionlist + { + display: inline-block; + vertical-align:top; + width: 32.5%; + padding: 0; + } + .indexboxcont .sectionlist ul + { + margin-bottom: 20px; + } + + .indexboxcont .sectionlist ul li + { + line-height: 12px; + } + + .content .indexboxcont li + { + font: normal bold 13px/1 Verdana; + } + + .indexbox a:hover, .indexbox a:visited:hover + { + color: #4c0033; + text-decoration: underline; + } + + .indexbox a:visited + { + color: #00732f; + text-decoration: none; + } + + .indexbox .indexIcon { + width: 11%; + } + + .indexbox .indexIcon span + { + display: block; + } + + .indexbox.guide .indexIcon span + { + width: 96px; + height: 137px; + background: url(../images/sprites-combined.png) no-repeat -5px -376px; + padding: 0; + } + + .indexbox.tools .indexIcon span + { + width: 115px; + height: 137px; + background: url(../images/sprites-combined.png) no-repeat -111px -376px; + padding: 0; + } + .indexboxcont:after + { + content: "."; + display: block; + height: 0; + clear: both; + visibility: hidden; + } + + + +/* start of creator spec*/ + .creator + { + margin-left:0px; + margin-right:0px; + padding-left:0px; + padding-right:0px; + } + .creator .wrap .content ol li { + list-style-type:decimal; + } + .creator .header .icon, + .creator .feedback, + .creator .t_button, + .creator .feedback, + .creator #feedbackBox, + .creator #feedback, + .creator #blurpage, + /* .creator .indexbox .indexIcon span,*/ + .creator .wrapper .hd, + /* .creator .indexbox .indexIcon,*/ + .creator .header #nav-logo, + .creator #offlinemenu, + .creator #offlinesearch, + .creator .header #nav-topright, + .creator .header #shortCut , + .creator .wrapper .hd, + .creator .wrapper .ft, + .creator .sidebar, + .creator .wrap .feedback + { + display:none; + } + + body.creator + { + background: none; + + font: normal 13px/1.2 Verdana; + color: #363534; + background-color: #FAFAFA; + } + + .wrap .content ol li { + + } + + + .creator .header, .creator .footer, .creator .wrapper + { + max-width: 1500px; + margin: 0px; + } + + .creator .wrapper + { + position:relative; + top:5px; + } + .creator .wrapper .bd + { + background:#FFFFFF; + } + + + .creator .header, .footer + { + display: block; + clear: both; + overflow: hidden; + } + .creator .wrap .content p + + { + line-height: 20px; + padding: 5px; + } + + .creator .header .qtref span + { + background:none; + } + + .creator .footer + { + border-top:1px solid #E5E5E5; + height: 50px; + margin:0px; + padding:10px; + } + + .creator .footer p + { + text-align:justify; + max-width:900px; + } + + .creator .wrap + { + padding:0 5px 0 5px; + margin: 0px; + } + .creator .wrap .toolbar + { + border-bottom:1px solid #E5E5E5; + /*width:100%;*/ + margin-left:-5px; + margin-right:-5px; + } + .creator .wrap .breadcrumb ul li a + { + /* color: #363534;*/ + color: #00732F; + } + + .creator .wrap .content + { + padding: 0px; + word-wrap:break-word; + } + + .creator .wrap .content ol li { + background:none; + font: inherit; + padding-left: 0px; + } + + .creator .wrap .content .descr ol li { + margin-left: 45px; + } + + .creator .content .alignedsummary + { + margin: 5px; + width:100%; + } + .creator .generic{ + max-width:75%; + } + .creator .generic td{ + /*padding:0;*/ + } + .creator .indexboxbar + { + border-bottom:1px solid #E5E5E5; + margin-bottom: 25px; + background: none; + } + + .creator .header + { + width: 100%; + margin: 0; + height: auto; + background-color: #ffffff; + padding: 10px 0 5px 0; + overflow: visible; + border-bottom: solid #E5E5E5 1px; + z-index:1; + /* position:fixed;*/ + } + + .creator .header .content + { + } + .creator .header .qtref + { + color: #00732F; + position: static; + float: left; + margin-left: 5px; + font: bold 18px/1 Arial; + } + + .creator .header .qtref:visited + { + color: #00732F; + } + .creator .header .qtref:hover + { + color: #00732F; + text-decoration:none; + } + .creator .header .qtref span + { + background-image: none; + text-indent: 0; + text-decoration:none; + } + + .creator .wrap .toolbar + { + display:block; + padding-top:0px; + } + + .creator .wrap .breadcrumb ul li { + font-weight: normal; + } + + .creator .wrap .breadcrumb ul li a { + /*color: #44a51c;*/ + } + + .creator .wrap .breadcrumb ul li.last a { + /*color: #363534;*/ + } + + .creator #narrowmenu ul + { + border-bottom:solid 1px #E5E5E5; + border-left:solid 1px #E5E5E5; + border-right:solid 1px #E5E5E5; + } + + .creator #narrowmenu li ul { + margin-top:-15px; + } + + .creator .toc { + margin:10px 20px 10px 10px; + } + + .creator #narrowsearch, .creator #narrowmenu{ + display:none; + } +/* end of creator spec*/ + + .item { + float: left; + position: relative; + width: 100%; + overflow: hidden; + } + + .item .primary { + margin-right: 220px; + position: relative; + } + + .item hr { + margin-left: -220px; + } + + .item .secondary { + float: right; + width: 200px; + position: relative; + } + + .item .cols { + clear: both; + display: block; + } + + .item .cols .col { + float: left; + margin-left: 1.5%; + } + + .item .cols .col.first { + margin-left: 0; + } + + .item .cols.two .col { + width: 45%; + } + + .item .box { + margin: 0 0 10px 0; + } + + .item .box h3 { + margin: 0 0 10px 0; + } + + .cols.unclear { + clear:none; + } +} + +/* end of screen media */ + +/* start of print media */ + +@media print +{ + input, textarea, .header, .footer, .toolbar, .feedback, .wrapper .hd, .wrapper .bd .sidebar, .wrapper .ft, #feedbackBox, #blurpage, .toc, .breadcrumb, .toolbar, .floatingResult + { + display: none; + background: none; + } + .content + { + background: none; + display: block; + width: 100%; margin: 0; float: none; + } +} +/* end of print media */ diff --git a/tools/qdoc3/doc/config/style/style_ie6.css b/tools/qdoc3/doc/config/style/style_ie6.css new file mode 100644 index 0000000..16fb850 --- /dev/null +++ b/tools/qdoc3/doc/config/style/style_ie6.css @@ -0,0 +1,54 @@ +.indexbox, .indexboxcont, .group { + zoom: 1; + height: 1%; +} + +.sidebar { + margin-left: 3px; + width: 199px; + overflow: hidden; +} + +.sidebar .search form { + position: relative; +} + +.sidebar .search form fieldset { + position: absolute; + margin-top: -1px; +} + +.sidebar .search form input#searchstring { + border: 1px solid #fff; + height: 18px; +} + +.wrap { + zoom: 1; +} + +.content, +.toolbar { + zoom: 1; + margin-left: -3px; + position: relative; +} + +.indexbox { + clear: both; +} + +.indexboxcont .section { + zoom: 1; + float: left; +} + +.indexboxcont .sectionlist { + zoom: 1; + float: left; +} + +.wrap .toolbar .toolbuttons li { + text-indent: 0; + margin-right: 8px; +}
\ No newline at end of file diff --git a/tools/qdoc3/doc/config/style/style_ie7.css b/tools/qdoc3/doc/config/style/style_ie7.css new file mode 100644 index 0000000..afbff5f --- /dev/null +++ b/tools/qdoc3/doc/config/style/style_ie7.css @@ -0,0 +1,19 @@ +.indexbox, .indexboxcont, .group { + min-height: 1px; +} + +.sidebar .search form input#searchstring { + border: 1px solid #fff; + height: 17px; +} + + +.indexboxcont .section { + zoom: 1; + float: left; +} + +.indexboxcont .sectionlist { + zoom: 1; + float: left; +} diff --git a/tools/qdoc3/doc/config/style/style_ie8.css b/tools/qdoc3/doc/config/style/style_ie8.css new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tools/qdoc3/doc/config/style/style_ie8.css diff --git a/tools/qdoc3/doc/config/style/superfish.css b/tools/qdoc3/doc/config/style/superfish.css new file mode 100644 index 0000000..2bdaef4 --- /dev/null +++ b/tools/qdoc3/doc/config/style/superfish.css @@ -0,0 +1,51 @@ +.sf-menu, .sf-menu * { + margin: 0; + padding: 0; + list-style: none; +} +.sf-menu { + line-height: 1.0; +} +.sf-menu ul { + position: absolute; + top: -999em; + width: 10em; /* left offset of submenus need to match (see below) */ +} +.sf-menu ul li { + width: 100%; +} +.sf-menu li:hover { + visibility: inherit; /* fixes IE7 'sticky bug' */ +} +.sf-menu li { + float: left; + position: relative; +} +.sf-menu a { + display: block; + position: relative; +} +.sf-menu li:hover ul, +.sf-menu li.sfHover ul { + left: 0; + top: 2.5em; /* match top ul list item height */ + z-index: 99; +} +ul.sf-menu li:hover li ul, +ul.sf-menu li.sfHover li ul { + top: -999em; +} +ul.sf-menu li li:hover ul, +ul.sf-menu li li.sfHover ul { + left: 10em; /* match ul width */ + top: 0; +} +ul.sf-menu li li:hover li ul, +ul.sf-menu li li.sfHover li ul { + top: -999em; +} +ul.sf-menu li li li:hover ul, +ul.sf-menu li li li.sfHover ul { + left: 10em; /* match ul width */ + top: 0; +} diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc index 7290c0e..712dcea 100644 --- a/tools/qdoc3/doc/qdoc-manual.qdoc +++ b/tools/qdoc3/doc/qdoc-manual.qdoc @@ -27,727 +27,874 @@ /*! \page index.html - \nextpage QDoc Manual + \nextpage Introduction to QDoc - \title QDoc Manual - Table of Contents + \title Table of Contents \list - \o \l{QDoc Manual} - \o \l{QDoc Commands} - \list - \o \l{Markup Commands} - \o \l{Text Formatting Commands} - \o \l{Document Structuring Commands} - \o \l{Verbatim Code Commands} - \o \l{Quoting External Code Commands} - \list - \o \l{Example File} - \endlist - \o \l{Linking Commands} - \o \l{Graphic Commands} - \o \l{Container Commands} - \o \l{Document Contents Commands} - \o \l{Miscellaneous Commands} - \list - \o \l{signalandslots.qdocinc} - \o \l{objectmodel.qdocinc} - \o \l{layoutmanagement.qdocinc} - \endlist - \o \l{Topical Commands} - \o \l{Contextual Commands} - \o \l{Navigation Commands} - \o \l{Status Commands} - \o \l{Thread Support Commands} - \o \l{Relating Commands} - \o \l{Grouping Commands} - \o \l{Title Commands} - \endlist - \o \l{QDoc Configuration} - \list - \o \l{General Configuration Variables} - \o \l{Creating Help Project Files} - \o \l{C++ Specific Configuration Variables} - \o \l{HTML Specific Configuration Variables} - \o \l{Supporting Derived Projects} - \o \l{QDoc Compatibility} - \o \l{qt.qdocconf} - \o \l{minimum.qdocconf} - \endlist - \o \l{QDoc Commands - Alphabetical List} + \o \l {Introduction to QDoc} + \o \l {Command Index} + \o \l {Topic Commands} + \o \l {Context Commands} + \list + \o \l {Document Navigation} + \o \l {Reporting Status} + \o \l {Thread Support} + \o \l {Relating Things} + \o \l {Grouping Things} + \o \l {Naming Things} + \endlist + \o \l{Markup Commands} + \list + \o \l {Text Markup} + \o \l {Document Structure} + \o \l {Including Code Inline} + \o \l {Including External Code} + \o \l {Creating Links} + \o \l {Including Images} + \o \l {Tables and Lists} + \o \l {Special Content} + \o \l {Miscellaneous} + \endlist + \o \l {The QDoc Configuration File} + \list + \o \l {General Configuration Variables} + \o \l {Creating Help Project Files} + \o \l {C++ Specific Configuration Variables} + \o \l {HTML Specific Configuration Variables} + \o \l {Supporting Derived Projects} + \o \l {Compatibility Issues} + \o \l {qt.qdocconf} + \o \l {minimum.qdocconf} + \endlist \endlist + */ /*! \page 01-qdoc-manual.html - \contentspage QDoc Manual - Table of Contents - \previouspage QDoc Manual - Table of Contents - \nextpage QDoc Commands + \contentspage Table of Contents + \previouspage Table of Contents + \nextpage Command Index + + \title Introduction to QDoc + + QDoc is a tool used by Qt Developers to generate documentation of + software projects by extracting the documentation from the project + source files and then formatting it as HTML pages or DITA XML + documents, etc. The documentation is embedded in the source files + in \e {qdoc comments}. A qdoc comment begins with an exclamation + mark \bold{(!)} e.g.: + + \code + / *! + \class QObject + \brief The QObject class is the base class of all Qt objects. + + \ingroup objectmodel + + \reentrant + + QObject is the heart of the Qt \l{Object Model}. The + central feature in this model is a very powerful mechanism + for seamless object communication called \l{signals and + slots}. You can connect a signal to a slot with connect() + and destroy the connection with disconnect(). To avoid + never ending notification loops you can temporarily block + signals with blockSignals(). The protected functions + connectNotify() and disconnectNotify() make it possible to + track connections. + + QObjects organize themselves in \l {Object Trees & + Ownership} {object trees}. When you create a QObject with + another object as parent, the object will automatically + add itself to the parent's children() list. The parent + takes ownership of the object; i.e., it will automatically + delete its children in its destructor. You can look for an + object by name and optionally type using findChild() or + findChildren(). + + Every object has an objectName() and its class name can be + found via the corresponding metaObject() (see + QMetaObject::className()). You can determine whether the + object's class inherits another class in the QObject + inheritance hierarchy by using the inherits() function. + + .... + * / + \endcode - \title QDoc Manual + From this snippet, QDoc generates the now famous HTML page \l + {http://doc.trolltech.com/4.7/qobject.html#details} {QObject Class Reference}. + + This manual explains how to use the QDoc commands to write useful + qdoc comments in your source files. It also explains how to create + a \l {The QDoc Configuration File} {QDoc configuration file}, + which you must pass to QDoc on the command line when you run it. - QDoc is the internal tool used by Qt Development Frameworks for generating - documentation. This document is a reference for QDoc command syntax and - configuration. + \section1 Running QDoc - \section1 Overview + The current name of the QDoc program is \c {qdoc3}. To run qdoc3 + from the command line, give it the name of a configuration file: - \list I - \o \section2 \l {QDoc Commands} + \quotation + \c {/current/dir$ ../../bin/qdoc3 ./config.qdocconf} + \endquotation - \l {QDoc Commands - Alphabetical List}{A complete alphabetical - list}. + \c{config.qdocconf} is your \l{The QDoc Configuration File} {QDoc + configuration file}. The configuration file is where tell QDoc + where to find the source files from which it will extract the QDoc + comments it will use to generate the documentation. It is also + where you tell QDoc what kind of output to generate (HTML, DITA + XML,...), and where to put the generated output. The configuration + file also contains other information for QDoc. - There are two main categories of commands for QDoc: markup - commands and meta-commands. + \section1 Command Types - The markup commands indicate the generated documentation's - appearance and logical structure. The meta-commands provide - information about the document as well as the documented - item. The meta-commands can be further categorized as topical - commands and contextual commands. + QDoc interprets three types of commands: - \list - \o \l {Markup Commands} - \list - \o \l {Text Formatting Commands}{Text Formatting} - \o \l {Document Structuring Commands}{Document Structuring} - \o \l {Verbatim Code Commands}{Verbatim Code} - \o \l {Quoting External Code Commands}{Quoting External Code} - \o \l {Linking Commands}{Linking} - \o \l {Graphic Commands}{Graphic} - \o \l {Container Commands}{Container} - \o \l {Document Contents Commands}{Document Contents} - \o \l {Miscellaneous Commands}{Miscellaneous} - \endlist - \o \l {Topical Commands} - \o \l {Contextual Commands} - \list - \o \l {Navigation Commands}{Navigation} - \o \l {Status Commands}{Status} - \o \l {Thread Support Commands}{Thread Support} - \o \l {Relating Commands}{Relating} - \o \l {Grouping Commands}{Grouping} - \o \l {Title Commands}{Title} - \endlist - \endlist + \list + \o \l {Topic Commands} + \o \l {Context Commands} + \o \l {Markup Commands} \endlist - \list II - \o \section2 \l {QDoc Configuration} - - When running QDoc to generate the documentation, you must - specify a configuration file on the command line. The - configuration file is a list of entries of entries of the form - "variable = value". - - \list - \o \l {Configuration Variables} - \o \l {Configuration File Examples} - \endlist - - Some particular configuration variables allow you to use QDoc - to support Qt-based projects; i.e to make projects, such as Qt - Solutions, contain references to the online Qt documentation. - - \list - \o \l {Supporting Derived Projects} - \endlist - - QDoc is a tool that constantly evolves to suit our needs, for - that reason there are some compatibility issues between old and - new practices. - - \list - \o \l {QDoc Compatibility} - \endlist - \endlist + Topic commands identify the elememt you are documenting, e.g. a C++ + class, function, or type, an example, or an extra page of text + that doesn't map to an underlying C++ elememnt. + + Context commands tell QDoc how the element being documented + relates to other documented elememnts, e.g. next and previous page + links or inclusion in page groups or library modules. Context + commands can also provide information about the documented element + that QDoc can't get from the source files, e.g. whether the + element is thread-safe, an overloaded or reimplemented function, + or that it has been deprecated. + + Markup commands tell QDoc how text and image elements in the + document should be rendered, or about the document's outline + structure. */ /*! - \page 02-qdoc-commands.html - \previouspage QDoc Manual - \contentspage QDoc Manual - Table of Contents - \nextpage Markup Commands - - \title QDoc Commands + \page 03-qdoc-commands-markup.html + \contentspage Table of Contents + \previouspage Naming Things + \nextpage Text Markup - There are two main categories of commands for QDoc: markup - commands and meta-commands. + \title Markup Commands The markup commands indicate the generated documentation's visual - appearance and logical structure. The meta-commands provide - information about the documentation unit as well as the documented - item. The meta-commands can be further categorized as topical - commands and contextual commands. - - \section1 Alphabetical List - - A complete \l{QDoc Commands - Alphabetical List } - {alphabetical list of the QDoc commands}. - - \section1 Categories + appearance and logical structure. \list - \o \l {Markup Commands} - \o \l {Topical Commands} - \o \l {Contextual Commands} + \o \l {04-qdoc-commands-textmarkup.html#a-command} {\\a} + \o \l {11-qdoc-commands-specialcontent.html#abstract-command} {\\abstract} + \o \l {06-qdoc-commands-includecodeinline.html#badcode-command} {\\badcode} + \o \l {04-qdoc-commands-textmarkup.html#bold-command} {\\bold} + \o \l {11-qdoc-commands-specialcontent.html#brief-command} {\\brief} + \o \l {04-qdoc-commands-textmarkup.html#c-command} {\\c} + \o \l {09-qdoc-commands-includingimages.html#caption-command} {\\caption} + \o \l {05-qdoc-commands-documentstructure.html#chapter-command} {\\chapter} + \o \l {06-qdoc-commands-includecodeinline.html#code-command} {\\code} + \o \l {07-0-qdoc-commands-includingexternalcode.html#codeline-command} {\\codeline} + \o \l {04-qdoc-commands-textmarkup.html#div-command} {\\div} \span {class="newStuff"} {(new)} + \o \l {07-0-qdoc-commands-includingexternalcode.html#dots-command} {\\dots} + \o \l {12-0-qdoc-commands-miscellaneous.html#else-command} {\\else} + \o \l {12-0-qdoc-commands-miscellaneous.html#endif-command} {\\endif} + \o \l {12-0-qdoc-commands-miscellaneous.html#expire-command} {\\expire} + \o \l {11-qdoc-commands-specialcontent.html#footnote-command} {\\footnote} + \o \l {12-0-qdoc-commands-miscellaneous.html#generatelist-command} {\\generatelist} + \o \l {10-qdoc-commands-tablesandlists.html#header-command} {\\header} + \o \l {04-qdoc-commands-textmarkup.html#i-command} {\\i} + \o \l {12-0-qdoc-commands-miscellaneous.html#if-command} {\\if} + \o \l {09-qdoc-commands-includingimages.html#image-command} {\\image} + \o \l {12-0-qdoc-commands-miscellaneous.html#include-command} {\\include} + \o \l {09-qdoc-commands-includingimages.html#inlineimage-command} {\\inlineimage} + \o \l {08-qdoc-commands-creatinglinks.html#keyword-command} {\\keyword} + \o \l {08-qdoc-commands-creatinglinks.html#l-command} {\\l} + \o \l {11-qdoc-commands-specialcontent.html#legalese-command} {\\legalese} + \o \l {10-qdoc-commands-tablesandlists.html#list-command} {\\list} + \o \l {12-0-qdoc-commands-miscellaneous.html#meta-command} {\\meta} + \o \l {06-qdoc-commands-includecodeinline.html#newcode-command} {\\newcode} + \o \l {10-qdoc-commands-tablesandlists.html#o-command} {\\o} + \o \l {06-qdoc-commands-includecodeinline.html#oldcode-command} {\\oldcode} + \o \l {12-0-qdoc-commands-miscellaneous.html#omit-command} {\\omit} + \o \l {05-qdoc-commands-documentstructure.html#part-command} {\\part} + \o \l {07-0-qdoc-commands-includingexternalcode.html#printline-command} {\\printline} + \o \l {07-0-qdoc-commands-includingexternalcode.html#printto-command} {\\printto} + \o \l {07-0-qdoc-commands-includingexternalcode.html#printuntil-command} {\\printuntil} + \o \l {11-qdoc-commands-specialcontent.html#quotation-command} {\\quotation} + \o \l {07-0-qdoc-commands-includingexternalcode.html#quotefile-command} {\\quotefile} + \o \l {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command} {\\quotefromfile} + \o \l {12-0-qdoc-commands-miscellaneous.html#raw-command} {\\raw} \span {class="newStuff"} {(deprecated)} + \o \l {10-qdoc-commands-tablesandlists.html#row-command} {\\row} + \o \l {08-qdoc-commands-creatinglinks.html#sa-command} {\\sa} + \o \l {05-qdoc-commands-documentstructure.html#sectionOne-command} {\\section1} + \o \l {05-qdoc-commands-documentstructure.html#sectionTwo-command} {\\section2} + \o \l {05-qdoc-commands-documentstructure.html#sectionThree-command} {\\section3} + \o \l {05-qdoc-commands-documentstructure.html#sectionFour-command} {\\section4} + \o \l {07-0-qdoc-commands-includingexternalcode.html#skipline-command} {\\skipline} + \o \l {07-0-qdoc-commands-includingexternalcode.html#skipto-command} {\\skipto} + \o \l {07-0-qdoc-commands-includingexternalcode.html#skipuntil-command} {\\skipuntil} + \o \l {07-0-qdoc-commands-includingexternalcode.html#snippet-command} {\\snippet} + \o \l {04-qdoc-commands-textmarkup.html#span-command} {\\span} \span {class="newStuff"} {(new)} + \o \l {04-qdoc-commands-textmarkup.html#sub-command} {\\sub} + \o \l {04-qdoc-commands-textmarkup.html#sup-command} {\\sup} + \o \l {10-qdoc-commands-tablesandlists.html#table-command} {\\table} + \o \l {11-qdoc-commands-specialcontent.html#tableofcontents-command} {\\tableofcontents} + \o \l {08-qdoc-commands-creatinglinks.html#target-command} {\\target} + \o \l {04-qdoc-commands-textmarkup.html#tt-command} {\\tt} + \o \l {04-qdoc-commands-textmarkup.html#underline-command} {\\underline} + \o \l {12-0-qdoc-commands-miscellaneous.html#raw-command} {\\unicode} + \o \l {11-qdoc-commands-specialcontent.html#warning-command} {\\warning} + \o \l {04-qdoc-commands-textmarkup.html#backslash-command} {\\\\} \endlist */ /*! - \page 03-qdoc-commands-markup.html - \contentspage QDoc Manual - Table of Contents - \previouspage QDoc Commands - \nextpage Text Formatting Commands + \page 04-qdoc-commands-textmarkup.html + \contentspage Table of Contents + \previouspage Markup Commands + \nextpage Document Structure - \title Markup Commands + \title Text Markup - The markup commands indicate the generated documentation's visual - appearance and logical structure. + The text formatting commands indicate how text is to be rendered. - \section1 Alphabetical List - - \l {04-qdoc-commands-textformatting.html#backslash}{\\\\}, - \l {04-qdoc-commands-textformatting.html#a}{\\a}, - \l {11-qdoc-commands-documentcontents.html#abstract}{\\abstract}, - \l {06-qdoc-commands-verbatimcode.html#badcode}{\\badcode}, - \l {04-qdoc-commands-textformatting.html#bold}{\\bold}, - \l {11-qdoc-commands-documentcontents.html#brief}{\\brief}, - \l {04-qdoc-commands-textformatting.html#c}{\\c}, - \l {09-qdoc-commands-graphic.html#caption}{\\caption}, - \l {05-qdoc-commands-documentstructuring.html#chapter}{\\chapter}, - \l {06-qdoc-commands-verbatimcode.html#code}{\\code}, - \l {07-0-qdoc-commands-quoting.html#codeline}{\\codeline}, - \l {07-0-qdoc-commands-quoting.html#dots}{\\dots}, - \l {12-0-qdoc-commands-miscellaneous.html#else}{\\else}, - \l {12-0-qdoc-commands-miscellaneous.html#endif}{\\endif}, - \l {12-0-qdoc-commands-miscellaneous.html#expire}{\\expire}, - \l {11-qdoc-commands-documentcontents.html#footnote}{\\footnote}, - \l {12-0-qdoc-commands-miscellaneous.html#generatelist}{\\generatelist}, - \l {10-qdoc-commands-container.html#header}{\\header}, - \l {04-qdoc-commands-textformatting.html#i}{\\i}, - \l {12-0-qdoc-commands-miscellaneous.html#if}{\\if}, - \l {09-qdoc-commands-graphic.html#image}{\\image}, - \l {12-0-qdoc-commands-miscellaneous.html#include}{\\include}, - \l {09-qdoc-commands-graphic.html#inlineimage}{\\inlineimage}, - \l {08-qdoc-commands-linking.html#keyword}{\\keyword}, - \l {08-qdoc-commands-linking.html#l}{\\l}, - \l {11-qdoc-commands-documentcontents.html#legalese}{\\legalese}, - \l {10-qdoc-commands-container.html#list}{\\list}, - \l {12-0-qdoc-commands-miscellaneous.html#meta}{\\meta}, - \l {06-qdoc-commands-verbatimcode.html#newcode}{\\newcode}, - \l {10-qdoc-commands-container.html#o}{\\o}, - \l {06-qdoc-commands-verbatimcode.html#oldcode}{\\oldcode}, - \l {12-0-qdoc-commands-miscellaneous.html#omit}{\\omit}, - \l {05-qdoc-commands-documentstructuring.html#part}{\\part}, - \l {07-0-qdoc-commands-quoting.html#printline}{\\printline}, - \l {07-0-qdoc-commands-quoting.html#printto}{\\printto}, - \l {07-0-qdoc-commands-quoting.html#printuntil}{\\printuntil}, - \l {11-qdoc-commands-documentcontents.html#quotation}{\\quotation}, - \l {07-0-qdoc-commands-quoting.html#quotefile}{\\quotefile}, - \l {07-0-qdoc-commands-quoting.html#quotefromfile}{\\quotefromfile}, - \l {12-0-qdoc-commands-miscellaneous.html#raw}{\\raw}, - \l {10-qdoc-commands-container.html#row}{\\row}, - \l {08-qdoc-commands-linking.html#sa}{\\sa}, - \l {05-qdoc-commands-documentstructuring.html#sectionOne}{\\section1}, - \l {05-qdoc-commands-documentstructuring.html#sectionTwo}{\\section2}, - \l {05-qdoc-commands-documentstructuring.html#sectionThree}{\\section3}, - \l {05-qdoc-commands-documentstructuring.html#sectionFour}{\\section4}, - \l {07-0-qdoc-commands-quoting.html#skipline}{\\skipline}, - \l {07-0-qdoc-commands-quoting.html#skipto}{\\skipto}, - \l {07-0-qdoc-commands-quoting.html#skipuntil}{\\skipuntil}, - \l {07-0-qdoc-commands-quoting.html#snippet}{\\snippet}, - \l {04-qdoc-commands-textformatting.html#sub}{\\sub}, - \l {04-qdoc-commands-textformatting.html#sup}{\\sup}, - \l {10-qdoc-commands-container.html#table}{\\table}, - \l {11-qdoc-commands-documentcontents.html#tableofcontents} - {\\tableofcontents}, - \l {08-qdoc-commands-linking.html#target}{\\target}, - \l {04-qdoc-commands-textformatting.html#tt}{\\tt}, - \l {04-qdoc-commands-textformatting.html#underline}{\\underline}, - \l {12-0-qdoc-commands-miscellaneous.html#raw}{\\unicode}, - \l {11-qdoc-commands-documentcontents.html#warning}{\\warning} + \target a-command + \section1 \\a (parameter marker) - \section1 Categories - \list - \o \l {Text Formatting Commands} - \o \l {Document Structuring Commands} - \o \l {Verbatim Code Commands} - \o \l {Quoting External Code Commands} - \o \l {Linking Commands} - \o \l {Graphic Commands} - \o \l {Container Commands} - \o \l {Document Contents Commands} - \o \l {Miscellaneous Commands} - \endlist + The \\a command tells QDoc the next word is a formal parameter name. -*/ + A warning is emitted when a formal parameter is not documented or + is misspelled, so when you document a function you should mention + each formal parameter by name in the function description, + preceded by the \\a command. The parameter name is then rendered + in italics. -/*! - \page 04-qdoc-commands-textformatting.html - \contentspage QDoc Manual - Table of Contents - \previouspage Markup Commands - \nextpage Document Structuring Commands + \code + / *! + Constructs a line edit containing the text + \a contents. The \a parent parameter is sent + to the QWidget constructor. + * / - \title Text Formatting Commands + QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent) + { + ... + } - The text formatting commands indicate how the regular text in the - documentation is rendered. + \endcode - \section1 Alphabetical List + QDoc renders this as: - \l {04-qdoc-commands-textformatting.html#backslash}{\\\\}, - \l {04-qdoc-commands-textformatting.html#a}{\\a}, - \l {04-qdoc-commands-textformatting.html#bold}{\\bold}, - \l {04-qdoc-commands-textformatting.html#c}{\\c}, - \l {04-qdoc-commands-textformatting.html#i}{\\i}, - \l {04-qdoc-commands-textformatting.html#sub}{\\sub}, - \l {04-qdoc-commands-textformatting.html#sup}{\\sup}, - \l {04-qdoc-commands-textformatting.html#tt}{\\tt}, - \l {04-qdoc-commands-textformatting.html#underline}{\\underline} + \quotation + \bold {QLineEdit::QLineEdit ( const QString & + contents, QWidget *parent )} - \section1 Command Descriptions + Constructs a line edit containing the text \a contents. + The \a parent parameter is sent to the QWidget constructor. + \endquotation - \table - \header - \o Command - \o Description + You can enclose the formal parameter name in curly brackets, if + you want to, but it isn't necessary. - \row + \target c-command + \section1 \\c (code font) + + The \\c command is used for rendering variable names, user-defined + class names, and C++ keywords (e.g. \c int and \c for) in the code + font. - \o \bold \\\\ \target backslash - \o \bold {The \\\\ command expands to a single backslash.} + The command renders its argument using a typewriter font. For + example: - QDoc commands always start with a backslash alone. To - display an actual backslash in the text you need to type - two of the kind. If you want to display two backslashes, - you need to type four, and so forth. For example: + \code + / *! + The \c AnalogClock class provides a clock widget with hour + and minute hands that is automatically updated every + few seconds. + * / + \endcode - \code - / *! - The \\\\ command is useful if you want a - backslash to appear verbatim, for example, - writing C:\\windows\\home\\. - * / - \endcode + QDoc renders this as: - will be rendered as + \quotation + The \c AnalogClock class provides a clock widget with hour + and minute hands that is automatically updated every + few seconds. + \endquotation - \quotation - The \\\\ command is useful if you want a - backslash to appear verbatim, for example, - writing C:\\windows\\home\\. - \endquotation + If the text to be rendered in the code font contains spaces, enclose the + entire text in curly brackets. - However, if you want your text to appear in a typewriter - font as well, you can use the \l {c}{\\c} command instead, - which accepts and renders the backslash as any other - character. For example: + \code + \c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} + \endcode - \code - / *! - The \\c command is useful if you want a - backslash to appear verbatim, and the word - that contains it written in a typewriter font, - like this: \c {C:\windows\home\}. - * / - \endcode + QDoc renders this as: - will be rendered as + \quotation + \c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} + \endquotation - \quotation - The \\c command is useful if you want a - backslash to appear verbatim, and the word - that contains it written in a typewriter font, - like this: \c {C:\windows\home\}. - \endquotation + The \\c command accepts the special character \c \ within its + argument, i.e. it renders it as a normal character. So if you want + to use nested commands, you must use the \l {tt-command} {teletype + (\\tt)} command instead. - \row - \o \bold \\a \target a - \o \bold {The \\a command indicates that the next word - is a parameter when documenting functions.} + See also \l {tt-command} {\\tt} and \l {code-command} {\\code}. + + \target div-command + \section1 \\div \span {class="newStuff"} {(new)} + + The \\div and \\enddiv commands delimit a large or small block of + text (which may include other QDoc commands) to which special + formatting attributes should be applied. - Warnings are emitted when function parameters are - undocumented or misspelled, so whenever you write - documentation for functions you should make sure you - mention all the parameters and precede each of these by the - \\a command. The parameter is then rendered in italic. For - example: + An argument must be provided in curly braces, as in the qdoc + comment shown below. The argument is not interpreted but is used + as attribute(s) of the tag that is ultimately output by qdoc. - \code - / *! - Constructs a line edit containing the text - \a contents. + For example, we might want to render an inline image so that it + floats to the right of the current block of text: - The \a parent parameter is sent to the - QWidget constructor. - * / + \code + / *! + \div {class="float-right"} + \inlineimage qml-column.png + \enddiv - QLineEdit::QLineEdit(const QString &contents, QWidget *parent) - :QWidget(parent) - { - ... - } + * / + \endcode - \endcode + If qdoc is generating HTML, it will translate these commands to: - will be rendered as + \code + <div class="float-right"><p><img src="images/qml-column.png" /></p></div> + \endcode - \quotation - \bold {QLineEdit::QLineEdit ( const QString & - contents, QWidget *parent )} + For HTML, the attribute value \e {float-right} then will refer to + a clause in the style.css file. which in this case could be: - Constructs a line edit containing the text \a contents. + \code + div.float-right + { + float: right; margin-left: 2em + } + \endcode - The \a parent parameter is sent to the QWidget - constructor. + If qdoc is generating DITA XML, it will translate the commands to: - \endquotation + \code + <sectiondiv outputclass="float-right"> + <p> + <fig> + <image href="images/qml-column.png" placement="inline"/> + </fig> + </p> + </sectiondiv> + \endcode - The \\a command follows the same conventions as the \l - {i}{\\i} command for \l {argument}{punctuation, parentheses - and use of braces} for the argument. However, a parameter - is always a single word, so braces are rarely - necessary. And for the same reason, parentheses seldom - occur. + Your DITA XML publishing program must then recognize the \e + {outputclass} attribute value. - \row - \o \bold \\c \target c - \o \bold {The \\c command can be used to render variables, - user-defined classes and C++ keywords like \c int, - \c for, etc.} + \note The \bold {\\div} command can be nested. + + Below is an example taken from the index.qdoc file used to + generate index.html for Qt 4.7: - The command renders its argument using a typewriter font. For - example: + \code + \div {class="indexbox guide"} + \div {class="heading"} + Qt Developer Guide + \enddiv + \div {class="indexboxcont indexboxbar"} + \div {class="section indexIcon"} \emptyspan + \enddiv + \div {class="section"} + Qt is a cross-platform application and UI + framework. Using Qt, you can write web-enabled + applications once and deploy them across desktop, + mobile and embedded operating systems without + rewriting the source code. + \enddiv + \div {class="section sectionlist"} + \list + \o \l{Getting Started Guides} {Getting started} + \o \l{Installation} {Installation} + \o \l{how-to-learn-qt.html} {How to learn Qt} + \o \l{tutorials.html} {Tutorials} + \o \l{Qt Examples} {Examples} + \o \l{qt4-7-intro.html} {What's new in Qt 4.7} + \endlist + \enddiv + \enddiv + \enddiv + \endcode - \code - / *! - The \c AnalogClock class provides a clock widget with hour - and minute hands that is automatically updated every - few seconds. - * / - \endcode + When all the class attribute values are defined as they are in the + style.css file that is used for rendering the Qt 4.7 documentation, + the above example is rendered as: + + \div {class="indexbox guide"} + \div {class="heading"} + Qt Developer Guide + \enddiv + \div {class="indexboxcont indexboxbar"} + \div {class="section indexIcon"} \emptyspan + \enddiv + \div {class="section"} + Qt is a cross-platform application and UI + framework. Using Qt, you can write web-enabled + applications once and deploy them across desktop, + mobile and embedded operating systems without + rewriting the source code. + \enddiv + \div {class="section sectionlist"} + \list + \o \l{Getting Started Guides} {Getting started} + \o \l{Installation} {Installation} + \o \l{how-to-learn-qt.html} {How to learn Qt} + \o \l{tutorials.html} {Tutorials} + \o \l{Qt Examples} {Examples} + \o \l{qt4-7-intro.html} {What's new in Qt 4.7} + \endlist + \enddiv + \enddiv + \enddiv + + When generating DITA XML, qdoc outputs the nested \e {div} commands as: - will be rendered as + \code + <sectiondiv outputclass="indexbox guide"> + <sectiondiv outputclass="heading"> + <p>Qt Developer Guide</p> + </sectiondiv> + <sectiondiv outputclass="indexboxcont indexboxbar"> + <sectiondiv outputclass="section indexIcon"/> + <sectiondiv outputclass="section"> + <p>Qt is a cross-platform application and UI + framework. Using Qt, you can write + web-enabled applications once and deploy + them across desktop, mobile and embedded + operating systems without rewriting the + source code. + </p> + </sectiondiv> + <sectiondiv outputclass="section sectionlist"> + <ul> + <li> + <xref href="gettingstarted.xml#id-606ee7a8-219b-47b7-8f94-91bc8c76e54c">Getting started</xref> + </li> + <li> + <xref href="installation.xml#id-075c20e2-aa1e-4f88-a316-a46517e50443">Installation</xref> + </li> + <li> + <xref href="how-to-learn-qt.xml#id-49f509b5-52f9-4cd9-9921-74217b9a5182">How to learn Qt</xref> + </li> + <li> + <xref href="tutorials.xml#id-a737f955-a904-455f-b4aa-0dc69ed5a64f">Tutorials</xref> + </li> + <li> + <xref href="all-examples.xml#id-98d95159-d65b-4706-b08f-13d80080448d">Examples</xref> + </li> + <li> + <xref href="qt4-7-intro.xml#id-519ae0e3-4242-4c2a-b2be-e05d1e95f177">What's new in Qt 4.7</xref> + </li> + </ul> + </sectiondiv> + </sectiondiv> + </sectiondiv> + \endcode - \quotation - The \c AnalogClock class provides a clock widget with hour - and minute hands that is automatically updated every - few seconds. - \endquotation + Your DITA XML publishing program must recognize the values of the + \e {outputclass} attribute. + + See also \l {span-command} {\\span}. - The \\c command follows the same conventions as the \l - {i}{\\i} command for \l {argument}{punctuation, parentheses - and use of braces} for the argument. + \target span -command + \section1 \\span \span {class="newStuff"} {(new)} + + The \\span command is for applying special formatting + attributes to a small block of text. + + Two arguments must be provided, each argument in curly braces, as + shown in the qdoc comment below. The first argument is not + interpreted but is used as the formatting attribute(s) of the tag + that is ultimately output by qdoc. The second argument is the text + to be rendered with the special formatting attributes. + + For example, we might want to render the first word of each + element in a numeric list in blue. - The \\c command accepts the special character \c \ within - its argument, i.e. it renders it as a normal character. So - if you want to use nested commands, you must use the \l - {tt}{teletype (\\tt)} command instead. + \code + / *! + Global variables with complex types: + \list 1 + \o \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14 + \o \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15 + \o \span {class="variableName"} {constComplex1} in globals.cpp at line 16 + \o \span {class="variableName"} {constComplex2} in globals.cpp at line 17 + \endlist + * / + \endcode - See also \l {tt}{\\tt} and \l {code}{\\code}. + Class \e {variableName} refers to a clause in your style.css. - \row - \o \bold \\tt \target tt - \o \bold {The \\tt command can be used to render variables, - user-defined classes and C++ keywords like \c int, \c - for, etc.} + \code + .variableName + { + font-family: courier; + color: blue + } + \endcode - The \\tt command behaves just like the \l {c}{\\c} command, - except that \\tt parses QDoc commands (like \l {i}{\\i}, \l - {bold}{\\bold} and \l {underline}{\\underline}) contained - within its argument. + Using the \e {variableName} clause shown above, the example is rendered as: - The command renders its argument using a monospace - font. For example: + Global variables with complex types: + \list 1 + \o \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14 + \o \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15 + \o \span {class="variableName"} {constComplex1} in globals.cpp at line 16 + \o \span {class="variableName"} {constComplex2} in globals.cpp at line 17 + \endlist - \code - / *! - After \c setupUi() populates the main container with - child widgets it scans the main container's list of - slots for names with the form - \tt{on_\i{objectName}_\i{signalName}().} - * / - \endcode + \note The \bold span command does not cause a new paragraph to be + started. - will be rendered as + See also \l {div-command} {\\div}. + + \target tt-command + \section1 \\tt (teletype font) - \quotation - After \c setupUi() populates the main container with - child widgets it scans the main container's list of - slots for names with the form - \tt{on_\i{objectName}_\i{signalName}().} - \endquotation + The \\tt command renders its argument in a monospace font. This + command behaves just like the \l {c-command} {\\c} command, except + that \\tt allows you to nest QDoc commands within the argument + (e.g. \l {i-command} {\\i}, \l {bold-command} {\\bold} and \l + {underline-command} {\\underline}). - The \\tt command follows the same conventions as the \l - {i}{\\i} command for \l {argument}{punctuation, parentheses - and use of braces} for the argument. + \code + / *! + After \c setupUi() populates the main container with + child widgets it scans the main container's list of + slots for names with the form + \tt{on_\e{objectName}_\e{signalName}().} + * / + \endcode - See also \l {c}{\\c}. + QDoc renders this as: - \row - \o \bold \\bold \target bold - \o \bold {The \\bold command renders its argument using - a bold font.} + \quotation + After \c setupUi() populates the main container with + child widgets it scans the main container's list of + slots for names with the form + \tt{on_\e{objectName}_\e{signalName}().} + \endquotation - For example: + If the text to be rendered in the code font contains spaces, enclose the + entire text in curly brackets. - \code - / *! - This is regular text; \bold {this text is - rendered using the \\bold command}. - * / - \endcode + \code + \tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} + \endcode - will be rendered as + QDoc renders this as: - \quotation - This is regular text; \bold {this text is rendered using - the \\bold command}. - \endquotation + \quotation + \tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} + \endquotation - The command follows the same conventions as the \l {i}{\\i} - command for \l {argument}{punctuation, parentheses and use - of braces} for the argument. + See also \l {c-command} {\\c}. - \row - \o \bold \\i \target i - \o \bold {The \\i command renders its argument in italic.} + \target bold-command + \section1 \\bold - \warning This is preliminary functionality. For - more information, see the \l - {26-qdoc-commands-compatibility.html#i-versus-e}{compatibility} - section. + The \\bold command renders its argument in bold font. - \target argument - Normally, a command argument ends at the next whitespace [1], - but braces can be used to group words [2]. For example: + \code + / *! + This is regular text; \bold {this text is + rendered using the \\bold command}. + * / + \endcode - \code - / *! - Here, we render \i {a few words} in italic. - * / - \endcode + QDoc renders this as: - will be rendered as + \quotation + This is regular text; \bold {this text is rendered using + the \\bold command}. + \endquotation - \quotation - Here, we render \i {a few words} in italic. - \endquotation + \target i-command + \section1 \\i (italics) - If you want to use other QDoc commands within an argument - that contains spaces, you always need to enclose the - argument with braces. But QDoc is smart enough to count - parentheses [3], so you don't need braces in cases like this: + The \\i command renders its argument in italics. - \code - / *! - An argument can sometimes contain whitespaces, - for example: \i QPushButton(tr("A Brand New Button")) - * / - \endcode + \warning If \\i doesn't work and you get some strange error + meesages from qdoc3 about using \\o outside of tables and lists, + use \bold{\\e} for italics instead of \\i. For more information, + see the relevant explanation in the section on \l + {26-qdoc-commands-compatibility.html#i-versus-e} {compatibility + issues}. - will be rendered as + If the argument contains spaces or other punctuation, enclose the + argument in curly brackets. - \quotation - An argument can sometimes contain whitespaces, - for example: \i QPushButton(tr("A Brand New Button")) - \endquotation + \code + / *! + Here, we render \i {a few words} in italic. + * / + \endcode - Finally, trailing punctuation is not included in an - argument [4], nor is 's [5] + QDoc renders this as: - \raw HTML - <table align="center" cellpadding="2" - cellspacing="1" border="0"> - <tr valign="top" bgcolor="#a2c511"> - <th></th> - <th>QDoc Syntax</th> - <th>Generated Documentation</th> - </tr> + \quotation + Here, we render \e {a few words} in italic. + \endquotation - <tr valign="top" bgcolor="#d0d0d0"> - <td>1</td> - <td>A variation of a command button is a \i menu - button.</td> - <td>A variation of a command button is a <i>menu</i> - button.</td> - </tr> + If you want to use other QDoc commands within an argument that + contains spaces, you always need to enclose the argument with + braces. But QDoc is smart enough to count parentheses [3], so you + don't need braces in cases like this: - <tr valign="top" bgcolor="#c0c0c0"> - <td>2</td> - <td>The QPushButton widget provides a - \i {command button}.</td> - <td>The QPushButton widget provides a - <i>command button</i>.</td> - </tr> + \code + / *! + An argument can sometimes contain whitespaces, + for example: \i QPushButton(tr("A Brand New Button")) + * / + \endcode - <tr valign="top" bgcolor="#d0d0d0"> - <td>3</td> - <td>Another class of buttons are option buttons - \i (see QRadioButton).</td> - <td>Another class of buttons are option buttons - <i> (see QRadioButton)</i>.</td> - </tr> + QDoc renders this as: - <tr valign="top" bgcolor="#c0c0c0"> - <td>4</td> - <td>A push button emits the signal \i clicked().</td> - <td>A push button emits the signal <i>clicked</i>().</td> - </tr> + \quotation + An argument can sometimes contain whitespaces, + for example: \e QPushButton(tr("A Brand New Button")) + \endquotation - <tr valign="top" bgcolor="#d0d0d0"> - <td>5</td> - <td>The \i QPushButton's checked property is - false by default.</td> - <td>The <i>QPushButton</i>'s checked property is - false by default.</td> - </tr> + Finally, trailing punctuation is not included in an argument [4], + nor is 's [5] - </table> - \endraw + \raw HTML + <table align="center" cellpadding="2" + cellspacing="1" border="0"> + <tr valign="top" bgcolor="#a2c511"> + <th></th> + <th>QDoc Syntax</th> + <th>Generated Documentation</th> + </tr> + + <tr valign="top" bgcolor="#d0d0d0"> + <td>1</td> + <td>A variation of a command button is a \e menu + button.</td> + <td>A variation of a command button is a <i>menu</i> + button.</td> + </tr> + + <tr valign="top" bgcolor="#c0c0c0"> + <td>2</td> + <td>The QPushButton widget provides a + \e {command button}.</td> + <td>The QPushButton widget provides a + <i>command button</i>.</td> + </tr> + + <tr valign="top" bgcolor="#d0d0d0"> + <td>3</td> + <td>Another class of buttons are option buttons + \e (see QRadioButton).</td> + <td>Another class of buttons are option buttons + <i> (see QRadioButton)</i>.</td> + </tr> + + <tr valign="top" bgcolor="#c0c0c0"> + <td>4</td> + <td>A push button emits the signal \e clicked().</td> + <td>A push button emits the signal <i>clicked</i>().</td> + </tr> + + <tr valign="top" bgcolor="#d0d0d0"> + <td>5</td> + <td>The \e QPushButton's checked property is + false by default.</td> + <td>The <i>QPushButton</i>'s checked property is + false by default.</td> + </tr> - \row - \o \bold \\sub \target sub - \o \bold {The \\sub command renders its argument lower - than the baseline of the regular text, using a smaller font.} + </table> + \endraw - For example: + \target sub-command + \section1 \\sub - \code - / *! - Definition (Range): Consider the sequence - {x\sub n}\sub {n > 1} . The set + The \\sub command renders its argument lower than the baseline of + the regular text, using a smaller font. - {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...} + \code + / *! + Definition (Range): Consider the sequence + {x\sub n}\sub {n > 1} . The set - is called the range of the sequence. - * / - \endcode + {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...} - will be rendered as + is called the range of the sequence. + * / + \endcode - \quotation - Definition (Range): Consider the sequence - {x\sub n}\sub {n > 1} . The set + QDoc renders this as: - {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...} + \quotation + Definition (Range): Consider the sequence + {x\sub n}\sub {n > 1} . The set - is called the range of the sequence. - \endquotation + {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...} - The \\sub command follows the same conventions as the \l - {i}{\\i} command for \l {argument}{punctuation, parentheses - and use of braces} for the argument. + is called the range of the sequence. + \endquotation - \row - \o \bold \\sup \target sup - \o \bold {The \\sup command renders its argument higher than - the baseline of the regular text, using a smaller font.} + If the argument contains spaces or other punctuation, enclose the + argument in curly brackets. - For example: + \target sup-command + \section1 \\sup - \code - / *! - The series + The \\sup command renders its argument higher than + the baseline of the regular text, using a smaller font. - 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ... + \code + / *! + The series - is called the \i {geometric series}. - * / - \endcode + 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ... - will be rendered as + is called the \i {geometric series}. + * / + \endcode - \quotation - The series + QDoc renders this as: - 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ... + \quotation + The series - is called the \i {geometric series}. - \endquotation + 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ... - The \\sup command follows the same conventions as the \l - {i}{\\i} command for \l {argument}{punctuation, parentheses - and use of braces} for the argument. + is called the \e {geometric series}. + \endquotation - \row - \o \bold \\underline \target underline - \o \bold {The \\underline command renders its argument underlined.} + If the argument contains spaces or other punctuation, enclose the + argument in curly brackets. - For example: + \target underline-command + \section1 \\underline - \code - / *! - The \underline {F}ile menu gives the users the possibility - to open, and edit, an existing file, save a new or modified - file, and exit the application. - * / - \endcode + The \\underline command renders its argument underlined. - will be rendered as + \code + / *! + The \underline {F}ile menu gives the users the possibility + to open, and edit, an existing file, save a new or modified + file, and exit the application. + * / + \endcode - \quotation - The \underline {F}ile menu gives the users the possibility - to open, and edit, an existing file, save a new or modified - file, and exit the application. - \endquotation + QDoc renders this as: - The \\underline command follows the same conventions as the - \l {i}{\\i} command for \l {argument}{punctuation, - parentheses and use of braces} for the argument. \endtable -*/ + \quotation + The \underline {F}ile menu gives the users the possibility + to open, and edit, an existing file, save a new or modified + file, and exit the application. + \endquotation -/*! - \page 05-qdoc-commands-documentstructuring.html - \previouspage Text Formatting Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Verbatim Code Commands + If the argument contains spaces or other punctuation, enclose the + argument in curly brackets. - \title Document Structuring Commands + \target backslash-command + \section1 \\\\ (double backslash) - The document structuring commands divide the documentation into - sections. In total, there are six levels of sections in QDoc: \c - \part, \c \chapter, \c \section1, \c \section2, \c \section3 and - \c \section4. \c \section1 to \c \section4 correspond to the - traditional section, subsection, subsubsection and - subsubsubsection. + The \\\\ command expands to a single backslash. - \section1 Alphabetical List + QDoc commands always start with a backslash alone. To display an + actual backslash in the text you need to type two of the kind. If + you want to display two backslashes, you need to type four, and so + forth. - \l {05-qdoc-commands-documentstructuring.html#chapter}{\\chapter}, - \l {05-qdoc-commands-documentstructuring.html#part}{\\part}, - \l {05-qdoc-commands-documentstructuring.html#sectionOne}{\\section1}, - \l {05-qdoc-commands-documentstructuring.html#sectionTwo}{\\section2}, - \l {05-qdoc-commands-documentstructuring.html#sectionThree}{\\section3}, - \l {05-qdoc-commands-documentstructuring.html#sectionFour}{\\section4} + \code + / *! + The \\\\ command is useful if you want a + backslash to appear verbatim, for example, + writing C:\\windows\\home\\. + * / + \endcode - \section1 Command Descriptions + QDoc renders this as: - \table - \header - \o Command - \o Description + \quotation + The \\\\ command is useful if you want a + backslash to appear verbatim, for example, + writing C:\\windows\\home\\. + \endquotation - \row - \o \bold \\part \target part - \o \bold {The \\part command is intended for use in - larger documents, and divides the document into parts.} + However, if you want your text to appear in a typewriter font as + well, you can use the \l {c-command} {\\c} command instead, which + accepts and renders the backslash as any other character. For + example: - In general a document structuring command considers - everything that follows it until the first line break as - its argument. The argument is rendered as the unit's - title. If the title needs to be spanned over several lines, - make sure that each line (except the last one) is ended - with a backslash. + \code + / *! + The \\c command is useful if you want a + backslash to appear verbatim, and the word + that contains it written in a typewriter font, + like this: \c {C:\windows\home\}. + * / + \endcode - In total, there are six levels of sections in QDoc: \c - \part, \c \chapter, \c \section1, \c \section2, \c - \section3 and \c \section4. \c \section1 to \c \section4 - correspond to the traditional section, subsection, - subsubsection and subsubsubsection. + QDoc renders this as: - There is a strict ordering of the section units: + \quotation + The \\c command is useful if you want a + backslash to appear verbatim, and the word + that contains it written in a typewriter font, + like this: \c {C:\windows\home\}. + \endquotation + +*/ + +/*! + \page 05-qdoc-commands-documentstructure.html + \previouspage Text Markup + \contentspage Table of Contents + \nextpage Including Code Inline + + \title Document Structure + + The document structuring commands are for dividing your document + into sections. QDoc supports six kinds of sections: \c \part, \c + \chapter, \c \section1, \c \section2, \c \section3 and \c + \section4. The \c \section1..4 commands are the most useful. The + correspond to the traditional section, subsection, etc used in + outlining. + + \target part-command + \section1 \\part + + The \\part command is intended for use in a large document, like a + book. + + In general a document structuring command considers everything + that follows it until the first line break as its argument. The + argument is rendered as the unit's title. If the title needs to be + spanned over several lines, make sure that each line (except the + last one) is ended with a backslash. + + In total, there are six levels of sections in QDoc: \c \part, \c + \chapter, \c \section1, \c \section2, \c \section3 and \c + \section4. \c \section1 to \c \section4 correspond to the + traditional section, subsection, subsubsection and + subsubsubsection. + + There is a strict ordering of the section units: \code part @@ -763,13 +910,12 @@ section4 \endcode - For example, a \c section1 unit can only appear as the top - level section or inside a \c chapter unit. Skipping a - section unit, for example from \c part to \c section1, is - not allowed. + For example, a \c section1 unit can only appear as the top level + section or inside a \c chapter unit. Skipping a section unit, for + example from \c part to \c section1, is not allowed. - You can \i begin with either of the three: \c part, \c - chapter or \c section1. For example: + You can \e begin with either of the three: \c part, \c chapter or + \c section1. \code @@ -829,7 +975,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation \raw HTML @@ -890,154 +1036,96 @@ \endraw \endquotation - Each section level is a logical unit within the - document. Its title will appear on the table of contents - generated by the \l - {11-qdoc-commands-documentcontents.html#tableofcontents} - {\\tableofcontents} command. For example: - - \code - / *! - Contents: + Each section is a logical unit in the document. The section + heading appears in the automatically generated table of contents + that normally appears in the upper righthand corner of the page. - \tableofcontents + \target chapter-command + \section1 \\chapter + + The \\chapter command is intended for use in + larger documents, and divides the document into chapters. - ... - * / - \endcode + See \l{part} {\\part} for an explanation of the various + section units, command argument and rendering. - will expand to + \target sectionOne-command + \section1 \\section1 - \quotation - \raw HTML - <p>Contents:</p> - - <ul> - <li><a href="#Basic Qt">Basic Qt</a></li> - <ul> - <li><a href="#Getting Started">Getting Started</a></li> - <ul> - <li><a href="#Hello Qt">Hello Qt</a></li> - <li><a href="#Making Connections"> - Making Connections</a></li> - <li><a href="#Using the Reference Documentation"> - Using the Reference Documentation</a></li> - </ul> - <li><a href="#Creating Dialogs">Creating Dialogs</a></li> - <ul> - <li><a href="#Subclassing QDialog"> - Subclassing QDialog</a></li> - </ul> - </ul> - <li><a href="#Intermediate Qt">Intermediate Qt</a></li> - <ul> - <li><a href="#Layout Management"> - Layout Management</a></li> - <ul> - <li><a href="#Basic Layouts">Basic Layouts</a></li> - </ul> - </ul> - </ul> + The \\section1 command starts a new section. - ... - \endraw - \endquotation + See \l{part} {\\part} for an explanation of the various + section units, command argument and rendering. - \row - \o \bold \\chapter \target chapter - \o \bold {The \\chapter command is intended for use in - larger documents, and divides the document into chapters.} + \target sectionTwo-command + \section1 \\section2 - See \l{part}{\\part} for an explanation of the various - section units, command argument and rendering. + The \\section2 command starts a new section. - \row - \o \bold \\section1 \target sectionOne - \o \bold {The \\section1 command starts a new section.} + See \l{part} {\\part} for an explanation of the various + section units, command argument and rendering. - See \l{part}{\\part} for an explanation of the various - section units, command argument and rendering. - \row - \o \bold \\section2 \target sectionTwo - \o \bold {The \\section2 command starts a new section.} + \target sectionThree-command + \section1 \\section3 - See \l{part}{\\part} for an explanation of the various - section units, command argument and rendering. + The \\section3 command starts a new section. - \row - \o \bold \\section3 \target sectionThree - \o \bold {The \\section3 command starts a new section.} + See \l{part} {\\part} for an explanation of the various + section units, command argument and rendering. - See \l{part}{\\part} for an explanation of the various - section units, command argument and rendering. + \target sectionFour-command + \section1 \\section4 - \row - \o \bold \\section4 \target sectionFour - \o \bold {The \\section4 command starts a new section.} + The \\section4 command starts a new section. - See \l{part}{\\part} for an explanation of the various - section units, command argument and rendering. + See \l{part} {\\part} for an explanation of the various + section units, command argument and rendering. - \endtable */ /*! - \page 06-qdoc-commands-verbatimcode.html - \previouspage Document Structuring Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Quoting External Code Commands - - \title Verbatim Code Commands - - The following commands are used to render verbatim code within the - documentation. The code is rendered on a new line, using a - typewriter font and the standard indentation. - - \bold{Note:} Although all of these commands can be used to present - C++ code, the \l{07-0-qdoc-commands-quoting.html#snippet}{\\snippet} - and \l{07-0-qdoc-commands-quoting.html#codeline}{\\codeline} commands - should be used in preference to - the others when presenting valid code. This allows auxilliary tools - for Qt language bindings to substitute the relevant code snippets in - place of the C++ ones. + \page 06-qdoc-commands-includecodeinline.html + \previouspage Document Structure + \contentspage Table of Contents + \nextpage Including External Code + + \title Including Code Inline + + The following commands are used to render source code without + formatting. The source code begins on a new line, rendered in the + code. + + \bold{Note:} Although all these commands are for rendering C++ + code, the + \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command} + {\\snippet} and + \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command} + {\\codeline} commands are preferred over the others. These + commands allow equivalent code snippets for other Qt language + bindings to be substituted for the C++ snippets in the + documentation. - \section1 Alphabetical List + \target code-command + \section1 \\code - \l {06-qdoc-commands-verbatimcode.html#badcode}{\\badcode}, - \l {06-qdoc-commands-verbatimcode.html#code}{\\code}, - \l {06-qdoc-commands-verbatimcode.html#newcode}{\\newcode}, - \l {06-qdoc-commands-verbatimcode.html#oldcode}{\\oldcode} + The \\code and \\endcode commands enclose a snippet of source code. - \section1 Command Descriptions + \note The \l {c-command} {\\c} command can be used for short code + fragments within a sentence. The \\code command is for longer code + snippets. It renders the code verbatim in a separate paragraph in + the code font. - \table - \header - \o Command - \o Description + When processing any of the \\code, \l {badcode-command} + {\\badcode}, \l {newcode-command} {\\newcode} or \l + {oldcode-command} {\\oldcode} commands, QDoc removes all + indentation that is common for the verbatim code blocks within a + \c{/}\c{*!} ... \c{*}\c{/} comment before it adds the standard + indentation. For that reason the recommended style is to use 8 + spaces for the verbatim code contained within these commands - \row - \o \bold \\code \target code - \o \bold {The \\code command and the corresponding - \\endcode command delimit a piece of verbatim code.} - - Whereas the \l {c}{\\c} command can be used for short code - fragments within a sentence, the \\code command is for - longer code snippets and renders the code verbatim in a - separate paragraph using a typewriter font and the standard - indentation. - - When processing any of the \\code, \l {badcode}{\\badcode}, - \l {newcode}{\\newcode} and \l {oldcode}{\\oldcode} - commands, QDoc basically removes all indentation that is - common for the verbatim code blocks within a \c{/}\c{*!} ... - \c{*}\c{/} comment before it adds the standard - indentation. For that reason the recommended style is to - use 8 spaces for the verbatim code contained within these - commands (note that this doesn't apply to externally - quoted code using the \l {quotefromfile}{\\quotefromfile} - or \l {quotefile}{\\quotefile} command). - - For example: + \note This doesn't apply to externally quoted code using the \l + {quotefromfile-command} {\\quotefromfile} or \l + {quotefile-command} {\\quotefile} command. \code / *! @@ -1053,7 +1141,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \code #include <QApplication> @@ -1065,34 +1153,35 @@ } \endcode - Other QDoc commands are disabled within - \\code... \\endcode, and the special character '\\' is - accepted and rendered like the rest of the code. + Other QDoc commands are disabled within \\code... \\endcode, and + the special character '\\' is accepted and rendered like the rest + of the code. - You need to type the code manually between the \\code and - \\endcode commands. If you want to include code snippets - from a particular file, use the \l - {07-0-qdoc-commands-quoting.html#quotefromfile}{\\quotefromfile} - command instead. + To include code snippets from an external file, use the + \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command} + {\\snippet} and + \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command} + {\\codeline} commands. - See also \l {c}{\\c}, \l - {07-0-qdoc-commands-quoting.html#quotefromfile}{\\quotefromfile}, - \l {badcode}{\\badcode}, \l {newcode}{\\newcode} and \l - {oldcode}{\\oldcode}. + See also \l {c-command} {\\c}, \l + {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command} + {\\quotefromfile}, \l {badcode-command} {\\badcode}, \l + {newcode-command} {\\newcode} and \l {oldcode-command} + {\\oldcode}. - \row - \o \bold \\badcode \target badcode - \o \bold {The \\badcode command and the corresponding - \\endcode command delimit a piece of code that doesn't - compile or is wrong for some other reason.} + \target badcode-command + \section1 \\badcode - The \\badcode command is similar the \l {code}{\\code} - command, but renders the code using a grey font instead of - black (the default). + The \\badcode and \\endcode commands delimit a snippet of code + that doesn't compile or is wrong for some other reason. - Like the \l {code}{\\code} command, it renders its code on - a new line in the documentation using a typewriter font and - the standard indentation. For example: + The \\badcode command is similar to the \l {code-command} {\\code} + command, but it renders the code snippet using a grey font instead + of black. + + Like the \l {code-command} {\\code} command, this command begins + its code snippet on a new line rendered in the code font and with + the standard indentation. \code / *! @@ -1112,7 +1201,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation The statement below is rendered using the @@ -1130,30 +1219,29 @@ \endcode \endquotation - Other QDoc commands are disabled within - \\badcode... \\endcode, and the special character '\\' is - accepted and rendered like the rest of the code. + Other QDoc commands are disabled within \\badcode... \\endcode, + and the special character '\\' is accepted and rendered like the + rest of the code. - See also \l {code}{\\code}, \l {newcode}{\\newcode} and \l - {oldcode}{\\oldcode}. + See also \l {code-command} {\\code}, \l {newcode-command} + {\\newcode} and \l {oldcode-command} {\\oldcode}. - \row - \o \bold \\newcode \target newcode - \o \bold {The \\newcode command, and the associated \\oldcode - and \\endcode commands, indicate how to port a piece of - code to a new version of an API.} - - The \\newcode command, and its companion the \\oldcode - command, is a convenience combination of the \l - {code}{\\code} and \l {badcode}{\\badcode} commands: The - combination provides a text relating the two code snippets - to each other. The command requires a preceding \\oldcode - statement. - - Like the \l {code}{\\code} and \l {badcode}{\\badcode} - commands, the \\newcode command renders its code on a new - line in the documentation using a typewriter font and the - standard indentation. For example: + \target newcode-command + \section1 \\newcode + + The \\newcode, \\oldcode, and \\endcode commands enable you to + show how to port a snippet of code to a new version of an API. + + The \\newcode command, and its companion the \\oldcode command, is + a convenience combination of the \l {code-command} {\\code} and \l + {badcode-command} {\\badcode} commands: The combination provides a + text relating the two code snippets to each other. The command + requires a preceding \\oldcode statement. + + Like the \l {code-command} {\\code} and \l {badcode-command} + {\\badcode} commands, the \\newcode command renders its code on a + new line in the documentation using a typewriter font and the + standard indentation. \code / *! @@ -1168,7 +1256,7 @@ * / \endcode - is rendered like this: + QDoc renders this as: \quotation \oldcode @@ -1181,76 +1269,102 @@ \endcode \endquotation - Other QDoc commands are disabled within - \\oldcode ... \\endcode, and the '\\' character doesn't need - to be escaped. + Other QDoc commands are disabled within \\oldcode ... \\endcode, + and the '\\' character doesn't need to be escaped. - \row - \o \bold \\oldcode \target oldcode - \o \bold {The \\oldcode command requires a corresponding - \\newcode statement; otherwise QDoc fails to parse the command - and emits a warning.} + \target oldcode-command + \section1 \\oldcode - See also \l {newcode}{\\newcode} and \l {badcode}{\\badcode}. - \endtable + The \\oldcode command requires a corresponding + \\newcode statement; otherwise QDoc fails to parse the command + and emits a warning. + + See also \l {newcode-command} {\\newcode} and \l {badcode-command} {\\badcode}. + + \target qml-command + \section1 \\qml \span {class="newStuff"} {(new)} + + The \\qml and \\endqml commands enclose a snippet of QML source + code. Currently, QDoc handles \\qml and \\endqml exactly the same + as \\code and \\endcode. + + \code + / *! + \qml + import QtQuick 1.0 + + Row { + Rectangle { + width: 100; height: 100 + color: "blue" + transform: Translate { y: 20 } + } + Rectangle { + width: 100; height: 100 + color: "red" + transform: Translate { y: -20 } + } + } + \endqml + * / + \endcode + + QDoc renders this as: + + \qml + import QtQuick 1.0 + + Row { + Rectangle { + width: 100; height: 100 + color: "blue" + transform: Translate { y: 20 } + } + Rectangle { + width: 100; height: 100 + color: "red" + transform: Translate { y: -20 } + } + } + \endqml */ /*! - \page 07-0-qdoc-commands-quoting.html - \previouspage Verbatim Code Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Linking Commands + \page 07-0-qdoc-commands-includingexternalcode.html + \previouspage Including Code Inline + \contentspage Table of Contents + \nextpage Creating Links - \title Quoting External Code Commands + \title Including External Code - The following commands enable quoting from files in the - documentation: You can make QDoc include the complete contents of + The following commands enable you to include code snippets from + external files. You can make QDoc include the complete contents of a file, or you can quote specific parts of the file and skip others. The typical use of the latter is to quote a file chunk by chunk. - \bold{Note:} Although all of these commands can be used to present - C++ code, the \l{#snippet}{\\snippet} and \l{#codeline}{\\codeline} - commands should be used in preference to - the others when presenting valid code. This allows auxilliary tools - for Qt language bindings to substitute the relevant code snippets in - place of the C++ ones. - - \section1 Alphabetical List - - \l {07-0-qdoc-commands-quoting.html#codeline}{\\codeline}, - \l {07-0-qdoc-commands-quoting.html#dots}{\\dots}, - \l {07-0-qdoc-commands-quoting.html#printline}{\\printline}, - \l {07-0-qdoc-commands-quoting.html#printto}{\\printto}, - \l {07-0-qdoc-commands-quoting.html#printuntil}{\\printuntil}, - \l {07-0-qdoc-commands-quoting.html#quotefile}{\\quotefile}, - \l {07-0-qdoc-commands-quoting.html#quotefromfile}{\\quotefromfile}, - \l {07-0-qdoc-commands-quoting.html#skipline}{\\skipline}, - \l {07-0-qdoc-commands-quoting.html#skipto}{\\skipto}, - \l {07-0-qdoc-commands-quoting.html#skipuntil}{\\skipuntil}, - \l {07-0-qdoc-commands-quoting.html#snippet}{\\snippet} - - \section1 Command Descriptions - - \table - \header - \o Command - \o Description + \bold{Note:} Although all these commands are for rendering C++ + code, the + \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command} + {\\snippet} and + \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command} + {\\codeline} commands are preferred over the others. These + commands allow equivalent code snippets for other Qt language + bindings to be substituted for the C++ snippets in the + documentation. - \row - \o \bold \\quotefile \target quotefile - \o \bold {The \\quotefile command expands to the complete - contents of the file given as argument.} + \target quotefile-command + \section1 \\quotefile - The command considers the rest of the line as part of its - argument, make sure to follow the file name with a line - break. + The \\quotefile command expands to the complete contents of the + file given as argument. - The file's contents is rendered in a separate paragraph, - using a typewriter font and the standard indentation. The - code is shown verbatim. + The command considers the rest of the line as part of its + argument, make sure to follow the file name with a line break. - For example: + The file's contents is rendered in a separate paragraph, using a + typewriter font and the standard indentation. The code is shown + verbatim. \code / *! @@ -1263,7 +1377,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation This is a simple "Hello world" example: @@ -1274,29 +1388,29 @@ application up and running. \endquotation - \warning If you use the \l {QDoc - Compatibility}{compat.qdocconf} file this command is called - \\include. + \warning If you use the \l {Compatibility Issues} + {compat.qdocconf} file this command is called \\include. - See also \l {quotefromfile}{\\quotefromfile} and \l - {code}{\\code}. + See also \l {quotefromfile-command} {\\quotefromfile} and + \l {code-command} {\\code}. - \row - \o \bold \\quotefromfile \target quotefromfile - \o \bold {The \\quotefromfile command opens the file - given as argument for quoting.} - - The command considers the rest of the line as part of its - argument, make sure to follow the file name with a line - break. - - The command is intended for use when quoting parts from - file with the walkthrough commands: \l - {printline}{\\printline}, \l {printto}{\\printto}, \l - {printuntil}{\\printuntil}, \l {skipline}{\\skipline}, \l - {skipto}{\\skipto}, \l {skipuntil}{\\skipuntil}. This - enables you to quote specific portions of a file. For - example: + + \target quotefromfile-command + \section1 \\quotefromfile + + The \\quotefromfile command opens the file given as argument for + quoting. + + The command considers the rest of the line as part of its + argument, make sure to follow the file name with a line break. + + The command is intended for use when quoting parts from file with + the walkthrough commands: \l {printline-command} {\\printline}, \l + {printto-command} {\\printto}, \l {printuntil-command} + {\\printuntil}, \l {skipline-command} {\\skipline}, \l + {skipto-command} {\\skipto}, \l {skipuntil-command} + {\\skipuntil}. This enables you to quote specific portions of a + file. \code / *! @@ -1321,7 +1435,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation The whole application is contained within @@ -1344,38 +1458,35 @@ ... \endquotation - (\l {Example File}{The complete example file...}) + (\l {Example File} {The complete example file...}) - QDoc remembers which file it's quoting, and the current - position within that file (see \l {file}{\\printline} for - more information). There is no need to "close" the file. + QDoc remembers which file it's quoting, and the current position + within that file (see \l {file} {\\printline} for more + information). There is no need to "close" the file. - Earlier we called this command \\quotefile. For more - information, see the \l - {26-qdoc-commands-compatibility.html#quotefromfile-versus-quotefile} - {compatibility} section. + Earlier we called this command \\quotefile. For more information, + see the \l + {26-qdoc-commands-compatibility.html#quotefromfile-versus-quotefile} + {compatibility} section. - See also \l {quotefile}{\\quotefile}, \l {code}{\\code} and - \l {dots}{\\dots}. + See also \l {quotefile-command} {\\quotefile}, \l {code-command} + {\\code} and \l {dots} {\\dots}. - \row - \o \bold \\printline \target printline - \o \bold {The \\printline command expands to the line - from the current position to the next non-blank line of - the current souce file.} + \target printline-command + \section1 \\printline - To ensure that the documentation always is synchronized - with the source file, a substring of the line must be - specified as an argument to the command. Note that the - command considers the rest of the line as part of its - argument, make sure to follow the substring with a line - break. + The \\printline command expands to the line from the current + position to the next non-blank line of the current souce file. - The line from the source file is rendered as a separate - paragraph, using a typewriter font and the standard - indentation. The code is shown verbatim. + To ensure that the documentation remains synchronized with the + source file, a substring of the line must be specified as an + argument to the command. Note that the command considers the rest + of the line as part of its argument, make sure to follow the + substring with a line break. - For example: + The line from the source file is rendered as a separate paragraph, + using a typewriter font and the standard indentation. The code is + shown verbatim. \code / *! @@ -1403,7 +1514,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation There has to be exactly one QApplication object @@ -1430,22 +1541,20 @@ The main function... \endquotation - (\l {Example File}{The complete example file...}) + (\l {Example File} {The complete example file...}) - \target file + \target file - QDoc reads the file sequentially. To move the current - position forward you can use either of the \l - {skipline}{\\skip...} commands. To move the current - position backward, you can use the \l - {quotefromfile}{\\quotefromfile} command again. + QDoc reads the file sequentially. To move the current position + forward you can use either of the \l {skipline-command} + {\\skip...} commands. To move the current position backward, you + can use the \l {quotefromfile-command} {\\quotefromfile} command + again. - \target substring + \target substring - If the substring argument is surrounded by slashes it is - interpreted as a \l {regular expression}. - - For example: + If the substring argument is surrounded by slashes it is + interpreted as a \l {regular expression}. \code / *! @@ -1462,7 +1571,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation \quotefromfile widgets/scribble/mainwindow.cpp @@ -1477,39 +1586,36 @@ application. \endquotation - (\l {widgets/scribble}{The complete example file...}) + (\l {widgets/scribble} {The complete example file...}) - The regular expression \c /^\}/ makes QDoc print until the - first '}' character occurring at the beginning of the line - without indentation. /.../ encloses the regular expression, - and '^' means the beginning of the line. The '}' character - must be escaped since it is a special character in regular - expressions. + The regular expression \c /^\}/ makes QDoc print until the first + '}' character occurring at the beginning of the line without + indentation. /.../ encloses the regular expression, and '^' means + the beginning of the line. The '}' character must be escaped since + it is a special character in regular expressions. - QDoc will emit a warning if the specified substring or - regular expression cannot be located, i.e. if the source - code has changed. + QDoc will emit a warning if the specified substring or regular + expression cannot be located, i.e. if the source code has changed. - See also \l {printto}{\\printto} and \l - {printuntil}{\\printuntil}. + See also \l {printto-command} {\\printto} and \l + {printuntil-command} {\\printuntil}. - \row - \o \bold \\printto \target printto - \o \bold {The \\printto command expands to all the lines - from the current position up to and \i excluding the - next line containing a given substring.} + \target printto-command + \section1 \\printto - The command considers the rest of the line as part of its - argument, make sure to follow the substring with a line - break. The command also follows the same conventions for \l - {file}{positioning} and \l {substring}{argument} as the \l - {printline}{\\printline} command. + The \\printto command expands to all the lines from the current + position up to and \e excluding the next line containing a given + substring. - The lines from the source file are rendered in a separate - paragraph, using a typewriter font and the standard - indentation. The code is shown verbatim. + The command considers the rest of the line as part of its + argument, make sure to follow the substring with a line break. The + command also follows the same conventions for \l {file} + {positioning} and \l {substring} {argument} as the \l + {printline-command} {\\printline} command. - For example: + The lines from the source file are rendered in a separate + paragraph, using a typewriter font and the standard + indentation. The code is shown verbatim. \code / *! @@ -1524,7 +1630,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation The whole application is contained within the @@ -1538,28 +1644,27 @@ and \c argv parameters... \endquotation - (\l {Example File}{The complete example file...}) + (\l {Example File} {The complete example file...}) - See also \l {printline}{\\printline} and \l - {printuntil}{\\printuntil}. + See also \l {printline-command} {\\printline} and \l + {printuntil-command} {\\printuntil}. - \row - \o \bold \\printuntil \target printuntil - \o \bold {The \\printuntil command expands to all the lines - from the current position up to and \i including the next line - containing a given substring.} + \target printuntil-command + \section1 \\printuntil - The command considers the rest of the line as part of its - argument, make sure to follow the substring with a line - break. The command also follows the same conventions for \l - {file}{positioning} and \l {substring}{argument} as the \l - {printline}{\\printline} command. + The \\printuntil command expands to all the lines from the current + position up to and \e including the next line containing a given + substring. - The lines from the source file are rendered in a separate - paragraph, using a typewriter font and the standard - indentation. The code is shown verbatim. + The command considers the rest of the line as part of its + argument, make sure to follow the substring with a line break. The + command also follows the same conventions for \l {file} + {positioning} and \l {substring} {argument} as the \l + {printline-command} {\\printline} command. - For example: + The lines from the source file are rendered in a separate + paragraph, using a typewriter font and the standard + indentation. The code is shown verbatim. \code / *! @@ -1576,7 +1681,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation The whole application is contained within the @@ -1587,33 +1692,33 @@ \printuntil hello First we create a \l - {http://qt.nokia.com/doc/4.0/qapplication}{QApplication} + {http://qt.nokia.com/doc/4.0/qapplication} {QApplication} object using the \c argc and \c argv parameters, then we create a \l - {http://qt.nokia.com/doc/4.0/qpushbutton}{QPushButton}. + {http://qt.nokia.com/doc/4.0/qpushbutton} {QPushButton}. \endquotation - (\l {Example File}{The complete example file...}) + (\l {Example File} {The complete example file...}) - See also \l {printline}{\\printline} and \l - {printto}{\\printto}. + See also \l {printline-command} {\\printline} and \l + {printto-command} {\\printto}. - \row - \o \bold \\skipline \target skipline - \o \bold {The \\skipline command ignores the next non-blank - line in the current source file.} - - Doc reads the file sequentially, and the \\skipline command - is used to move the current position (omitting a line of - the source file). See the remark about \l {file}{file - positioning} above. - - The command considers the rest of the line as part of its - argument, make sure to follow the substring with a line - break. The command also follows the same conventions for \l - {substring}{argument} as the \l {printline}{\\printline} - command, and it is used in conjunction with the \l - {quotefromfile}{\\quotefromfile} command. For example: + \target skipline-command + \section1 \\skipline + + The \\skipline command ignores the next non-blank line in the + current source file. + + Doc reads the file sequentially, and the \\skipline command is + used to move the current position (omitting a line of the source + file). See the remark about \l {file} {file positioning} above. + + The command considers the rest of the line as part of its + argument, make sure to follow the substring with a line break. The + command also follows the same conventions for \l {substring} + {argument} as the \l {printline-command} {\\printline} command, + and it is used in conjunction with the \l {quotefromfile-command} + {\\quotefromfile} command. \code / *! @@ -1631,7 +1736,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation \l @@ -1649,30 +1754,30 @@ that contains its definition. \endquotation - (\l {Example File}{The complete example file...}) + (\l {Example File} {The complete example file...}) - See also \l {skipto}{\\skipto}, \l - {skipuntil}{\\skipuntil} and \l {dots}{\\dots}. + See also \l {skipto-command} {\\skipto}, \l {skipuntil-command} + {\\skipuntil} and \l {dots} {\\dots}. - \row - \o \bold \\skipto \target skipto - \o \bold {The \\skipto command ignores all the lines from the - current position up to and \i excluding the next line - containing a given substring.} + \target skipto-command + \section1 \\skipto - QDoc reads the file sequentially, and the \\skipto command - is used to move the current position (omitting one or - several lines of the source file). See the remark about \l - {file}{file positioning} above. + The \\skipto command ignores all the lines from the current + position up to and \e excluding the next line containing a given + substring. - The command considers the rest of the line as part of its - argument, make sure to follow the substring with a line - break. + QDoc reads the file sequentially, and the \\skipto command is used + to move the current position (omitting one or several lines of the + source file). See the remark about \l {file} {file positioning} + above. - The command also follows the same conventions for \l - {substring}{argument} as the \l {printline}{\\printline} - command, and it is used in conjunction with the \l - {quotefromfile}{\\quotefromfile} command. For example: + The command considers the rest of the line as part of its + argument, make sure to follow the substring with a line break. + + The command also follows the same conventions for \l {substring} + {argument} as the \l {printline-command} {\\printline} command, + and it is used in conjunction with the \l {quotefromfile-command} + {\\quotefromfile} command. \code / *! @@ -1691,7 +1796,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation The whole application is contained within @@ -1707,30 +1812,30 @@ reasonable size ... \endquotation - (\l {Example File}{The complete example file...}) + (\l {Example File} {The complete example file...}) - See also \l {skipline}{\\skipline}, \l - {skipuntil}{\\skipuntil} and \l {dots}{\\dots}. + See also \l {skipline-command} {\\skipline}, \l + {skipuntil-command} {\\skipuntil} and \l {dots} {\\dots}. - \row - \o \bold \\skipuntil \target skipuntil - \o \bold {The \\skipuntil command ignores all the lines from - the current position up to and \i including the next line - containing a given substring.} + \target skipuntil-command + \section1 \\skipuntil - QDoc reads the file sequentially, and the \\skipuntil - command is used to move the current position (omitting one - or several lines of the source file). See the remark about - \l {file}{file positioning} above. + The \\skipuntil command ignores all the lines from the current + position up to and \e including the next line containing a given + substring. - The command considers the rest of the line as part of its - argument, make sure to follow the substring with a line - break. + QDoc reads the file sequentially, and the \\skipuntil command is + used to move the current position (omitting one or several lines + of the source file). See the remark about \l {file} {file + positioning} above. - The command also follows the same conventions for \l - {substring}{argument} as the \l {printline}{\\printline} - command, and it is used in conjunction with the \l - {quotefromfile}{\\quotefromfile} command. For example: + The command considers the rest of the line as part of its + argument, make sure to follow the substring with a line break. + + The command also follows the same conventions for \l {substring} + {argument} as the \l {printline-command} {\\printline} command, + and it is used in conjunction with the \l {quotefromfile-command} + {\\quotefromfile} command. \code / *! @@ -1748,7 +1853,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation The first thing we did in the \c main() function was to @@ -1764,20 +1869,21 @@ will return when the application exits... \endquotation - (\l {Example File}{The complete example file...}) + (\l {Example File} {The complete example file...}) - See also \l {skipline}{\\skipline}, \l {skipto}{\\skipto} - and \l {dots}{\\dots}. + See also \l {skipline-command} {\\skipline}, \l {skipto-command} + {\\skipto} and \l {dots} {\\dots}. - \row - \o \bold \\dots \target dots - \o \bold {The \\dots command indicates that parts of the - source file have been omitted when quoting a file.} + \target dots-command + \section1 \\dots - The command is used in conjunction with the \l - {quotefromfile}{\\quotefromfile} command, and should be - stated on its own line. The dots are rendered on a new - line, using a typewriter font. For example: + The \\dots command indicates that parts of the source file have + been omitted when quoting a file. + + The command is used in conjunction with the \l + {quotefromfile-command} {\\quotefromfile} command, and should be + stated on its own line. The dots are rendered on a new line, using + a typewriter font. \code / *! @@ -1790,7 +1896,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotefromfile examples/main.cpp \skipto main @@ -1799,54 +1905,54 @@ \skipuntil exec \printline } - (\l {Example File}{The complete example file...}) + (\l {Example File} {The complete example file...}) - The default indentation is 4 spaces, but this can be - adjusted using the command's optional argument. For - example: + The default indentation is 4 spaces, but this can be adjusted + using the command's optional argument. - \code - / *! - \dots 0 - \dots - \dots 8 - \dots 12 - \dots 16 - * / - \endcode + \code + / *! + \dots 0 + \dots + \dots 8 + \dots 12 + \dots 16 + * / + \endcode - will be rendered as + QDoc renders this as: - \dots 0 - \dots - \dots 8 - \dots 12 - \dots 16 + \dots 0 + \dots + \dots 8 + \dots 12 + \dots 16 - See also \l {skipline}{\\skipline}, \l - {skipto}{\\skipto} and \l {skipuntil}{\\skipuntil}. + See also \l {skipline-command} {\\skipline}, \l {skipto-command} + {\\skipto} and \l {skipuntil-command} {\\skipuntil}. - \row - \o \bold \\snippet \target snippet - \o \bold {The \\snippet command causes a code snippet to be included - verbatim as preformatted text, which may be syntax highlighted.} - - Each code snippet are referenced by the file that holds it and by - a unique identifier for that file. Snippet files are typically - stored in a \c{snippets} directory inside the documentation - directory (e.g., \c{$QTDIR/doc/src/snippets}). + \target snippet-command + \section1 \\snippet + + The \\snippet command causes a code snippet to be included + verbatim as preformatted text, which may be syntax highlighted. - For example, the following documentation references a snippet in - a file residing in a subdirectory of the documentation directory: + Each code snippet are referenced by the file that holds it and by + a unique identifier for that file. Snippet files are typically + stored in a \c{snippets} directory inside the documentation + directory (e.g., \c{$QTDIR/doc/src/snippets}). + + For example, the following documentation references a snippet in a + file residing in a subdirectory of the documentation directory: \code \snippet snippets/textdocument-resources/main.cpp Adding a resource \endcode - The text following the file name is the unique identifier for the - snippet. This is used to delimit the quoted code in the relevant - snippet file as shown in the following example that corresponds to - the above \c{\\snippet} command: + The text following the file name is the unique identifier for the + snippet. This is used to delimit the quoted code in the relevant + snippet file as shown in the following example that corresponds to + the above \c{\\snippet} command: \dots \code @@ -1859,18 +1965,20 @@ //! [Adding a resource] \endcode \dots - \row - \o \bold \\codeline \target codeline - \o \bold{The \\codeline command inserts a blank line of preformatted - text. It is used to insert gaps between snippets without closing - the current preformatted text area and opening a new one.} - \endtable + + \target codeline-command + \section1 \\codeline + + The \\codeline command inserts a blank line of preformatted + text. It is used to insert gaps between snippets without closing + the current preformatted text area and opening a new one. + */ /*! \page 07-1-example.html - \previouspage Quoting External Code Commands - \contentspage QDoc Manual - Table of Contents + \previouspage Including External Code + \contentspage Table of Contents \title Example File @@ -1878,541 +1986,528 @@ */ /*! - \page 08-qdoc-commands-linking.html - \previouspage Quoting External Code Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Graphic Commands + \page 08-qdoc-commands-creatinglinks.html + \previouspage Including External Code + \contentspage Table of Contents + \nextpage Including Images - \title Linking Commands + \title Creating Links - The linking commands make it possible to create hyperlinks to - classes, functions, header files and examples. They also make it - possible to link to targets within a document, as well as to other - documents and URLs. + These commands are for creating hyperlinks to classes, functions, + examples, and other targets. - \section1 Alphabetical List + \target l-command + \section1 \\l (link) - \l {08-qdoc-commands-linking.html#keyword}{\\keyword}, - \l {08-qdoc-commands-linking.html#l}{\\l}, - \l {08-qdoc-commands-linking.html#sa}{\\sa}, - \l {08-qdoc-commands-linking.html#target}{\\target} + The \\l link command is used to create a hyperlink to many + different kinds of targets. The command's general syntax is: - \section1 Command Descriptions + \code + \l {link target} {link text} + \endcode - \table - \header - \o Command - \o Description + \code + / *! + Read the \l {http://qt.nokia.com/doc/4.0/} + {Qt's Reference Documentation} carefully. + * / + \endcode - \row - \o \bold \\l \target l - \o \bold {The \\l command is used to create hyperlinks. } + QDoc renders this as: - The command's general syntax is + \quotation + Read the \l {http://qt.nokia.com/doc/4.0/} + {Qt's Reference Documentation} carefully. + \endquotation - \code - \l {link target}{link text} - \endcode + If the link target is equivalent to the link text, the second + argument can be omitted. - For example: + For example, if you have documentation like: - \code - / *! - Read the \l {http://qt.nokia.com/doc/4.0/} - {Qt's Reference Documentation} carefully. - * / - \endcode + \code + / *! + \target assertions - will be rendered as + Assertions make some statement about the text at the + point where they occur in the regexp but they do not + match any characters. - \quotation - Read the \l {http://qt.nokia.com/doc/4.0/} - {Qt's Reference Documentation} carefully. - \endquotation + ... - If the link target is equivalent to the link text, the - second argument can be omitted. + Regexps are built up from expressions, quantifiers, and + \l {assertions} {assertions}. + * / + \endcode - For example, if you have documentation like: + You can simplify this as follows: - \code - / *! - \target assertions + \code + / *! + \target assertions - Assertions make some statement about the text at the - point where they occur in the regexp but they do not - match any characters. + Assertions make some statement about the text at the + point where they occur in the regexp but they do not + match any characters. - ... + ... - Regexps are built up from expressions, quantifiers, and - \l {assertions}{assertions}. - * / - \endcode + Regexps are built up from expressions, quantifiers, and + \l assertions. + * / + \endcode - you can rewrite it as + For the one-parameter version the braces can often be omitted. + The \\l command supports several kinds of links: - \code - / *! - \target assertions + \list - Assertions make some statement about the text at the - point where they occur in the regexp but they do not - match any characters. + \o \c {\l QWidget} - The name of a class documented with the \l + {class-command} {\\class} command. - ... + \o \c {\l QWidget::sizeHint()} - The name of a member function, + documented with or without an \l {fn-command} {\\fn} command. - Regexps are built up from expressions, quantifiers, and - \l assertions. - * / - \endcode + \o \c {\l <QtGlobal>} - The subject of a \l {headerfile-command} + {\\headerfile} command. - For the one-parameter version the braces can often - be omitted. See the \l {i}{\\i} command for the \l - {argument}{argument conventions}. + \o \c {\l widgets/wiggly} - The relative path used in an \l + {example-command} {\\example} command. - The \\l command supports several kinds of links: + \o \c {\l {QWidget Class Reference}} - The title used in a + \l {title-command} {\\title} command. - \list - \o \c {\l QWidget} - a defined \l {class}{\\class} - \o \c {\l QWidget::sizeHint()} - a defined member - function (\l {fn}{\\fn}) - \o \c {\l <QtGlobal>} - a defined \l {headerfile}{\\headerfile} - \o \c {\l widgets/wiggly} - a defined - \l {example-command}{\\example} - \o \c {\l {QWidget Class Reference}} - a defined \l {title}{\\title} - \o \c {\l {Introduction}}- a defined \l{part}{\\part}, - \l{chapter}{\\chapter} or \l {sectionOne}{\\section...} - \o \c {\l fontmatching} - a defined \l {target}{\\target} - \o \c {\l {Shared Classes}} - a defined \l {keyword}{\\keyword} - \o \c {\l network.html} - a defined \l {page}{\\page} - \o \c {\l http://www.trolltech.com/} - a URL - \endlist + \o \c {\l {Introduction to QDoc}}- The text from one of the + \l{part-command} {\\part}, \l{chapter} {\\chapter} or \l + {sectionOne-command} {\\section} commands. - QDoc also tries to make a link out of any words that don't - resemble any normal English words, for example Qt class - names or functions, like QWidget or QWidget::sizeHint(). In - these cases, the \\l command can actually be omitted, but - by using the command, you ensure that QDoc will emit a - warning if it cannot find the link target. In addition, if - you only want the function name to appear in the link, you - can use the following syntax: + \o \c {\l fontmatching} - The argument of a \l {target-command} + {\\target} command. - \list - \o \c {\l {QWidget::}{sizeHint()}} - \endlist + \o \c {\l {Shared Classes}} - A keyword named in a \l + {keyword-command} {\\keyword} command. - See also \l {sa}{\\sa}, \l {target}{\\target} and \l - {keyword}{\\keyword}. + \o \c {\l network.html} - The file name used in a \l + {page-command} {\\page} command. - \row - \o \bold \\sa \target sa - \o \bold {The \\sa command defines a list of links that will - be rendered in a separate "See also" section at the bottom - of the documentation.} + \o \c {\l http://www.trolltech.com/} - A URL. - The command takes a comma-separated list of links as its - argument. If the line ends with a comma, you can continue - on a second line. The general syntax is: + \endlist - \code - \sa {the first link}, {the second link}, - {the third link}, ... - \endcode + QDoc also tries to make a link out of any words that don't + resemble any normal English words, for example Qt class names or + functions, like QWidget or QWidget::sizeHint(). In these cases, + the \\l command can actually be omitted, but by using the command, + you ensure that QDoc will emit a warning if it cannot find the + link target. In addition, if you only want the function name to + appear in the link, you can use the following syntax: - QDoc will automatically try to generate "See also" links - interconnecting a property's various functions. For - example, an setVisible() function will automatically get a - link to visible() and vice versa. + \list + \o \c {\l {QWidget::} {sizeHint()}} + \endlist - In general, QDoc will generate "See also" links that - interconnect the functions that access the same - property. It recognizes four different syntax versions: + QDoc renders this as: - \list - \o \c property() - \o \c setProperty() - \o \c isProperty() - \o \c hasProperty() - \endlist + \quotation + \l {QWidget::} {sizeHint()} + \endquotation - The \\sa command supports the same kind - of links as the \l {l}{\\l} command. For example: + See also \l {sa-command} {\\sa}, \l {target-command} {\\target} + and \l {keyword-command} {\\keyword}. - \code - / *! - Appends the actions \a actions to this widget's - list of actions. - \sa removeAction(), QMenu, addAction() - * / - void QWidget::addActions(QList<QAction *> actions) - { - ... - } - \endcode + \target sa-command + \section1 \\sa (see also) - will be rendered as + The \\sa command defines a list of links that will be rendered in + a separate "See also" section at the bottom of the documentation + unit. - \quotation - \bold {void QWidget::addActions ( QList<QAction*> - \i actions )} + The command takes a comma-separated list of links as its + argument. If the line ends with a comma, you can continue + the list on the next line. The general syntax is: - Appends the actions \i actions to this widget's - list of actions. + \code + \sa {the first link}, {the second link}, + {the third link}, ... + \endcode - See also \l {QWidget::removeAction()}{removeAction()}, - \l QMenu, and \l {QWidget::addAction()}{addAction()}. - \endquotation + QDoc will automatically try to generate "See also" links + interconnecting a property's various functions. For example, a + setVisible() function will automatically get a link to visible() + and vice versa. - See also \l {l}{\\l}, \l {target}{\\target} and \l - {keyword}{\\keyword}. + In general, QDoc will generate "See also" links that interconnect + the functions that access the same property. It recognizes four + different syntax versions: - \row - \o \bold \\target \target target - \o \bold {The \\target command defines an explicit point in the - documentation that you can later link to using the \l {l}{\\l} - and \l {sa}{\\sa} commands.} + \list + \o \c property() + \o \c setProperty() + \o \c isProperty() + \o \c hasProperty() + \endlist - The command considers the rest of the line as part of its - argument, make sure to follow the target name with a line - break. + The \\sa command supports the same kind of links as the \l + {l-command} {\\l} command. - For example: + \code + / *! + Appends the actions \a actions to this widget's + list of actions. + + \sa removeAction(), QMenu, addAction() + * / + void QWidget::addActions(QList<QAction *> actions) + { + ... + } + \endcode - \code - / *! - \target capturing parentheses - \section1 Capturing Text + QDoc renders this as: - Parentheses allow us to group elements together so that - we can quantify and capture them. + \quotation + \bold {void QWidget::addActions ( QList<QAction*> + \e actions )} - ... - * / - \endcode + Appends the actions \e actions to this widget's list of + actions. - can be referenced with + See also \l {QWidget::removeAction()} {removeAction()}, + \l QMenu, and \l {QWidget::addAction()} {addAction()}. + \endquotation - \list - \o \c {\l {capturing parentheses}} - (from elsewhere in the same comment) - \o \c {\l qregexp.html#capturing-parentheses} - (from anywhere else) - \endlist + See also \l {l-command} {\\l}, \l {target-command} {\\target} and + \l {keyword-command} {\\keyword}. - within a documentation unit, and with - \list - \o \c {\l http://www.trolltech.com/4.0/doc/html/qregexp.html#capturing-parentheses} - \endlist + \target target-command + \section1 \\target - on a more global scale. + The \\target command names a place in the documentation that you + can link to using the \l {l-command} {\\l (link)} and \l + {sa-command} {\\sa (see also)} commands. - If the target name does't contain any spaces, the brackets can - be omitted as well. + The text up to the line break becomes the target name. Be sure to + follow the target name with a line break. Curly brackets are not + required around the target name, but they may be required when the + target name is used in a link cammand. See below. - See also \l {l}{\\l}, \l {sa}{\\sa} and \l - {keyword}{\\keyword}. + \code + / *! + \target capturing parentheses + \section1 Capturing Text - \row - \o \bold \\keyword \target keyword - \o \bold {The \\keyword command defines an explicit point in the - documentation that you can later link to using the \l {l}{\\l} - and \l {sa}{\\sa} commands.} + Parentheses allow us to group elements together so that + we can quantify and capture them. - Keywords must be unique within the entire set of - documentation processed in on QDoc run. The command - considers the rest of the line as part of its argument, - make sure to follow the keyword with a line break. + ... + * / + \endcode - The \\keyword command is similar to \l {target}{\\target}, - but stronger. A keyword can be referenced from anywhere - using a simple syntax. For example: + The target name \e{capturing parentheses} can be linked from + within the same document containing the target in two ways: - \code - / *! - \class QRegExp - \reentrant - \brief The QRegExp class provides pattern - matching using regular expressions. - \ingroup tools - \ingroup misc - \ingroup shared - \mainclass + \list + \o \c {\l {capturing parentheses}} (from within the same qdoc comment) + \o \c {\l qregexp.html#capturing-parentheses} (from elsewhere in the same document) + \endlist - \keyword regular expression + \note The brackets in the link example are required because the + target name contains spaces. - Regular expressions, or "regexps", provide a way to - find patterns within text. + From other documents, the target name can be linked this way: - ... - * / - \endcode + \list + \o \c {\l http://www.trolltech.com/4.0/doc/html/qregexp.html#capturing-parentheses} + \endlist - can be referenced like this + See also \l {l-command} {\\l}, \l {sa-command} {\\sa} and \l + {keyword-command} {\\keyword}. - \code - / *! - When a string is surrounded by slashes, it's - interpreted as a \l regular expression. - * / - \endcode + \target keyword-command + \section1 \\keyword - which will be rendered as + The \\keyword command names a place in the documentation that you + can link to using the \l {l-command} {\\l (link)} and \l + {sa-command} {\\sa (see also)} commands. - \quotation - When a string is surrounded by slashes, it's - interpreted as a \l {regular expression}. - \endquotation + The \\keyword command is like the \l {target-command} {\\target} + command, but stronger. A keyword can be linked from anywhere using + a simple syntax. - If the keyword does't contain any spaces, the brackets can - be omitted as well. + Keywords must be unique over all the documents processed during + the QDoc run. The command uses the rest of the line as its + argument. Be sure to follow the keyword with a line break. - See also \l {l}{\\l}, \l {sa}{\\sa} and \l - {target}{\\target}. - \endtable -*/ -/*! - \page 09-qdoc-commands-graphic.html - \previouspage Linking Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Container Commands + \code + / *! + \class QRegExp + \reentrant + \brief The QRegExp class provides pattern + matching using regular expressions. + \ingroup tools + \ingroup misc + \ingroup shared + \mainclass - \title Graphic Commands + \keyword regular expression - The graphic commands makes it possible to include images in the - documentation. The images can be rendered as separate paragraphs, - or within running text. + Regular expressions, or "regexps", provide a way to + find patterns within text. - \section1 Alphabetical List + ... + * / + \endcode - \l {09-qdoc-commands-graphic.html#caption}{\\caption}, - \l {09-qdoc-commands-graphic.html#image}{\\image}, - \l {09-qdoc-commands-graphic.html#inlineimage}{\\inlineimage} + The location marked with the keyword can be linked with: - \section1 Command Descriptions + \code + / *! + When a string is surrounded by slashes, it is + interpreted as a \l {regular expression}. + * / + \endcode - \table - \header - \o Command - \o Description + QDoc renders this as: - \row - \o \bold \\image \target image - \o \bold {The \\image command expands to the image specified by its - argument, and renders it centered as a separate paragraph.} + \quotation + When a string is surrounded by slashes, it's + interpreted as a \l {regular expression}. + \endquotation - The \\image command replaces the old \\img command. For more - information, see the \l - {26-qdoc-commands-compatibility.html#image-versus-img} - {compatibility} section. + If the keyword text contains spaces, the brackets are required. - The command takes two arguments. The first is the name of - the image file. The second argument is optional and is a - simple description of the image equivalent to the HTML - alt="" in an image tag. The description is used for - tooltips, and when a browser doesn't support images like - the Lynx text browser. + See also \l {l-command} {\\l (link)}, \l {sa-command} {\\sa (see + also)} and \l {target-command} {\\target}. - The command considers the rest of the line after the file - name its second argument, make sure that you follow the - filename or description with a line break. Braces are only - necessary if the description spans several lines. +*/ - For example: +/*! + \page 09-qdoc-commands-includingimages.html + \previouspage Creating Links + \contentspage Table of Contents + \nextpage Tables and Lists - \code - / *! - Qt by Trolltech is a C++ toolkit for cross-platform GUI - application development. + \title Including Images - \image happyguy.jpg "Happy guy" + The graphic commands makes it possible to include images in the + documentation. The images can be rendered as separate paragraphs, + or within running text. - Qt provides single-source portability across Microsoft - Windows, Mac OS X, Linux, and all major commercial Unix - variants. It is also available for embedded devices. - * / - \endcode + \target image-command + \section1 \\image - will be rendered as + The \\image command expands to the image specified by its first + argument, and renders it centered as a separate paragraph. - \quotation - Qt by Trolltech is a C++ toolkit for cross-platform GUI - application development. + The \\image command replaces the old \\img command. For more + information, see the \l + {26-qdoc-commands-compatibility.html#image-versus-img} + {compatibility} section. - \image happyguy.jpg image "Happy guy" + The command takes two arguments. The first argument is the name of + the image file. The second argument is optional and is a simple + description of the image, equivalent to the HTML alt="" in an image + tag. The description is used for tooltips, and for when a browser + doesn't support images, like the Lynx text browser. - Qt provides single-source portability across Microsoft - Windows, Mac OS X, Linux, and all major commercial Unix - variants. It is also available for embedded devices. - \endquotation + The remaining text \e{after} the file name is the optional, + description argument. Be sure to follow the file name or the + description with a line break. Curly brackets are required if the + description argument spans multiple lines. - See also \l {inlineimage}{\\inlineimage} and \l - {caption}{\\caption}. + \code + / *! + Qt by Trolltech is a C++ toolkit for cross-platform GUI + application development. - \row - \o \bold \\inlineimage \target inlineimage - \o \bold {The \\inlineimage command expands to the image - specified by its argument; the image is rendered inline - with the rest of the text.} + \image happyguy.jpg "Happy guy" - The command takes two arguments. The first is the name of - the image file. The second argument is optional and is a - simple description of the image equivalent to the HTML - alt="" in an image tag. The description is used for - tooltips, and when a browser doesn't support images like - the Lynx text browser. + Qt provides single-source portability across Microsoft + Windows, Mac OS X, Linux, and all major commercial Unix + variants. It is also available for embedded devices. + * / + \endcode - The most common use of the \\inlineimage command is in - lists and tables. For example: + QDoc renders this as: - \code - / *! - \list 1 - \o \inlineimage happy.gif Oh so happy! - \o \inlineimage happy.gif Oh so happy! - \o \inlineimage happy.gif Oh so happy! - \endlist - * / - \endcode + \quotation + Qt by Trolltech is a C++ toolkit for cross-platform GUI + application development. - will be rendered as + \image happyguy.jpg image "Happy guy" - \list 1 - \o \inlineimage happy.gif Oh so happy! - \o \inlineimage happy.gif Oh so happy! - \o \inlineimage happy.gif Oh so happy! - \endlist + Qt provides single-source portability across Microsoft + Windows, Mac OS X, Linux, and all major commercial Unix + variants. It is also available for embedded devices. + \endquotation - And + See also \l {inlineimage-command} {\\inlineimage} and \l + {caption-command} {\\caption}. - \code - / *! - \table - \header - \o Trolltech - \o Trolltech - \row - \o \inlineimage happy.gif Oh so happy! - \o \inlineimage happy.gif Oh so happy! - \row - \o \inlineimage happy.gif Oh so happy! - \o \inlineimage happy.gif Oh so happy! - \endtable - * / - \endcode + \target inlineimage-command + \section1 \\inlineimage - will be rendered as + The \\inlineimage command expands to the image specified by its + argument. The image is rendered inline with the rest of the text. - \raw HTML - <table align="center" cellpadding="2" - cellspacing="1" border="0"> - <tr valign="top" bgcolor="#a2c511"> - <th>Trolltech</th> - <th>Trolltech</th> - </tr> + The command takes two arguments. The first argument is the name of + the image file. The second argument is optional and is a simple + description of the image, equivalent to the HTML alt="" in an image + tag. The description is used for tooltips, and for when a browser + doesn't support images, like the Lynx text browser. - <tr valign="top" bgcolor="#f0f0f0"> - <td><img src="images/happy.gif" alt="Oh so happy!" /> - </td> - <td><img src="images/happy.gif" alt="Oh so happy!" /> - </td> - </tr> + The most common use of the \\inlineimage command is in lists and + tables. Here is an example of including inline images in a list: - <tr valign="top" bgcolor="#f0f0f0"> - <td><img src="images/happy.gif" alt="Oh so happy!"/> - </td> - <td><img src="images/happy.gif" alt="Oh so happy!" /> - </td> - </tr> + \code + / *! + \list 1 + \o \inlineimage happy.gif Oh so happy! + \o \inlineimage happy.gif Oh so happy! + \o \inlineimage happy.gif Oh so happy! + \endlist + * / + \endcode - </table> - \endraw + QDoc renders this as: - The command can also be used to insert an image - inline with the regular text. For example: + \list 1 + \o \inlineimage happy.gif Oh so happy! + \o \inlineimage happy.gif Oh so happy! + \o \inlineimage happy.gif Oh so happy! + \endlist - \code - / *! - \inlineimage training.jpg Training by Trolltech - The Qt Programming course is offered as a - five day Open Enrollment Course. The classes - are open to the public.While the course is open - to anyone who wants to learn, attendees should - have significant experience in C++ development - to derive maximum benefit from the course. - * / - \endcode + Her eis an example of including inline images in a table: - will be rendered as + \code + / *! + \table + \header + \o Trolltech + \o Trolltech + \row + \o \inlineimage happy.gif Oh so happy! + \o \inlineimage happy.gif Oh so happy! + \row + \o \inlineimage happy.gif Oh so happy! + \o \inlineimage happy.gif Oh so happy! + \endtable + * / + \endcode - \quotation - \inlineimage training.jpg Training by Trolltech - The Qt Programming course is offered as a - five day Open Enrollment Course. The classes - are open to the public.While the course is open - to anyone who wants to learn, attendees should - have significant experience in C++ development - to derive maximum benefit from the course. - \endquotation + QDoc renders this as: + + \raw HTML + <table align="center" cellpadding="2" + cellspacing="1" border="0"> + <tr valign="top" bgcolor="#a2c511"> + <th>Trolltech</th> + <th>Trolltech</th> + </tr> + <tr valign="top" bgcolor="#f0f0f0"> + <td><img src="images/happy.gif" alt="Oh so happy!" /> + </td> + <td><img src="images/happy.gif" alt="Oh so happy!" /> + </td> + </tr> + <tr valign="top" bgcolor="#f0f0f0"> + <td><img src="images/happy.gif" alt="Oh so happy!"/> + </td> + <td><img src="images/happy.gif" alt="Oh so happy!" /> + </td> + </tr> + </table> + \endraw - See also \l {image}{\\image} and \l {caption}{\\caption}. + The command can also be used to insert an image inline with the + text. - \row - \o \bold \\caption \target caption - \o \bold {The \\caption command provides a caption for an image.} + \code + / *! + \inlineimage training.jpg Training by Trolltech + The Qt Programming course is offered as a + five day Open Enrollment Course. The classes + are open to the public.While the course is open + to anyone who wants to learn, attendees should + have significant experience in C++ development + to derive maximum benefit from the course. + * / + \endcode + + QDoc renders this as: - The command follows the same conventions for parentheses and use - of braces for its \l argument as the \l {i}{\\i} command. + \quotation + \inlineimage training.jpg Training by Trolltech + The Qt Programming course is offered as a + five day Open Enrollment Course. The classes + are open to the public.While the course is open + to anyone who wants to learn, attendees should + have significant experience in C++ development + to derive maximum benefit from the course. + \endquotation - \warning This is preliminary functionality. The - command is not fully implemented. + See also \l {image-command} {\\image} and \l {caption-command} {\\caption}. - See also \l {image}{\\image} and \l - {inlineimage}{\\inlineimage} + \target caption-command + \section1 \\caption - \endtable -*/ + The \\caption command provides a caption for an image. -/*! - \page 10-qdoc-commands-container.html - \previouspage Graphic Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Document Contents Commands + The command takes all the text up to the end of the paragraph to + be the caption. Experiment until you get the effect you want. - \title Container Commands + \code + / *! + \table 100% + \row + \o \image windowsvista-pushbutton.png + \caption The QPushButton widget provides a command button. + \o \image windowsvista-toolbutton.png + \caption The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar. + \endtable + * / + \endcode - The container commands create tables and lists with associated - items and contents. A list is rendered left aligned as a separate - paragraph. A table is rendered centered as a separate paragraph, - and its width depends on its content. + QDoc renders this as: - \section1 Alphabetical List + \table 100% + \row + \o \image windowsvista-pushbutton.png + \caption The QPushButton widget provides a command button. + \o \image windowsvista-toolbutton.png + \caption The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar. + \endtable - \l {10-qdoc-commands-container.html#header}{\\header}, - \l {10-qdoc-commands-container.html#list}{\\list}, - \l {10-qdoc-commands-container.html#o}{\\o}, - \l {10-qdoc-commands-container.html#omitvalue}{\\omitvalue}, - \l {10-qdoc-commands-container.html#row}{\\row}, - \l {10-qdoc-commands-container.html#table}{\\table}, - \l {10-qdoc-commands-container.html#value}{\\value} + See also \l {image-command} {\\image} and \l {inlineimage-command} + {\\inlineimage} +*/ - \section1 Command Descriptions +/*! + \page 10-qdoc-commands-tablesandlists.html + \previouspage Including Images + \contentspage Table of Contents + \nextpage Special Content - \table - \header - \o Command - \o Description + \title Tables and Lists - \row - \o \bold \\table \target table - \o \bold {The \\table command and the corresponding \\endtable - command delimit the contents of a table.} + These commands enable creating lists and tables. A list is + rendered left aligned as a separate paragraph. A table is rendered + centered as a separate paragraph. The table width depends on the + width of its contents. - The command accepts a single argument specifying the - table's width in percentage: + \target table-command + \section1 \\table + + The \\table and \\endtable commands delimit the contents of a + table. + + The command accepts a single argument specifying the table's width + as a percentage of the page width: \code / *! @@ -2424,15 +2519,15 @@ * / \endcode - The code above ensures that the table will fill all - available space. If the table's width is smaller than 100 %, - the table will be centered in the generated documentation. + The code above ensures that the table will fill all available + space. If the table's width is smaller than 100 %, the table will + be centered in the generated documentation. - A table can contain headers, rows and columns. A row starts - with a \l {row}{\\row} command and consists of cells, which - starts with a \l {o}{\\o} command. There is also a \l - {header}{\\header} command which is a special kind of row - with a special formatting. For example: + A table can contain headers, rows and columns. A row starts with a + \l {row-command} {\\row} command and consists of cells, which + starts with a \l {o-command} {\\o} command. There is also a \l + {header-command} {\\header} command which is a special kind of row + with a special formatting. \code / *! @@ -2458,7 +2553,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \raw HTML <table align="center" cellpadding="2" @@ -2498,8 +2593,8 @@ </table> \endraw - You can also make cells span several rows and columns. For - example: + You can also make cells span several rows and columns. For + example: \code / *! @@ -2519,7 +2614,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \raw HTML <table align="center" cellpadding="2" cellspacing="1" @@ -2548,20 +2643,20 @@ </table> \endraw - See also \l {header}{\\header}, \l {row}{\\row} and \l {o}{\\o}. + See also \l {header-command} {\\header}, \l {row-command} {\\row} and \l {o-command} {\\o}. - \row - \o \bold \\header \target header - \o \bold {The \\header command indicates that the following - table cells are the current table's column headers.} + \target header-command + \section1 \\header + + The \\header command indicates that the following table cells are + the current table's column headers. - The command can only be used within the \l{table} - {\\table...\\endtable} commands. A header can contain - several cells. A cell is created with the \l {o}{\\o} - command. + The command can only be used within the \l{table-command} + {\\table...\\endtable} commands. A header can contain several + cells. A cell is created with the \l {o-command} {\\o} command. - A header cell's text is centered within the table cell and - rendered using a bold font. For example: + A header cell's text is centered within the table cell and + rendered using a bold font. \code / *! @@ -2577,7 +2672,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \raw HTML <table align="center" cellpadding="2" @@ -2598,23 +2693,22 @@ </table> \endraw - See also \l {table}{\\table}, \l {row}{\\row} and \l {o}{\\o}. + See also \l {table-command} {\\table}, \l {row-command} {\\row} and \l {o-command} {\\o}. - \row - \o \bold \\row \target row - \o \bold {The \\row command indicates that the following table - cells belong to the same row in the current table.} + \target row-command + \section1 \\row - The command can only be used within the \l{table} - {\\table...\\endtable} commands. A row can contain - several cells. A cell is created with the \l {o}{\\o} - command. + The \\row command begins a new row in a table. The \l {o-command} + {\\o items} that belong in the new row will immediately follow the + \\row. - The background cell color of each row alternate between two - shades of grey, making it easier to distinguish the rows - from each other. The cells' contents is left aligned. + The command can only be used within the \l{table-command} + {\\table...\\endtable} commands. A row can contain several + cells. A cell is created with the \l {o-command} {\\o} command. - For example: + The background cell color of each row alternates between two + shades of grey, making it easier to distinguish the rows from each + other. The cells' contents is left aligned. \code / *! @@ -2640,7 +2734,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \raw HTML <table align="center" cellpadding="2" @@ -2680,44 +2774,45 @@ </table> \endraw - See also \l {table}{\\table}, \l {header}{\\header} and \l - {o}{\\o}. + See also \l {table-command} {\\table}, \l {header-command} + {\\header} and \l {o-command} {\\o}. - \row - \o \bold \\value \target value - \o \bold {The \\value command starts the documentation of a C++ enum - item}. + \target value-command + \section1 \\value - The command's first argument is the enum item. Then follows - its associated description. The description argument ends - at the next blank line or \\value. The arguments are - rendered within a table. + The \\value command starts the documentation of a C++ enum item. - The documentation will be located in the associated class, - header file or namespace documentation. See the \l - {enum}{\\enum} documentation for an example. + The command's first argument is the enum item. Then follows its + associated description. The description argument ends at the next + blank line or \\value. The arguments are rendered within a table. - See also \l {enum}{\\enum} and \l {omitvalue}{\\omitvalue}. + The documentation will be located in the associated class, header + file or namespace documentation. See the \l {enum-command} + {\\enum} documentation for an example. - \row - \o \bold \\omitvalue \target omitvalue - \o \bold {The \\omitvalue command excludes a C++ enum item - from the documentation}. + See also \l {enum-command} {\\enum} and \l {omitvalue-command} {\\omitvalue}. + + \target omitvalue-command + \section1 \\omitvalue - The command's only argument is the name of the enum item - that will be omitted. See the \l {enum}{\\enum} - documentation for an example. + The \\omitvalue command excludes a C++ enum item from the + documentation. - See also \l {enum}{\\enum} and \l {value}{\\value}. + The command's only argument is the name of the enum item that will + be omitted. See the \l {enum-command} {\\enum} documentation for + an example. - \row - \o \bold \\list \target list - \o \bold {The \\list command and the corresponding \\endlist - command delimit a list of items.} + See also \l {enum-command} {\\enum} and \l {value-command} + {\\value}. + + \target list-command + \section1 \\list + + The \\list and \\endlist commands delimit a list of items. - You need to create each list item explicitly using the \l - {o}{\\o} command. A list can contain one or more items; it - can also be nested. For example: + Create each list item with the \l {o-command} {\\o} command. A + list always contains one or more items. Lists can be nested. For + example: \code / *! @@ -2738,7 +2833,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \list \o Qt Reference Documentation: Getting Started @@ -2755,8 +2850,8 @@ \endlist \endlist - The \\list command takes an optional argument providing - alternative appearances for the list items. For example: + The \\list command takes an optional argument providing + alternative appearances for the list items. \code / *! @@ -2768,7 +2863,7 @@ * / \endcode - will render the list items with bullets (the default): + QDoc renders the list items with bullets (the default): \list \o How to Learn Qt @@ -2776,9 +2871,12 @@ \o Tutorial and Examples \endlist - If you provide 'A' as an argument to the \\list command, - the bullets are replaced with characters following in - alphabetical order: + \warning There appears to be a bug in qdoc3 here. If you include + any of the argument types, you get a numeric list. We're looking + into it. + + If you provide 'A' as an argument to the \\list command, the + bullets are replaced with characters in alphabetical order: \list A \o How to Learn Qt @@ -2786,8 +2884,8 @@ \o Tutorial and Examples \endlist - If you replace 'A' with '1', the list items are rendered - with numbers following in ascending order: + If you replace 'A' with '1', the list items are numbered in + ascending order: \list 1 \o How to Learn Qt @@ -2796,8 +2894,8 @@ \endlist - If you provide 'i' as the argument, the default bullets are - replaced with roman numerals: + If you provide 'i' as the argument, the bullets are replaced with + roman numerals: \list i \o How to Learn Qt @@ -2805,9 +2903,9 @@ \o Tutorial and Examples \endlist - Or finally, you can make the list items appear with roman - numbers following in ascending order if you provide 'I' as - the optional argument: + Finally, you can make the list items appear with roman numbers + following in ascending order if you provide 'I' as the optional + argument: \list I \o How to Learn Qt @@ -2815,9 +2913,9 @@ \o Tutorial and Examples \endlist - You can also make the listing start at any character or - number by simply provide the number or character you want - to start at. For example: + You can also make the listing start at any character or number by + simply provide the number or character you want to start at. For + example: \code / *! @@ -2829,7 +2927,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \list G \o How to Learn Qt @@ -2837,30 +2935,30 @@ \o Tutorial and Examples \endlist - See also \l {o}{\\o}. + See also \l {o-command} {\\o}. - \row - \o \bold \\o \target o - \o \bold {The \\o command announce a table or list item.} + \target o-command + \section1 \\o (cell, item) - Earlier we used the \l {i}{\\i} command for this purpose. For more - information see the \l - {26-qdoc-commands-compatibility.html#o-versus-i}{compatibility} - section. + The \\o command announce a table or list item. - The command can only be used within the \l{table} - {\\table...\\endtable} or \l{list}{\\list... \\endlist} - commands. + Earlier we used the \l {i-command} {\\i} command for this + purpose. For more information see the \l + {26-qdoc-commands-compatibility.html#o-versus-i} {compatibility} + section. - It considers everything until the next occurrence - of the \\o command, or the currently applicable \l - {table}{\\endtable} or \l {list}{\\endlist} command, as its - argument. For examples, see \l {table}{\\table} and \l - {list}{\\list}. + The command can only be used within the \l{table-command} + {\\table...\\endtable} or \l{list-command} {\\list... \\endlist} + commands. - If the command is used within a table, you can in addition - specify how many rows or columns the item should span. For - example: + It considers everything until the next occurrence of the \\o + command, or the currently applicable \l {table-command} + {\\endtable} or \l {list-command} {\\endlist} command, as its + argument. For examples, see \l {table-command} {\\table} and \l + {list-command} {\\list}. + + If the command is used within a table, you can in addition specify + how many rows or columns the item should span. \code / *! @@ -2880,7 +2978,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \raw HTML <table align="center" cellpadding="2" cellspacing="1" @@ -2909,333 +3007,133 @@ </table> \endraw - If not specified, the item will span one column and one row. + If not specified, the item will span one column and one row. + + See also \l {table-command} {\\table}, \l {header-command} + {\\header}, \l {list-command} {\\list} and \l {o-command} {\\o}. - See also \l {table}{\\table}, \l {header}{\\header}, - \l {list}{\\list} and \l {o}{\\o}. - \endtable */ /*! - \page 11-qdoc-commands-documentcontents.html - \previouspage Container Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Miscellaneous Commands + \page 11-qdoc-commands-specialcontent.html + \previouspage Tables and Lists + \contentspage Table of Contents + \nextpage Miscellaneous - \title Document Contents Commands + \title Special Content The document contents commands identify parts of the documentation, i.e. parts with a special rendering, conceptual meaning or function. - \section1 Alphabetical List - - \l {11-qdoc-commands-documentcontents.html#abstract}{\\abstract}, - \l {11-qdoc-commands-documentcontents.html#brief}{\\brief}, - \l {11-qdoc-commands-documentcontents.html#footnote}{\\footnote}, - \l {11-qdoc-commands-documentcontents.html#legalese}{\\legalese}, - \l {11-qdoc-commands-documentcontents.html#tableofcontents} - {\\tableofcontents}, - \l {11-qdoc-commands-documentcontents.html#quotation}{\\quotation}, - \l {11-qdoc-commands-documentcontents.html#warning}{\\warning} - - \section1 Command Descriptions - - \table - \header - \o Command - \o Description - - \row - \o \bold \\abstract \target abstract - \o \bold {The \\abstract command and the corresponding \\endabstract - command delimit a document's abstract section.} - - The abstract section is rendered as an indented italicized - paragraph. - - \warning This is preliminary funcionality. The - command is not fully implemented. Currently, the abstract - section is rendered as a regular HTML paragraph. For - example: - - \code - / *! - \abstract - Qt by Trolltech is a C++ toolkit for cross-platform - GUI application development. Qt provides - single-source portability across Microsoft Windows, - Mac OS X, Linux, and all major commercial Unix - variants. It is also available for embedded - devices. - \endabstract - * / - \endcode - - will be rendered as - - \abstract - Qt by Trolltech is a C++ toolkit for cross-platform GUI - application development. Qt provides single-source - portability across Microsoft Windows, Mac OS X, Linux, - and all major commercial Unix variants. It is also - available for embedded devices. - \endabstract - - \row - \o \bold \\quotation \target quotation - \o \bold { The \\quotation command and the corresponding - \\endquotation command delimit a quotation remark.} - - This command replaces the old \\quote command. For more - information see the \l - {26-qdoc-commands-compatibility.html#quotation-versus-quote} - {compatibility} section. - - The remark is rendered as a separate centered - paragraph. For example: - - \code - / *! - While the prospect of a significantly broader market is - good news for Firstlogic, the notion also posed some - challenges. Dave Dobson, director of technology for the La - Crosse, Wisconsin-based company, said: - - - \quotation - As our solutions were being adopted into new - environments, we saw an escalating need for easier - integration with a wider range of enterprise - applications. - \endquotation - * / - \endcode - - will be rendered as - - While the prospect of a significantly broader market is - good news for Firstlogic, the notion also posed some - challenges. Dave Dobson, director of technology for the La - Crosse, Wisconsin-based company, said: - - \quotation - As our solutions were being adopted into new - environments, we saw an escalating need for easier - integration with a wider range of enterprise - applications. - \endquotation - - \row - \o \bold \\footnote \target footnote - \o \bold {The \\footnote command and the corresponding - \\endfootnote command delimit a footnote.} - - The footnote follows the standard conventions, rendered at the - bottom of the page. - - \warning This is preliminary funcionality. The - command is not fully implemented. - - For example: - - \code - / *! - In Qt 4 we have tried to simplify the constructors of - QObject/QWidget subclasses. This makes subclassing - easier, at the same time as it helps make the Qt - library more efficient. - - \footnote - Constructors no longer take a "const char *name" - parameter. If you want to specify a name for a QObject, - you must call QObject::setObjectName() after - construction. The object name is now a QString. - \endfootnote - - QWidget's WFlags data type has been split in two: - Qt::WindowFlags specifies low-level window flags (the - type of window and the frame style), whereas - Qt::WidgetAttribute specifies various higher-level - attributes about the widget (e.g., - WA_StaticContents). - * / - \endcode - - will be rendered as - - \quotation - In Qt 4 we have tried to simplify the constructors of - QObject/QWidget subclasses. This makes subclassing - easier, at the same time as it helps make the Qt - library more efficient. - - \footnote - Constructors no longer take a "const char *name" - parameter. If you want to specify a name for a QObject, - you must call QObject::setObjectName() after - construction. The object name is now a QString. - \endfootnote - - QWidget's WFlags data type has been split in two: - Qt::WindowFlags specifies low-level window flags (the - type of window and the frame style), whereas - Qt::WidgetAttribute specifies various higher-level - attributes about the widget (e.g., - WA_StaticContents). - \endquotation + \target abstract-command + \section1 \\abstract - \row - \o \bold \\tableofcontents \target tableofcontents - \o \bold {The \\tableofcontents command generates a - table displaying the titles of the current documentation - unit's parts, chapters, sections, etc.} - - The command accepts a single optional argument: - - \code - \tableofcontents sectionN - \endcode - - where \c sectionN is the deepest section to include (by - default all sections are included). - - For example, it the documentation unit's structure looks - something like this: - - \quotation - \raw HTML - <a name="Basic Qt"> - <h1>Basic Qt</h1> - </a> - <p>This is the first part.</p> - - <a name="Getting started"> - <h2>Getting Started</h2> - </a> - This is the first part's first chapter.</p> + The \\abstract and \\endabstract commands delimit a + document's abstract section. - <a name="Hello Qt"> - <h3>Hello Qt</h3> - </a> - <p>This is the first chapter's first section.</p> + The abstract section is rendered as an indented italicized + paragraph. - <a name="Making Connections"> - <h3>Making Connections</h3> - </a> - <p>This is the first chapter's second section.</p> + \warning The \bold{\\abstract} and \bold{\\endabstract} commands + have not been implemented. The abstract section is rendered as a + regular HTML paragraph. - <a name="Using the Reference Documentation"> - <h3>Using the Reference Documentation</h3> - </a> - <p>This is the first chapter's third section.</p> + \target quotation-command + \section1 \\quotation - <a name="Creating Dialogs"> - <h2>Creating Dialogs</h2> - </a> - <p>This is the first part's second chapter.</p> + The \\quotation and \\endquotation commands delimit a long quotation. - <a name="Subclassing QDialog"> - <h3>Subclassing QDialog</h3> - </a> - <p>This is the second chapter's first section.</p> + The text in the delimited block is surrounded by + \bold{<blockquote>} and \bold{</blockquote>} in the html output, + e.g.: - ... + \code + / *! + While the prospect of a significantly broader market is + good news for Firstlogic, the notion also posed some + challenges. Dave Dobson, director of technology for the La + Crosse, Wisconsin-based company, said: + + \quotation + As our solutions were being adopted into new + environments, we saw an escalating need for easier + integration with a wider range of enterprise + applications. + \endquotation + * / + \endcode - <a name="Intermediate Qt"> - <h1>Intermediate Qt</h1> - </a> - <p>This is the second part.</p> + The text in the \bold{\\quotation} block will appear in the generated HTML as: - <a name="Layout Management"> - <h2>Layout Management</h2> - </a> - <p>This is the second part's first chapter.</p> + \code + <blockquote> + <p>As our solutions were being adopted into new environments, + we saw an escalating need for easier integration with a wider + range of enterprise applications.</p> + </blockquote> + \endcode - <a name="Basic Layouts"> - <h3>Basic Layouts</h3> - </a> - <p>This is the first chapter's first section.</p> + The built-in style sheet for most browsers will render the + contents of the <blockquote> tag with left and right + indentations. The example above would be rendered as: - ... + \quotation + As our solutions were being adopted into new + environments, we saw an escalating need for easier + integration with a wider range of enterprise + applications. + \endquotation - \endraw - \endquotation + But you can redefine the \bold{<blockquote>} tag in your style.css file. - Then + This command replaces the old \\quote command. For more + information see the \l + {26-qdoc-commands-compatibility.html#quotation-versus-quote} + {compatibility} section. - \code - / *! - Contents: + \target footnote-command + \section1 \\footnote - \tableofcontents + The \\footnote and \\endfootnote commands delimit a footnote. - ... - * / - \endcode + The footnote is rendered at the bottom of the page. - will expand to + \warning The \bold{\\footnote} and \bold{\\endfootnote} commands + have not been implemented. The footnote is rendered as a regular + HTML paragraph. - \quotation - \raw HTML - <p>Contents:</p> + \target tableofcontents-command + \section1 \\tableofcontents - <ul> - <li><a href="#Basic Qt">Basic Qt</a></li> - <ul> - <li><a href="#Getting Started">Getting Started</a></li> - <ul> - <li><a href="#Hello Qt">Hello Qt</a></li> - <li><a href="#Making Connections"> - Making Connections</a></li> - <li><a href="#Using the Reference Documentation"> - Using the Reference Documentation</a></li> - </ul> - <li><a href="#Creating Dialogs">Creating Dialogs</a></li> - <ul> - <li><a href="#Subclassing QDialog"> - Subclassing QDialog</a></li> - </ul> - </ul> - <li><a href="#Intermediate Qt">Intermediate Qt</a></li> - <ul> - <li><a href="#Layout Management">Layout Management</a></li> - <ul> - <li><a href="#Basic Layouts">Basic Layouts</a></li> - </ul> - </ul> - </ul> + The \\tableofcontents command has been disabled because QDoc + now generates a table of contents automatically. - ... - \endraw - \endquotation + The automatically generated table of contents appears in the upper + righthand corner of the page. - Each table entry becomes a link to the corresponding part, - chapter or section. + \target brief-command + \section1 \\brief - \row - \o \bold \\brief \target brief - \o \bold {The \\brief command introduces a one-sentence - description of a class, namespace, header file, property - or variable.} + The \\brief command introduces a one-sentence description of a + class, namespace, header file, property or variable. - The brief text is used to introduce the documentation of - the associated object, and in lists generated using the \l - {generatelist}{\\generatelist} command. + The brief text is used to introduce the documentation of the + associated object, and in lists generated using the \l + {generatelist-command} {\\generatelist} command. - The \\brief command can be used in two significant - different ways: \l {brief class}{One for classes, - namespaces and header files}, and \l {brief property}{one - for properties and variables}. + The \\brief command can be used in two significant different ways: + \l {brief class} {One for classes, namespaces and header files}, + and \l {brief-property} {one for properties and variables}. - \target brief property + \target brief-property - When the \\brief command is used to describe a property or - a variable, the brief text must only be a sentence fragment - and start with "whether" (for boolean properties and - variables) or "the" (for any other property or variable). + When the \\brief command is used to describe a property or a + variable, the brief text must be a sentence fragment starting with + "whether" (for a boolean property or variable) or starting with + "the" (for any other property or variable). - For example the boolean QWidget::isWindow property: + For example the boolean QWidget::isWindow property: \code / *! @@ -3270,7 +3168,7 @@ * / \endcode - The latter will be rendered as + QDoc renders this as: \quotation \raw HTML @@ -3292,28 +3190,21 @@ \endlist See also \l - {QWidget::frameGeometry()}{frameGeometry()}, \l - {QWidget::rect()}{rect()}, ... + {QWidget::frameGeometry()} {frameGeometry()}, \l + {QWidget::rect()} {rect()}, ... \endquotation - \target brief class + \target brief class - When the \\brief command is used to describe a class, the - brief text should be a complete sentence and must start - like this: + When the \\brief command is used to describe a class, the brief + text should be a complete sentence and must start like this: \code The <classname> class is|provides|contains|specifies... \endcode - and likewise when the command is used for namespaces or - header files. - - \warning The brief statement is used as the first - paragraph of the detailed description. Do not repeat the - sentence. - - For example: + \warning The brief statement is used as the first paragraph of the + detailed description. Do not repeat the sentence. \code / *! @@ -3333,7 +3224,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation \raw HTML @@ -3342,7 +3233,7 @@ The PreviewWindow class is a custom widget displaying the names of its currently set window flags in a - read-only text editor. \l {preview window}{More...} + read-only text editor. \l {preview window} {More...} \raw HTML <h3>Properties</h3> @@ -3358,8 +3249,8 @@ \endraw \list - \o \l {constructor}{PreviewWindow}(QWidget *parent = 0) - \o void \l {function}{setWindowFlags}(Qt::WindowFlags flags) + \o \l {constructor} {PreviewWindow}(QWidget *parent = 0) + \o void \l {function} {setWindowFlags}(Qt::WindowFlags flags) \endlist \list @@ -3395,13 +3286,14 @@ <hr /> <h2>Detailed Description</h2> \endraw + The PreviewWindow class is a custom widget displaying the names of its currently set window flags in a read-only text editor. The PreviewWindow class inherits QWidget. The widget displays the names of its window flags set with the \l - {function}{setWindowFlags()} function. It is also + {function} {setWindowFlags()} function. It is also provided with a QPushButton that closes the window. ... @@ -3418,7 +3310,7 @@ <h3>PreviewWindow(QWidget *parent = 0)</h3> \endraw - Constructs a preview window widget with \i parent. + Constructs a preview window widget with \e parent. \target function \raw HTML @@ -3434,7 +3326,7 @@ the text in the widgets text editor. \endquotation - Using \\brief with a namespace can for example look like this: + Using \\brief in a \l{namespace-command}{\\namespace}: \code / *! @@ -3445,8 +3337,7 @@ * / \endcode - and finally using \\brief with a header file can look - something like this: + Using \\brief in a \l{headerfile-command}{\\headerfile}: \code / *! @@ -3460,107 +3351,83 @@ * / \endcode - See also \l{property}{\\property}, \l{class}{\\class}, - \l{namespace}{\\namespace} and \l{headerfile}{\\headerfile}. - - \row - \o \bold \\legalese \target legalese - \o \bold {The \\legalese command, and the corresponding \\endlegalese - command, delimit a licence agreement.} - - If the \\endlegalese command is omitted, QDoc will still - process the \\legalese command but considers the rest of - the documentation page as the license agreement. - - Ideally, the license documentation is located where the - licensed code is used. - - Later the documentation identified by the \\legalese - command can be accumulated into a list using the \l - {generatelist}{\\generatelist} command with the \c legalese - argument. This is useful to generate an overview of all the - licenses associated with the source code. - - For example: - - \code - \ * ! - ... - - On X11, Qt also supports drops via the Motif Drag \& - Drop Protocol. The implementation incorporates some - code that was originally written by Daniel Dardailler, - and adapted for Qt by Matt Koss \<koss@napri.sk\> and - Trolltech. Here is the original copyright notice: - - \legalese - \code - - Copyright 1996 Daniel Dardailler. - - Permission to use, copy, modify, distribute, and sell - this software for any purpose is hereby granted without - fee, provided that the above copyright notice appear in - all copies and that both that copyright notice and this - permission notice appear in supporting documentation, - and that the name of Daniel Dardailler not be used in - advertising or publicity pertaining to distribution of - the software without specific, written prior - permission. Daniel Dardailler makes no representations - about the suitability of this software for any - purpose. It is provided "as is" without express or - implied warranty. - - Modifications Copyright 1999 Matt Koss, under the same - license as above. - - \ endcode - \endlegalese - * / - \endcode - - will be rendered as - - \quotation - ... - - On X11, Qt also supports drops via the Motif Drag \& - Drop Protocol. The implementation incorporates some - code that was originally written by Daniel Dardailler, - and adapted for Qt by Matt Koss \<koss@napri.sk\> and - Trolltech. Here is the original copyright notice: + See also \l{property-command} {\\property}, \l{class-command} + {\\class}, \l{namespace-command} {\\namespace} and + \l{headerfile-command} {\\headerfile}. - \legalese - \code - - Copyright 1996 Daniel Dardailler. + \target legalese-command + \section1 \\legalese - Permission to use, copy, modify, distribute, and sell - this software for any purpose is hereby granted without - fee, provided that the above copyright notice appear in - all copies and that both that copyright notice and this - permission notice appear in supporting documentation, - and that the name of Daniel Dardailler not be used in - advertising or publicity pertaining to distribution of - the software without specific, written prior - permission. Daniel Dardailler makes no representations - about the suitability of this software for any - purpose. It is provided "as is" without express or - implied warranty. + The \\legalese and \\endlegalese commands delimit a licence agreement. - Modifications Copyright 1999 Matt Koss, under the same - license as above. + In the generated HTML, the delimited text is surrounded by a \bold + {<div class="LegaleseLeft">} and \bold {</div>} tags. - \endcode - \endlegalese - \endquotation + For example, here is a license agreement enclosed in \\legalese + and \\endlegalese: - \row - \o \bold \\warning \target warning - \o \bold {The \\warning command renders a "Warning:" prefix to - the command's argument.} + \code + / *! + \legalese + Copyright 1996 Daniel Dardailler. + + Permission to use, copy, modify, distribute, and sell this + software for any purpose is hereby granted without fee, + provided that the above copyright notice appear in all + copies and that both that copyright notice and this + permission notice appear in supporting documentation, and + that the name of Daniel Dardailler not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. Daniel + Dardailler makes no representations about the suitability of + this software for any purpose. It is provided "as is" + without express or implied warranty. + + Modifications Copyright 1999 Matt Koss, under the same + license as above. + \endlegalese + * / + \endcode - For example: + It will appear in the generated HTML as: + + \code + <div class="LegaleseLeft"> + <p>Copyright 1996 Daniel Dardailler.</p> + <p>Permission to use, copy, modify, distribute, and sell + this software for any purpose is hereby granted without fee, + provided that the above copyright notice appear in all + copies and that both that copyright notice and this + permission notice appear in supporting documentation, and + that the name of Daniel Dardailler not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. Daniel + Dardailler makes no representations about the suitability of + this software for any purpose. It is provided "as is" + without express or implied warranty.</p> + + <p>Modifications Copyright 1999 Matt Koss, under the same + license as above.</p> + </div> + \endcode + + If the \\endlegalese command is omitted, QDoc will process the + \\legalese command but considers the rest of the documentation + page as the license agreement. + + Ideally, the license text is located with the licensed code. + + Elsewhere, the documentation identified as \e{\\legalese} command + can be accumulated using \l {generatelist-command} {\\generatelist} + with \c {legalese-command} as the argument. This is useful for + generating an overview of the license agreements associated with + the source code. + + \target warning-command + \section1 \\warning + + The \\warning command prepends "Warning:" to the command's + argument, in bold font. \code / *! @@ -3573,7 +3440,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation Qt::HANDLE is a platform-specific handle type @@ -3583,50 +3450,31 @@ \warning Using this type is not portable. \endquotation - \endtable + */ /*! \page 12-0-qdoc-commands-miscellaneous.html - \previouspage Document Contents Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Topical Commands - - \title Miscellaneous Commands - - These commands provide miscellaneous functions - connected to the visual appearance of the documentation, and to the - process of generating the documentation. - - \section1 Alphabetical List + \previouspage Special Content + \contentspage Table of Contents + \nextpage The QDoc Configuration File - \l {12-0-qdoc-commands-miscellaneous.html#else}{\\else}, - \l {12-0-qdoc-commands-miscellaneous.html#endif}{\\endif}, - \l {12-0-qdoc-commands-miscellaneous.html#expire}{\\expire}, - \l {12-0-qdoc-commands-miscellaneous.html#generatelist}{\\generatelist}, - \l {12-0-qdoc-commands-miscellaneous.html#if}{\\if}, - \l {12-0-qdoc-commands-miscellaneous.html#include}{\\include}, - \l {12-0-qdoc-commands-miscellaneous.html#meta}{\\meta}, - \l {12-0-qdoc-commands-miscellaneous.html#omit}{\\omit}, - \l {12-0-qdoc-commands-miscellaneous.html#raw}{\\raw}, - \l {12-0-qdoc-commands-miscellaneous.html#raw}{\\unicode} + \title Miscellaneous - \section1 Command Descriptions + These commands provide miscellaneous functions connected to the + visual appearance of the documentation, and to the process of + generating the documentation. - \table - \header - \o Command - \o Description + \target expire-command + \section1 \\expire - \row - \o \bold \\expire \target expire - \o \bold {The \\expire command allows you to define an expiration - date for your documentation.} + The \\expire command allows you to define an expiration + date for your documentation. - When using the \\expire command, QDoc will emit a warning - when the current date is larger than the specified - date. The command accepts one argument; the argument's - format is yyyy-mm-dd. For example: + When using the \\expire command, QDoc will emit a warning when the + current date is larger than the specified date. The command + accepts one argument; the argument's format is yyyy-mm-dd. For + example: \code / *! @@ -3645,23 +3493,24 @@ * / \endcode - If you run QDoc on 4 July 2005, it will emit the warning + If you run QDoc on 4 July 2005, it will emit the warning \quotation porting.qdoc:6: Documentation expired 185 days ago \endquotation - \row - \o \bold \\generatelist \target generatelist - \o \bold {The \\generatelist command expands to a list of - various documentation or links to documentation.} - For example in the Qt Reference Documentation: + \target generatelist-command + \section1 \\generatelist + + The \\generatelist command expands to a list of various + documentation or links to documentation. Below is an example from + the Qt Reference Documentation: \code / *! \page classes.html - \title All Qt Classes (main index) + \title All Classes For a shorter list that only includes the most frequently used classes, see \l{Qt's Main Classes}. For @@ -3672,434 +3521,308 @@ * / \endcode - is used to generate \l {All Qt Classes (main index)}. - - The command accepts the following arguments: - - \target table example - - \list - \o \c annotatedclasses - - The \c annotatedclasses argument provides a table - containing the names of all the classes, and a - description of each class. Each class name is a link to - the class's reference documentation. - - For example: - - \quotation - \raw HTML - <table align="center" cellpadding="2" - cellspacing="1" border="0"> - - <tr valign="top" bgcolor="#d0d0d0"> - <td> - <a href="http://qt.nokia.com/doc/4.0/qdial.html"> - QDial</a> - </td> - <td>Rounded range control (like a speedometer - or potentiometer)</td> - </tr> - - <tr valign="top" bgcolor="#d0d0d0"> - <td> - <a href="http://qt.nokia.com/doc/4.0/qdialog.html"> - QDialog</a> - </td> - <td>The base class of dialog windows</td> - </tr> - - <tr valign="top" bgcolor="#d0d0d0"> - <td> - <a href="http://qt.nokia.com/doc/4.0/qdir.html"> - QDir</a> - </td> - <td>Access to directory structures and their - contents</td> - </tr> - </table> - \endraw - \endquotation - - A class is identified within the documentation by the - the \l {class}{\\class} command, and the descriptions - are based on the argument of the \l {brief}{\\brief} - commands in the class documentation. - - \target list example + This generates the \l {All Classes} page. The command accepts the + following arguments: - \o \c classes - - The \c classes argument provides a complete alphabetical - list of the classes. Each class name is a link to the - class's reference documentation. - - For example: - - \quotation - \raw HTML - <p><table width="100%"> + \target table example + \section2 \c annotatedclasses - <tr> - <td align="right"><b>A </b></td> - <td><a href="http://qt.nokia.com/doc/4.0/qabstractbutton.html">QAbstractButton</a></td> + The \c annotatedclasses argument provides a table containing the + names of all the classes, and a description of each class. Each + class name is a link to the class's reference documentation. For + example: - <td align="right"></td> - <td><a href="http://qt.nokia.com/doc/4.0/qabstractextensionmanager.html">QAbstractExtensionManager</a></td> - - <td align="right"></td> - <td><a href="http://qt.nokia.com/doc/4.0/qabstractitemmodel.html">QAbstractItemModel</a></td> - </tr> - - <tr> - <td align="right"></td> - <td><a href="http://qt.nokia.com/doc/4.0/qabstracteventdispatcher.html">QAbstractEventDispatcher</a></td> - - <td align="right"></td> - <td><a href="http://qt.nokia.com/doc/4.0/qabstractformbuilder.html">QAbstractFormBuilder</a></td> - - <td align="right"></td> - <td><a href="http://qt.nokia.com/doc/4.0/qabstractitemview.html">QAbstractItemView</a></td> - </tr> - - <tr> - <td align="right"></td> - <td><a href="http://qt.nokia.com/doc/4.0/qabstractextensionfactory.html">QAbstractExtensionFactory</a></td> - - <td align="right"></td> - <td><a href="http://qt.nokia.com/doc/4.0/qabstractitemdelegate.html">QAbstractItemDelegate</a></td> - - <td align="right"></td> - <td><a href="http://qt.nokia.com/doc/4.0/qabstractlistmodel.html">QAbstractListModel</a></td> - </tr> - </table></p> - \endraw - \endquotation - - A class is identified within the documentation by the - the \l {class}{\\class} command. - - \o \c classesbymodule + \table + \row + \o QDial + \o Rounded range control (like a speedometer or potentiometer) + \row + \o QDialog + \o The base class of dialog windows + \row + \o QDir + \o Access to directory structures and their contents + \endtable - This particular argument requests an additional argument, - i.e. a specification of the module. + A C++ class is documented with the \l {class-command} {\\class} + command. The annotation for the class is taken from the argument + of the class comment's \l {brief-command} {\\brief} command. - For example: + \target list example + \section2 \c classes - \code - / *! - \page qtgui.html - \contentspage Qt Classes by Module - \previouspage QtCore Classes - \nextpage QtNetwork Classes + The \c classes argument provides a complete alphabetical list of + the classes. Each class name is a link to the class's reference + documentation. This command is uded to generate the \l + {classes.html} {All Classes} page this way: - \title QtGui Classes + \code + / *! + \page classes.html + \title All Classes + \ingroup classlists - \keyword QtGui + \brief If you know the name of the class you want, find it here. - \generatelist {classesbymodule QtGui} - * / - \endcode + This is a list of all Qt classes. For a list of the classes + provided for compatibility with Qt3, see \l{Qt3 Support + Classes}. For classes that have been deprecated, see the + \l{Obsolete Classes} list. - Together, these arguments provide a table containing the - classes considered members of the specified module, - accompanied with a brief description. Each class name is - a link to the class's reference documentation. + \generatelist classes + * / + \endcode - The generated table is rendered similarily to the one - generated when using the \l {table example}{\c - annotatedclasses} argument. + A C++ class is documented with the \l {class-command} {\\class} + command. - For the basic classes in Qt, a class's module is - determined by its location, i.e. its directory. However, - for extensions, like ActiveQt and Qt Designer, a class - is related to a module with the \l - {inmodule}{\\inmodule} command. + \section2 \c classesbymodule - \o \c classesbyedition + When this argument is used, a second argument is required, which + specifies the module whose classes are to be listed. QDoc + generates a table containing those classes. Each class is listed + with the text of its \l{brief-command} {\\brief} command. - This particular argument requests an additional argument, - i.e. a specification of the edition. + This command is used to generate the \l {phonon-module.html} + {Phonon Module} page this way. - For example: + \code + / *! + \page phonon-module.html + \module Phonon + \title Phonon Module + \ingroup modules - \code - / *! - \page console-edition-classes.html - \title Qt Console Edition Classes + \brief The Phonon module contains namespaces and classes for multimedia functionality. - \generatelist{classesbyedition Console} - * / - \endcode + \generatelist{classesbymodule Phonon} - Together, these arguments provide a table containing the - classes considered members of the specified edition, - accompanied with a brief description. Each class name is - a link to the class's reference documentation. + ... - The edition a given class can be found in is determined by - the module it belongs to. + * / + \endcode - \o \c compatclasses + Each class that is a member of the specified module must be marked + with the \l {inmodule-command} {\\inmodule} command in its \\class + comment. - The \c compatclasses argument provides a complete and - alphabetical list of the support classes. A support - class is identified within the documentation by the \l - {compat}{\\compat} command. Each class name is a link to - the class's reference documentation. The list is - rendered similarily to the list generated by the \l - {list example}{\c classes} argument. + \section2 \c compatclasses - \warning The \c classesbymodule argument will at some - point replace the this argument. + The \c compatclasses argument generates a list in alphabetical + order of the support classes. It is normally used only to + generate the \l {compatclasses.html} {Qt3 Support Classes} page + this way: - \o \c functionindex + \code + / *! + \page compatclasses.html + \title Qt3 Support Classes + \ingroup classlists - The \c functionindex argument provides a complete - alphabetical list of all the documented member - functions. + \brief These classes ease the porting of code from Qt 3 to Qt 4. - For example: + These are the classes that Qt provides for compatibility with Qt + 3. Most of these are provided by the Qt3Support module. - \quotation - \raw HTML - <p><center><font size="+1"><b><a href="#a">A</a> <a href="#b">B</a> <a href="#c">C</a> <a href="#d">D</a> <a href="#e">E</a> <a href="#f">F</a> <a href="#g">G</a> <a href="#h">H</a> <a href="#i">I</a> <a href="#j">J</a> <a href="#k">K</a> <a href="#l">L</a> <a href="#m">M</a> <a href="#n">N</a> <a href="#o">O</a> <a href="#p">P</a> <a href="#q">Q</a> <a href="#r">R</a> <a href="#s">S</a> <a href="#t">T</a> <a href="#u">U</a> <a href="#v">V</a> <a href="#w">W</a> <a href="#x">X</a> <a href="#y">Y</a> <a href="#z">Z</a> </b></font></center></p> + \generatelist compatclasses + * / + \endcode - <p>DTDHandler: <a href="http://qt.nokia.com/doc/4.0/qxmlreader.html#DTDHandler">QXmlReader</a></p> + A support class is identified in the \\class comment with the \l + {compat-command} {\\compat} command. - <p>QAXCLASS: <a href="http://qt.nokia.com/doc/4.0/qaxfactory.html#QAXCLASS">global</a></p> + \section2 \c functionindex - <p>QAXFACTORY_BEGIN: <a href="http://qt.nokia.com/doc/4.0/qaxfactory.html#QAXFACTORY_BEGIN">global</a></p> + The \c functionindex argument provides a complete alphabetical + list of all the documented member functions. It is normally used + only to generate the \l {functions.html} {Qt function index} page + this way: - <p>QAXFACTORY_DEFAULT: <a href="http://qt.nokia.com/doc/4.0/qaxfactory.html#QAXFACTORY_DEFAULT">global</a></p> + \code + / *! + \page functions.html + \title All Functions + \ingroup funclists - <p>QAXFACTORY_END: <a href="http://qt.nokia.com/doc/4.0/qaxfactory.html#QAXFACTORY_END">global</a></p> + \brief All documented Qt functions listed alphabetically with a + link to where each one is declared. - \endraw + This is the list of all documented member functions and global + functions in the Qt API. Each function has a link to the + class or header file where it is declared and documented. - ... - \endquotation - - \o \c legalese - - The \c legalese argument provides a complete list of all - the licenses. The licenses are identified within the - documentation using the \l {legalese}{\\legalese} - command. - - For example: - - \quotation - \raw HTML - <hr /> - <p> - Copyright (c) 1989 The Regents of the - University of California. All rights reserved. - </p> - - <p> - Redistribution and use in source and binary - forms are permitted provided that the above - copyright notice and this paragraph are - duplicated in all such forms and that any - documentation, advertising materials, and other - materials related to such distribution and use - acknowledge that the software was developed by - the University of California, Berkeley... - </p> - - <ul> - <li> - <a href="http://qt.nokia.com/doc/4.0/qdate.html#weekNumber">QDate::weekNumber()</a> - </li> - </ul> - - <hr /> - <p> - Copyright (c) 1991 by AT&T. - </p> - - <p> - Permission to use, copy, modify, and distribute - this software for any purpose without fee is - hereby granted, provided that this entire notice - is included in all copies of any software which - is or includes a copy or modification of this - software and in all copies of the supporting - documentation for such software... - </p> - - <ul> - <li> - <a href="http://qt.nokia.com/doc/4.0/qlocale.html">QLocale</a> - </li> - </ul> - <hr /> - \endraw - ... - \endquotation + \generatelist functionindex + * / + \endcode - \o \c mainclasses + \section2 \c legalese - The \c mainclasses argument provides a complete - alphabetical list of the main classes. Each class name - is a link to the class's reference documentation. A - class is related to the group of main classes by using - the \l {mainclass}{\\mainclass} command. + The \c legalese argument tells QDoc to generate a complete list of + licenses in the documentation. Each license is identified using + the \l {legalese-command} {\\legalese} command. This command is + used to generate the \l {licenses.html} {Qt license information} + page this way: - The list is rendered similarily to the list generated by - the \l {list example}{\c classes} argument. + \code + / *! + \page licenses.html + \title Other Licenses Used in Qt + \ingroup licensing + \brief Information about other licenses used for Qt components and third-party code. + + Qt contains some code that is not provided under the + \l{GNU General Public License (GPL)}, + \l{GNU Lesser General Public License (LGPL)} or the + \l{Qt Commercial Edition}{Qt Commercial License Agreement}, but rather under + specific licenses from the original authors. Some pieces of code were developed + by Nokia and others originated from third parties. + This page lists the licenses used, names the authors, and links + to the places where it is used. + + Nokia gratefully acknowledges these and other contributions + to Qt. We recommend that programs that use Qt also acknowledge + these contributions, and quote these license statements in an + appendix to the documentation. + + See also: \l{Licenses for Fonts Used in Qt for Embedded Linux} + + \generatelist legalese + * / + \endcode - \o \c overviews + \section2 \c mainclasses - The \c overviews argument provides a complete - alphabetical overview of the documentation. Each list - entry is a link to the respective documentation page. + The \c mainclasses argument tells QDoc to generate an alphabetical + list of the main classes. A class is marked as a main class by + including a \l {mainclass-command} {\\mainclass} command in the + \\class comment. - The list includes pages declared using commands like \l - {page}{\\page} and \l {group}{\\group}. The list omits - examples and classes, and only lists the first page of - documentation that contains two or more pages using - commands like \l {nextpage}{\\nextpage}. + \note The Qt documentation no longer includes a main classes page, + but you can generate one for your main classes if you want it. - For example: + \section2 \c overviews - \quotation - \raw HTML - <ul> + The \c overviews argument is used to tell QDoc to generate a list + by concatenating the contents of all the \l {group-command} + {\\group} pages. Qt uses it to generate the \l {overviews.html} + {overviews} page this way: - <li> - <a href="http://qt.nokia.com/doc/4.0/qtalgorithms.html"> - <QtAlgorithms> - Generic Algorithms - </a> - </li> + \code + / *! + \page overviews.html - <li> - <a href="http://qt.nokia.com/doc/4.0/qtglobal.html"> - <QtGlobal> - Global Qt Declarations - </a> - </li> + \title All Overviews and HOWTOs - <li> - <a href="http://qt.nokia.com/doc/4.0/qaxserver-demo-simple.html"> - A standard ActiveX and the "simple" ActiveQt widget - </a> - </li> + \generatelist overviews + * / + \endcode - <li> - <a href="http://qt.nokia.com/doc/4.0/aboutqt.html"> - About Qt - </a> - </li> + \section2 \c related - <li> - <a href="http://qt.nokia.com/doc/4.0/trolltech.html"> - About Trolltech - </a> - </li> + The \c related argument is used in combination with the \l + {group-command} {\\group} and \l {ingroup-command} {\\ingroup} + commands to list all the overviews related to a specified + group. For example, the page for the \l {Programming with Qt} + {Programming with Qt} page is generated this way: - <li> - <a href="http://qt.nokia.com/doc/4.0/abstractwidgets.html"> - Abstract Widget Classes - </a> - </li> + \code + / *! + \group qt-basic-concepts + \title Programming with Qt - <li> - <a href="http://qt.nokia.com/doc/4.0/accessibility.html"> - Accessibility Classes - </a> - </li> - ... - </ul> - \endraw - \endquotation + \brief The basic architecture of the Qt cross-platform application and UI framework. - \o \c related + Qt is a cross-platform application and UI framework for + writing web-enabled applications for desktop, mobile, and + embedded operating systems. This page contains links to + articles and overviews explaining key components and + techniuqes used in Qt development. - The \c related argument is used in combination with the - \l {group}{\\group} command to list all the overviews - related to the given group. Each list entry is a link to - the respective documentation page. + \generatelist {related} + * / + \endcode - \o \c relatedinline + Each page listed on this group page contains the command: - The \c related argument is used in combination with the - \l {group}{\\group} command to collect all documentation - related to the given group. The various documentation - snippets are copied directly into the group page. + \code + \ingroup qt-basic-concepts + \endcode - \o \c service + \section2 \c service - The \c service argument provides a complete alphabetical - list of the services. Each service name is a link to the - service's reference documentation. + The \c service argument tells QDoc to generate an alphabetical + list of the services. Each service name is a link to the service's + reference documentation. - A service is identified within the documentation by the - \l {service}{\\service} command. + A service is identified with the \l {service-command} {\\service} + command. - \endlist + \note This command and the \l {service-command} {\\service} + command are not used in the Qt documentation. + \target if-command + \section1 \\if - \row - \o \bold \\if \target if - \o \bold {The \\if command and the corresponding \\endif command - enclose parts of a QDoc comment that only will be included if - the condition specified by the command's argument is true.} + The \\if command and the corresponding \\endif command + enclose parts of a QDoc comment that only will be included if + the condition specified by the command's argument is true. - The command reads the rest of the line and parses it as an - C++ #if statement. For example: + The command reads the rest of the line and parses it as an C++ #if + statement. \code / *! \if defined(opensourceedition) \bold{Note:} This edition is for the development of - \l{Qt Open Source Edition}{Free and Open Source} + \l{Qt Open Source Edition} {Free and Open Source} software only; see \l{Qt Commercial Editions}. \endif * / \endcode - This QDoc comment will only be rendered if the \c - opensourceedition preprocessor symbol is defined, and - specified in the \l {definesvariable}{defines} variable in - the configuration file to make QDoc process - the code within #ifdef and #endif: + This QDoc comment will only be rendered if the \c + opensourceedition preprocessor symbol is defined, and specified in + the \l {defines-variable} {defines} variable in the configuration + file to make QDoc process the code within #ifdef and #endif: \code defines = opensourceedition \endcode - You can also define the preprocessor symbol manually on the - command line. For more information see the documentation of - the \l {definesvariable}{defines} variable. + You can also define the preprocessor symbol manually on the + command line. For more information see the documentation of the \l + {defines-variable} {defines} variable. - See also \l{endif}{\\endif}, \l{else}{\\else}, \l - {definesvariable}{defines} and \l falsehoods. + See also \l{endif-command} {\\endif}, \l{else-command} {\\else}, + \l {defines-variable} {defines} and \l {falsehoods-variable} + {falsehoods}. - \row - \o \bold \\endif \target endif - \o \bold {The \\endif command and the corresponding \\if command - enclose parts of a QDoc comment that will be included if - the condition specified by the \l {if}{\\if} command's - argument is true.} + \target endif-command + \section1 \\endif - For more information, see the documentation of the \l - {if}{\\if} command. + The \\endif command and the corresponding \\if command + enclose parts of a QDoc comment that will be included if + the condition specified by the \l {if-command} {\\if} command's + argument is true. - See also \l{if}{\\if}, \l{else}{\\else}, \l - {definesvariable}{defines} and \l falsehoods. + For more information, see the documentation of the \l {if-command} + {\\if} command. - \row - \o \bold \\else \target else - \o \bold {The \\else command specifies an alternative if the - condition in the \l {if}{\\if} command is false.} + See also \l{if-command} {\\if}, \l{else-command} {\\else}, \l + {defines-variable} {defines} and \l {falsehoods-variable} + {falsehoods}. + + \target else-command + \section1 \\else - The \\else command can only be used within \l - {if}{\\if...\\endif} commands, but is useful when there is - only two alternatives. For example: + The \\else command specifies an alternative if the + condition in the \l {if-command} {\\if} command is false. + + The \\else command can only be used within \l {if-command} + {\\if...\\endif} commands, but is useful when there is only two + alternatives. \code / *! @@ -4134,8 +3857,8 @@ * / \endcode - If the \c QT3_SUPPORT is defined, the comment will be rendered - as + If the \c QT3_SUPPORT is defined, the comment will be rendered + like this: \quotation The Qt 3 support library is provided to keep old source @@ -4146,8 +3869,8 @@ API to cohabit with the new one. \endquotation - If \c QT3_SUPPORT isn't defined but \c QT3_SUPPORT_WARNINGS - is, the comment will be rendered as + If \c QT3_SUPPORT is not defined but \c QT3_SUPPORT_WARNINGS is + defined, the comment will be rendered like this: \quotation The Qt 3 support library is provided to keep old source @@ -4186,32 +3909,31 @@ GCC 3.2+ and MSVC 7.) \endquotation - See also \l{if}{\\if}, \l{endif}{\\endif}, \l - {definesvariable}{defines} and \l falsehoods. + See also \l{if-command} {\\if}, \l{endif-command} {\\endif}, \l + {defines-variable} {defines} and \l {falsehoods-variable} + {falsehoods}. - \row - \o \bold \\include \target include - \o \bold {The \\include command expands to the contents of the - file specified by the command's argument.} + \target include-command + \section1 \\include - \warning This is preliminary functionality. For more - information, see the \l - {26-qdoc-commands-compatibility.html#include-versus-input} - {compatibility} section. + The \\include command expands to the contents of the + file specified by the command's argument. - The command takes a file name as an argument, and is - useful when some piece of the documentation is used - repeatedly: Move the repetetive text into a separate file, - and use the \\include command whenever you want to insert - the separate documentation. + \warning This is preliminary functionality. For more information, + see the \l + {26-qdoc-commands-compatibility.html#include-versus-input} + {compatibility} section. - The contents of such a file should follow QDoc syntax, - excluding the enclosing \c{/}\c{*!} ... \c{*}\c{/} marks. - To ensure that QDoc won't attempt to read the file as a - stand-alone piece of documentation, we recommend that you - use the \c .qdocinc extension. + The command takes a file name as an argument, and is useful when + some piece of the documentation is used repeatedly: Move the + repetetive text into a separate file, and use the \\include + command whenever you want to insert the separate documentation. - For example: + The contents of such a file should follow QDoc syntax, excluding + the enclosing \c{/}\c{*!} ... \c{*}\c{/} marks. To ensure that + QDoc won't attempt to read the file as a stand-alone piece of + documentation, we recommend that you use the \c .qdocinc + extension. \code / *! @@ -4224,33 +3946,31 @@ * / \endcode - will be rendered as + QDoc renders this as: \quotation \raw HTML <h1>Core Features</h1> \endraw - \include examples/signalandslots.qdocinc - \include examples/objectmodel.qdocinc - \include examples/layoutmanagement.qdocinc + \input examples/signalandslots.qdocinc + \input examples/objectmodel.qdocinc + \input examples/layoutmanagement.qdocinc \endquotation - Here is the actual \c .qdocinc files: \l - signalandslots.qdocinc, \l objectmodel.qdocinc, \l - layoutmanagement.qdocinc + Here is the actual \c .qdocinc files: \l signalandslots.qdocinc, + \l objectmodel.qdocinc, \l layoutmanagement.qdocinc - \row - \o \bold \\meta \target meta - \o \bold {The \\meta command is the QDoc equivalent to the HTML - \c meta tag.} + \target meta-command + \section1 \\meta - The command accepts two arguments: The first argument (the - following word) is equivalent to the HTML meta tag's \i - name variable, and the second argument (the rest of the - line) is equivalent to the tag's \i contents variable. + The \\meta command is the QDoc equivalent to the HTML + \c meta tag. - For example: + The command accepts two arguments: The first argument (the + following word) is equivalent to the HTML meta tag's \e name + variable, and the second argument (the rest of the line) is + equivalent to the tag's \e contents variable. \code / *! @@ -4274,7 +3994,7 @@ * / \endcode - will be included in the generated HTML page as + QDoc renders this as: \code <head> @@ -4284,13 +4004,12 @@ </head> \endcode - \row - \o \bold \\omit \target omit - \o \bold {The \\omit command and the correspondning \\endomit - command delimit parts of the documentation that - you want QDoc to skip.} + \target omit-command + \section1 \\omit - For example: + The \\omit command and the correspondning \\endomit command + delimit parts of the documentation that you want QDoc to skip. For + example: \code / *! @@ -4314,7 +4033,7 @@ * / \endcode - will be rendered as + QDoc renders this as: \raw HTML <table align="center" cellpadding="2" @@ -4333,94 +4052,115 @@ </table> \endraw + \target raw-command + \section1 \\raw \span {class="newStuff"} {(avoid)} - \row - \o \bold \\raw \target raw - \o \bold {The \\raw command and the corresponding - \\endraw command delimit a block of raw mark-up language code.} + The \\raw command and the corresponding + \\endraw command delimit a block of raw mark-up language code. - The command takes an argument specifying the code's format; - currently the only supported format is HTML. + \note Avoid using this command if possible, because it generates + DITA XML code that causes problems. If you are trying to generate + special table or list behavior, try to get the behavior you want + using the \l {span-command} {\\span} and \l {div-command} {\\div} + commands in your \l {table-command} {\\table} or \l {list-command} + {\\list}. + + The command takes an argument specifying the code's format; + currently the only supported format is HTML. - The \\raw command is useful if you want some special HTML - effects in your documentation. For example: + The \\raw command is useful if you want some special HTML effects + in your documentation. \code / *! - Qt has some predefined QColor objects. For example: + Qt has some predefined QColor objects. \raw HTML <style type="text/css" id="colorstyles"> - #blue { background-color: #0000ff; color: #ffffff } - #darkBlue { background-color: #000080; color: #ffffff } - #cyan { background-color: #00ffff; color: #000000 } + #color-blue { background-color: #0000ff; color: #ffffff } + #color-darkBlue { background-color: #000080; color: #ffffff } + #color-cyan { background-color: #00ffff; color: #000000 } </style> <p> - <tt id="blue">Blue(#0000ff)</tt>, - <tt id="darkBlue">dark blue(#000080)</tt> and - <tt id="cyan">cyan(#00ffff)</tt>. + <tt id="color-blue">Blue(#0000ff)</tt>, + <tt id="color-darkBlue">dark blue(#000080)</tt> and + <tt id="color-cyan">cyan(#00ffff)</tt>. + </p> \endraw * / \endcode - will be rendered as + QDoc renders this as: \quotation - Qt has some predefined QColor objects. For example: + Qt has some predefined QColor objects. \raw HTML <style type="text/css" id="colorstyles"> - #blue { background-color: #0000ff; color: #ffffff } - #darkBlue { background-color: #000080; color: #ffffff } - #cyan { background-color: #00ffff; color: #000000 } + #color-blue { background-color: #0000ff; color: #ffffff } + #color-darkBlue { background-color: #000080; color: #ffffff } + #color-cyan { background-color: #00ffff; color: #000000 } </style> <p> - <tt id="blue">Blue(#0000ff)</tt>, - <tt id="darkBlue">dark blue(#000080)</tt> and - <tt id="cyan">cyan(#00ffff)</tt>. + <tt id="color-blue">Blue(#0000ff)</tt>, + <tt id="color-darkBlue">dark blue(#000080)</tt> and + <tt id="color-cyan">cyan(#00ffff)</tt>. + </p> \endraw \endquotation - \row - \o \bold \\unicode \target unicode - \o \bold {The \\unicode command allows you to insert an - arbitrary Unicode character in the document.} + \note But you can achieve the exact same thing using qdoc + commands. In this case, all you have to do is include the color + styles in your style.css file. Then you can write: + + \code + \tt {\span {id="color-blue"} {Blue(#0000ff)}}, + \tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and + \tt {\span {id="color-cyan"} {cyan(#00ffff)}}. + \endcode - The command takes an argument specifying the character as - an integer. By default, base 10 is assumed, unless a '0x' - or '0' prefix is specified (for base 16 and 8, - respectively). For example: + ...which is rendered again as: + + \tt {\span {id="color-blue"} {Blue(#0000ff)}}, + \tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and + \tt {\span {id="color-cyan"} {cyan(#00ffff)}}. + + \target unicode-command + \section1 \\unicode + + The \\unicode command allows you to insert an arbitrary Unicode + character in the document. + + The command takes an argument specifying the character as an + integer. By default, base 10 is assumed, unless a '0x' or '0' + prefix is specified (for base 16 and 8, respectively). For + example: \code O G\unicode{0xEA}nio e as Rosas \unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour - \unicode 0x3A3 \i{a}\sub{\i{i}} + \unicode 0x3A3 \e{a}\sub{\e{i}} \endcode - will be rendered as + QDoc renders this as: \quotation O G\unicode{0xEA}nio e as Rosas \unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour - \unicode 0x3A3 \i{a}\sub{\i{i}} + \unicode 0x3A3 \e{a}\sub{\e{i}} \endquotation - - The \\raw command follows the same conventions as the \l - {i}{\\i} command for \l {argument}{punctuation and use of - braces} for the argument. - \endtable */ /*! \page 12-1-signalandslots.html - \previouspage Miscellaneous Commands - \contentspage QDoc Manual - Table of Contents + \previouspage Miscellaneous + \contentspage Table of Contents \title signalandslots.qdocinc @@ -4429,8 +4169,8 @@ /*! \page 12-2-objectmodel.html - \previouspage Miscellaneous Commands - \contentspage QDoc Manual - Table of Contents + \previouspage Miscellaneous + \contentspage Table of Contents \title objectmodel.qdocinc @@ -4439,8 +4179,8 @@ /*! \page 12-3-layoutmanagement.html - \previouspage Miscellaneous Commands - \contentspage QDoc Manual - Table of Contents + \previouspage Miscellaneous + \contentspage Table of Contents \title layoutmanagement.qdocinc @@ -4448,71 +4188,54 @@ */ /*! - \page 13-qdoc-commands-topical.html - \previouspage Miscellaneous Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Contextual Commands - - \title Topical Commands - - The topical commands tell QDoc what is being documented - (i.e. existing units like classes, functions and examples), and - some of the commands allows you to create extra pages. - - \section1 Alphabetical List - - \l {13-qdoc-commands-topical.html#class}{\\class}, - \l {13-qdoc-commands-topical.html#enum}{\\enum}, - \l {13-qdoc-commands-topical.html#example-command}{\\example}, - \l {13-qdoc-commands-topical.html#externalpage}{\\externalpage}, - \l {13-qdoc-commands-topical.html#fn}{\\fn}, - \l {13-qdoc-commands-topical.html#group}{\\group}, - \l {13-qdoc-commands-topical.html#headerfile}{\\headerfile}, - \l {13-qdoc-commands-topical.html#macro}{\\macro}, - \l {13-qdoc-commands-topical.html#module}{\\module}, - \l {13-qdoc-commands-topical.html#namespace}{\\namespace}, - \l {13-qdoc-commands-topical.html#page}{\\page}, - \l {13-qdoc-commands-topical.html#property}{\\property}, - \l {13-qdoc-commands-topical.html#service}{\\service}, - \l {13-qdoc-commands-topical.html#typedef}{\\typedef}, - \l {13-qdoc-commands-topical.html#variable}{\\variable}, + \page 13-qdoc-commands-topics.html + \previouspage Command Index + \contentspage Table of Contents + \nextpage Context Commands - \section1 General Description + \title Topic Commands + + A topic command tells QDoc which source code element is being + documented. Some topic commands allow you to create documentation + pages that aren't tied to any underlying source code element. - When QDoc is processing a comment, it will try to connect the - documentation to the source code. For that reason it will first - look for the topical commands. If there is no such command, it - will try to tie the documentation to the immediately following - code. If there is no topical command, and the documentation cannot - be tied to following code, the documentation is simply lost. + When QDoc processes a QDoc comment, it tries to connect the + comment to an element in the source code by first looking for a + topic command that names the source code element. If there is no + topic command, QDoc tries to connect the comment to the source + code element that immediately follows the comment. If it can't do + either of these and if there is no topic command that indicates + the comment does not have an underlying source code element (e.g. + \l{page-command} {\\page}), then the comment is discarded. - \target topical argument + \target topic argument - The documented unit's name is passed as the unique argument for - all the topical commands. The argument's naming convention is the - documented unit's complete name. For example: + The name of the thing being documented is the unique argument for + each topic command. The naming convention is to use the complete + name. \code \enum QComboBox::InsertPolicy \endcode - Functions is a special case, the argument's naming convention for - the \l {fn}{\\fn} command is that of the function's definition - outside the class definition. For example: + The \l {fn-command} {\\fn} command is a special case. For the \l + {fn-command} {\\fn} command, use the function's signature + including the class qualifier. \code - \fn void PreviewWindow::setWindowFlags() + \fn void QGraphicsWidget::setWindowFlags(Qt::WindowFlags wFlags) \endcode - A topical command can appear anywhere in a comment, but must stand - alone on its own line. If the argument spans several lines, make - sure that each line (except the last one) is ended with a + A topic command can appear anywhere in a comment but must stand + alone on its own line. Best practice is to put the topic commend + at the top of the comment. If the argument spans several lines, + make sure that each line (except the last one) is ended with a backslash. In addition QDoc counts parentheses, which means that if it encounters a '(' it considers everything until the closing ')' as its argument. - If a topical command is repeated with different arguments, the - same documentation will appear for both the units. For example: + If a topic command is repeated with different arguments, the + same documentation will appear for both the units. \code / *! @@ -4532,232 +4255,224 @@ ControllerWindow::setWindowFlags() functions will get the same documentation. - \section1 Command Descriptions - - \table - \header - \o Command - \o Description - - \row - \o \bold \\class \target class - \o \bold {The \\class command tells QDoc that a class is - part of the public API, and lets you enter a detailed - description.} - - The command follows \l {topical argument}{the general - topical command convention} for the argument, and supports - nested classes, for example: + \target class-command + \section1 \\class - \code - / *! - \class QMap::iterator + The \\class command is for documenting a C++ class. The argument + is the complete name of the class. The command tells QDoc that a + class is part of the public API, and lets you enter a detailed + description. - \brief The QMap::iterator class provides an STL-style - non-const iterator for QMap and QMultiMap. + \code + / *! + \class QMap::iterator - QMap features both \l{STL-style iterators} and - \l{Java-style iterators}. The STL-style iterators ... - * / - \endcode + \brief The QMap::iterator class provides an STL-style + non-const iterator for QMap and QMultiMap. - The generated HTML documentation for the specified class is - put in \c <lower-case>classname.html. For example, the - documentation for the \c PreviewWindow class is located in - \c previewwindow.html. + QMap features both \l{STL-style iterators} and + \l{Java-style iterators}. The STL-style iterators ... + * / + \endcode - \target framework + The HTML documentation for the named class is written to a + \c{.html} file named from the class name, in lower case, and with + the double colon qulifier(s) replaced with '-'. For example, the + documentation for the \c QMap::Iterator class is written to \c + qmap-iterator.html. - In addition to render the detailed description, the \\class - comand will generate the documentation framework, i.e. a - list of the class's types, properties, functions, signals - and slots with empty documentation. + \target framework - The command is typically accompanied with a \l - {brief}{\\brief} command, a \l {mainclass}{\\mainclass} - command, an \l {ingroup}{\\ingroup} command and a \l - {sa}{\\sa} command. For example: + The file contains the class description from the \\class comment, + plus the documentation generated from QDoc comments for all the + class members, i.e. a list of the class's types, properties, + functions, signals, and slots. - \code - / *! - \class PreviewWindow - \brief The PreviewWindow class is a custom widget - displaying the names of its currently set - window flags in a read-only text editor. + In addition to the detailed description of the class, the \\class + comment typically contains a \l {brief-command} {\\brief} command + and one or more \l{Markup Commands}. See the \\class command for + any of the Qt class for examples. Here is a very simple example: - \mainclass - \ingroup miscellaneous + \code + / *! + \class PreviewWindow + \brief The PreviewWindow class is a custom widget + displaying the names of its currently set + window flags in a read-only text editor. - The PreviewWindow class inherits QWidget. The widget - displays the names of its window flags set with the \l - {function}{setWindowFlags()} function. It is also - provided with a QPushButton that closes the window. + \ingroup miscellaneous - ... + The PreviewWindow class inherits QWidget. The widget + displays the names of its window flags set with the \l + {function} {setWindowFlags()} function. It is also + provided with a QPushButton that closes the window. - \sa QWidget - * / - \endcode + ... - will be rendered as + \sa QWidget + * / + \endcode - \quotation - \raw HTML - <h1>PreviewWindow Class Reference</h1> - \endraw + The way QDoc renders this \\class will depend a lot on your \c + {style.css} file, but the general outline of the class reference + page will look like this: - The PreviewWindow class is a custom widget displaying - the names of its currently set window flags in a - read-only text editor. \l {preview window}{More...} + \quotation + \raw HTML + <h1>PreviewWindow Class Reference</h1> + \endraw - \raw HTML - <h3>Properties</h3> - \endraw + The PreviewWindow class is a custom widget displaying + the names of its currently set window flags in a + read-only text editor. \l {preview window} {More...} - \list - \o 52 properties inherited from QWidget - \o 1 property inherited from QObject - \endlist + \raw HTML + <h3>Properties</h3> + \endraw - \raw HTML - <h3>Public Functions</h3> - \endraw + \list + \o 52 properties inherited from QWidget + \o 1 property inherited from QObject + \endlist - \list - \o \l {constructor}{PreviewWindow}(QWidget *parent = 0) - \o void \l {function}{setWindowFlags}(Qt::WindowFlags flags) - \endlist + \raw HTML + <h3>Public Functions</h3> + \endraw - \list - \o 183 public functions inherited from QWidget - \o 28 public functions inherited from QObject - \endlist + \list + \o \l {constructor} {PreviewWindow}(QWidget *parent = 0) + \o void \l {function} {setWindowFlags}(Qt::WindowFlags flags) + \endlist - \raw HTML - <h3>Public Slots</h3> - \endraw + \list + \o 183 public functions inherited from QWidget + \o 28 public functions inherited from QObject + \endlist - \list - \o 17 public slots inherited from QWidget - \o 1 public slot inherited from QObject - \endlist + \raw HTML + <h3>Public Slots</h3> + \endraw - \raw HTML - <h3>Additional Inherited Members</h3> - \endraw + \list + \o 17 public slots inherited from QWidget + \o 1 public slot inherited from QObject + \endlist - \list - \o 1 signal inherited from QWidget - \o 1 signal inherited from QObject - \o 4 static public members inherited from QWidget - \o 4 static public members inherited from QObject - \o 39 protected functions inherited from QWidget - \o 7 protected functions inherited from QObject - \endlist + \raw HTML + <h3>Additional Inherited Members</h3> + \endraw - \target preview window + \list + \o 1 signal inherited from QWidget + \o 1 signal inherited from QObject + \o 4 static public members inherited from QWidget + \o 4 static public members inherited from QObject + \o 39 protected functions inherited from QWidget + \o 7 protected functions inherited from QObject + \endlist - \raw HTML - <hr /> - <h2>Detailed Description</h2> - \endraw + \target preview window - The PreviewWindow class is a custom widget displaying - the names of its currently set window flags in a - read-only text editor. + \raw HTML + <hr /> + <h2>Detailed Description</h2> + \endraw - The PreviewWindow class inherits QWidget. The widget - displays the names of its window flags set with the \l - {function}{setWindowFlags()} function. It is also - provided with a QPushButton that closes the window. + The PreviewWindow class is a custom widget displaying + the names of its currently set window flags in a + read-only text editor. - ... + The PreviewWindow class inherits QWidget. The widget + displays the names of its window flags set with the \l + {function} {setWindowFlags()} function. It is also + provided with a QPushButton that closes the window. - See also QWidget. + ... - \raw HTML - <hr /> - <h2>Member Function Documentation</h2> - \endraw + See also QWidget. - \target constructor - \raw HTML - <h3>PreviewWindow(QWidget *parent = 0)</h3> - \endraw + \raw HTML + <hr /> + <h2>Member Function Documentation</h2> + \endraw - Constructs a preview window widget with \i parent. + \target constructor + \raw HTML + <h3>PreviewWindow(QWidget *parent = 0)</h3> + \endraw - \target function - \raw HTML - <h3>setWindowFlags(Qt::WindowFlags flags)</h3> - \endraw + Constructs a preview window widget with \e parent. - Sets the widgets flags using the - QWidget::setWindowFlags() function. + \target function + \raw HTML + <h3>setWindowFlags(Qt::WindowFlags flags)</h3> + \endraw - Then runs through the available window flags, - creating a text that contains the names of the flags - that matches the flags parameter, displaying - the text in the widgets text editor. - \endquotation + Sets the widgets flags using the + QWidget::setWindowFlags() function. - \row - \o \bold \\enum \target enum - \o \bold {The \\enum command allows you to document a C++ enum.} + Then runs through the available window flags, + creating a text that contains the names of the flags + that matches the flags parameter, displaying + the text in the widgets text editor. + \endquotation - The command follows \l {topical argument}{the general - topical command convention} for the argument. + \target enum-command + \section1 \\enum - The enum items are documented using the \l {value}{\\value} - command. If an item isn't documented, QDoc will emit a - warning. This can be avoided using the \l - {omitvalue}{\\omitvalue} command excluding an item from the - documentation. The enum documentation will be located in - the associated class, header file or namespace - documentation. + The \\enum command is for documenting a C++ enum type. The + argument is the full name of the enum type. - For example: + The enum values are documented in the \\enum comment using the \l + {value-command} {\\value} command. If an enum value is not + documented with \\value, QDoc emits a warning. These warnings can + be avoided using the \l {omitvalue-command} {\\omitvalue} command + to tell QDoc that an enum value should not be documented. The enum + documentation will be included on the class reference page, header + file page, or namespace page where the enum type is defined. For + example, consider the enum type \c {Corner} in the Qt namespace: - \code - enum Corner { - TopLeftCorner = 0x00000, - TopRightCorner = 0x00001, - BottomLeftCorner = 0x00002, - BottomRightCorner = 0x00003 - #if defined(QT3_SUPPORT) && !defined(Q_MOC_RUN) - ,TopLeft = TopLeftCorner, - TopRight = TopRightCorner, - BottomLeft = BottomLeftCorner, - BottomRight = BottomRightCorner - #endif - }; - \endcode + \code + enum Corner { + TopLeftCorner = 0x00000, + TopRightCorner = 0x00001, + BottomLeftCorner = 0x00002, + BottomRightCorner = 0x00003 + #if defined(QT3_SUPPORT) && !defined(Q_MOC_RUN) + ,TopLeft = TopLeftCorner, + TopRight = TopRightCorner, + BottomLeft = BottomLeftCorner, + BottomRight = BottomRightCorner + #endif + }; + \endcode - In case of the Qt::Corner enum, + This enum can be cocumented this way: - \code - / *! - \enum Qt::Corner - - This enum type specifies a corner in a rectangle: - - \value TopLeftCorner - The top-left corner of the rectangle. - \value TopRightCorner - The top-right corner of the rectangle. - \value BottomLeftCorner - The bottom-left corner of the rectangle. - \value BottomRightCorner - The bottom-right corner of the rectangle. - - \omitvalue TopLeft - \omitvalue TopRight - \omitvalue BottomLeft - \omitvalue BottomRight - * / - \endcode + \code + / *! + \enum Qt::Corner + + This enum type specifies a corner in a rectangle: + + \value TopLeftCorner + The top-left corner of the rectangle. + \value TopRightCorner + The top-right corner of the rectangle. + \value BottomLeftCorner + The bottom-left corner of the rectangle. + \value BottomRightCorner + The bottom-right corner of the rectangle. + + \omitvalue TopLeft + \omitvalue TopRight + \omitvalue BottomLeft + \omitvalue BottomRight + * / + \endcode - this associated QDoc comment will be rendered as + Note the inclusion of the namespace qualifier. QDoc will render + this enum type in \c {qt.html} like this: \quotation \raw HTML @@ -4800,231 +4515,258 @@ \endraw \endquotation - in qt.html. + See also \l {value-command} {\\value} and \l {omitvalue-command} {\\omitvalue}. - See also \l {value}{\\value} and \l {omitvalue}{\\omitvalue}. + \target example-command + \section1 \\example - \row - \o \bold \\example \target example-command - \o \bold {The \\example command allows you to document an - example.} + The \\example command is for documenting an example. The argument + is the example's path relative to omne of the paths listed in the + \l {exampledirs-variable} {exampledirs} variable in the QDoc + configuration file. - The command follows \l {topical argument}{the general - topical command convention} for the argument. In particular - the command's argument is the example's path relative to - the paths listed in the \l exampledirs configuration - variable. + The documentation page will be output to \c {path-to-example}.html. + QDoc will add a list of all the example's source files at the top + of the page. - The documentation will be located in \i - {path-to-example}.html, and QDoc will add a list of all the - example files at the top of this documentation page. + For example, if \l {exampledirs-variable} {exampledirs} contains + \c $QTDIR/examples/widgets/imageviewer, then - For example, if \l exampledirs contain \c - $QTDIR/examples/widgets/imageviewer, then + \code + / *! + \example widgets/imageviewer + \title ImageViewer Example + \subtitle - \code - / *! - \example widgets/imageviewer - \title ImageViewer Example - \subtitle + The example shows how to combine QLabel and QScrollArea + to display an image. - The example shows how to combine QLabel and QScrollArea - to display an image. + ... + * / + \endcode - ... - * / - \endcode + QDoc renders this example in widgets-imageviewer.html: - will be rendered as + \quotation + \raw HTML + <center><h1>Image Viewer Example</h1></center> + \endraw - \quotation - \raw HTML - <center><h1>Image Viewer Example</h1></center> - \endraw + Files: + \list + \o \l{http://qt.nokia.com/doc/4.0/widgets-imageviewer-imageviewer-cpp.html} + {widgets/imageviewer/imageviewer.cpp} + \o \l{http://qt.nokia.com/doc/4.0/widgets-imageviewer-imageviewer-h.html} + {widgets/imageviewer/imageviewer.h} + \o \l{http://qt.nokia.com/doc/4.0/widgets-imageviewer-main-cpp.html} + {widgets/imageviewer/main.cpp} + \endlist - Files: - \list - \o \l{http://qt.nokia.com/doc/4.0/widgets-imageviewer-imageviewer-cpp.html} - {widgets/imageviewer/imageviewer.cpp} - \o \l{http://qt.nokia.com/doc/4.0/widgets-imageviewer-imageviewer-h.html} - {widgets/imageviewer/imageviewer.h} - \o \l{http://qt.nokia.com/doc/4.0/widgets-imageviewer-main-cpp.html} - {widgets/imageviewer/main.cpp} - \endlist + The example shows how to combine QLabel and QScrollArea + to display an image. - The example shows how to combine QLabel and QScrollArea - to display an image. + ... + \endquotation - ... - \endquotation + \target externalpage-command + \section1 \\externalpage - in widgets-imageviewer.html. + The \\externalpage command assigns a title to an external URL. - \row - \o \bold \\fn \target fn - \o \bold {The \\fn command allows you to document a function.} - - The command follows \l {topical argument}{the general - topical command convention} for the argument. In particular - it is important that the return type of the function, - whether it is \c const or not and the complete set of - arguments with type are included in the argument. If the - referenced function doesn't exist, QDoc will emit a - warning. - - Also, the \\fn command is QDoc's default command, i.e. when - no topical command can be found within a QDoc comment, QDoc - tries to tie the documentation to the following code as if - it was function documentation. - - This means that the command normally isn't necessary since - the recommended style is to write the function - documentation directly before the function implementation - in the \c .cpp file. In fact, it should only be used for - inline functions implemented in the \c .h file. - - For example: + \code + / *! + \externalpage http://doc.trolltech.com/4.3/qtopiacore.html + \title Qtopia Core + * / + \endcode - \code - / *! - \fn bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const + This allows you to include a link to the external page in your + documentation this way: - Returns true if this toolbar is dockable in the given - \a area; otherwise returns false. - * / - \endcode + \code + / *! + The broad scope of the \l {Qtopia Core} API enables it to + be used across a wide variety of development projects. + * / + \endcode - will be rendered as + QDoc renders this as: - \quotation - \raw HTML - <h3>bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const - </h3> - \endraw + \quotation + The broad scope of the \l + {http://doc.trolltech.com/4.3/qtopiacore.html} {Qtopia + Core} API enables it to be used across a wide variety + of development projects. + \endquotation - Returns true if this toolbar is dockable in the given - \a area; otherwise returns false. - \endquotation + To achieve the same result without using the \\externalpage + command, you would have to hard code the adress into your + documentation: - See also \l {overload}{\\overload}. + \code + / *! + The broad scope of the \l + {http://doc.trolltech.com/4.3/qtopiacore.html} {Qtopia + Core} API enables it to be used across a wide variety + of development projects. + * / + \endcode - \row - \o \bold \\group \target group - \o \bold {The \\group command creates a separate page that - lists the classes belonging to the group specified by the - command's argument.} - - The command follows \l {topical argument}{the general - topical command convention} for the argument. The \\group - command is typically followed by a \l {title}{\\title} - command and a short introduction to the group. The - generated HTML documentation for the specified group is put - in <lower-case>\i{group}.html. - - A class can be related to a group by using the \l - {ingroup}{\\ingroup} command. In addition, overviews can be - related to a group using the same command, but these must - be listed explicitly using the \l - {generatelist}{\\generatelist} command (see example below). - - Each class is listed with a link to the class reference - page and a brief description based on the classes' \l - {brief}{\\brief} texts. For example: + The \\externalpage command makes it easier to maintain the + documentation. If the adress changes, you only need to change the + argument of the \\externalpage command. - \code - / *! - \group io + \target fn-command + \section1 \\fn (function) - \title Input/Output and Networking + The \\fn command is for documenting a function. The argument is + the function's signature, including its return type, const-ness, + and list of formal arguments with types. If the named function + doesn't exist, QDoc emits a warning. - These classes are used to handle input and output to - and from external devices, processes, files etc. as - well as manipulating files and directories. - * / - \endcode + \note The \\fn command is QDoc's default command, i.e. when no + topic command can be found in a QDoc comment, QDoc tries to tie + the documentation to the following code as if it is the + documentation for a function. Hence, it is normally not necessary + to include this command when documenting a function, if the + function's QDoc comment is written immediately above the function + implementation in the \c .cpp file. But it must be present when + documenting an inline function in the \c .cpp file that is + implemented in the \c .h file. - will be rendered as + \code + / *! + \fn bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const - \quotation - \raw HTML + Returns true if this toolbar is dockable in the given + \a area; otherwise returns false. + * / + \endcode - <h1>Input/Output and Networking</h1> - - <p>These classes are used to handle input and output - to and from external devices, processes, files etc. as - well as manipulating files and directories.</p> - - <p> - <table width="100%"> - <tr valign="top" bgcolor="#e0e0e0"> - <td><b> - <a href="http://qt.nokia.com/doc/4.0/qabstractsocket.html">QAbstractSocket</a> - </b></td> - <td> - The base functionality common to all socket types - </td></tr> - - <tr valign="top" bgcolor="#e0e0e0"> - <td><b> - <a href="http://qt.nokia.com/doc/4.0/qbuffer.html">QBuffer</a> - </b></td> - <td> - QIODevice interface for a QByteArray - </td></tr> - - <tr valign="top" bgcolor="#e0e0e0"> - <td><b> - <a href="http://qt.nokia.com/doc/4.0/qclipboard.html">QClipboard</a> - </b></td> - <td> - Access to the window system clipboard - </td></tr> - </table> - \endraw - \endquotation + QDoc renders this as: - in io.html. + \quotation + \raw HTML + <h3>bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const + </h3> + \endraw - Note that overviews related to the given group, must be - listed explicitly using the \l - {generatelist}{\\generatelist} command with the \c related - argument. For example: + Returns true if this toolbar is dockable in the given + \a area; otherwise returns false. + \endquotation - \code - / *! - \group architecture + See also \l {overload-command} {\\overload}. - \title Architecture + \target group-command + \section1 \\group - These documents describe aspects of Qt's architecture - and design, including overviews of core Qt features and - technologies. + The \\group command creates a separate page that lists the classes + belonging to the group. The argument is the group name. - \generatelist{related} - * / - \endcode + A class is included in a group by using the \l {ingroup-command} + {\\ingroup} command. Overview pages can also be related to a group + using the same command, but the list of overview pages must be + requested explicitly using the \l {generatelist-command} + {\\generatelist} command (see example below). - See also \l {ingroup}{\\ingroup} and \l - {generatelist}{\\generatelist}. + The \\group command is typically followed by a \l {title-command} + {\\title} command and a short introduction to the group. The + HTML page for the group is written to a \c {.html} file put in + <lower-case>\e{group}.html. - \row - \o \bold \\headerfile \target headerfile - \o \bold {The \\headerfile command allows you to document - global functions, types and macros declared in a header file.} + Each class name is listed as a link to the class reference page + followed by the text from the class's \l {brief-command} {\\brief} + texts. + + \code + / *! + \group io - The command follows \l {topical argument}{the general - topical command convention} for the argument, and the - generated HTML documentation for the specified header file - is put in <lower-case>\i{headerfilename}.html. + \title Input/Output and Networking - A function, type or macro can be associated with a - headerfile using the \l {relates}{\\relates} command. + These classes are used to handle input and output to + and from external devices, processes, files etc. as + well as manipulating files and directories. + * / + \endcode + + QDoc generates a group page in \c{io.html} that will look + like this: + + \quotation + \raw HTML + + <h1>Input/Output and Networking</h1> + + <p>These classes are used to handle input and output + to and from external devices, processes, files etc. as + well as manipulating files and directories.</p> + + <p> + <table width="100%"> + <tr valign="top" bgcolor="#e0e0e0"> + <td><b> + <a href="http://qt.nokia.com/doc/4.0/qabstractsocket.html">QAbstractSocket</a> + </b></td> + <td> + The base functionality common to all socket types + </td></tr> + + <tr valign="top" bgcolor="#e0e0e0"> + <td><b> + <a href="http://qt.nokia.com/doc/4.0/qbuffer.html">QBuffer</a> + </b></td> + <td> + QIODevice interface for a QByteArray + </td></tr> + + <tr valign="top" bgcolor="#e0e0e0"> + <td><b> + <a href="http://qt.nokia.com/doc/4.0/qclipboard.html">QClipboard</a> + </b></td> + <td> + Access to the window system clipboard + </td></tr> + </table> + \endraw + \endquotation - If the referenced header file doesn't exist, the - \\headerfile command will still create a documentation page - for a header file with the referenced file's name. + Note that overview pages related to the group, must be listed + explicitly using the \l {generatelist-command} {\\generatelist} + command with the \c related argument. - For example: + \code + / *! + \group architecture + + \title Architecture + + These documents describe aspects of Qt's architecture + and design, including overviews of core Qt features and + technologies. + + \generatelist{related} + * / + \endcode + + See also \l {ingroup-command} {\\ingroup} and \l + {generatelist-command} {\\generatelist}. + + \target headerfile-command + \section1 \\headerfile + + The \\headerfile command is for documenting the global functions, + types and macros that are declared in a header file but not in a + namespace. The argument is the name of the header file. The HTML + page is written to a \c {.html} file constructed from the header + file aregument. + + The documentation for a function, type, or macro that is declared + in the header file being documented is included in the header file + page using the \l {relates-command} {\\relates} command. + + If the argument doesn't exist as a header file, the \\headerfile + command creates a documentation page for the header file anyway. \code / *! @@ -5041,7 +4783,8 @@ * / \endcode - will be rendered as + QDoc generates a header file page \c{qtalgorithms.html} that looks + like this: \quotation \raw HTML @@ -5049,7 +4792,7 @@ Generic Algorithms</h1></center> <p>The <QtAlgorithms> header file provides generic template-based algorithms. - <a href="13-qdoc-commands-topical.html#header">More...</a> + <a href="13-qdoc-commands-topics.html#header-command">More...</a> </p> <h3>Functions</h3> @@ -5077,163 +4820,139 @@ ... \endquotation - in qtalgorithms.html. - - \row - \o \bold \\macro \target macro - \o \bold {The \\macro command allows you to document a C++ macro.} - - The command follows \l {topical argument}{the general - topical command convention} for the argument. - - QDoc recognizes three different macro syntax: function-like - macros like Q_ASSERT(), declaration-style macros like - Q_PROPERTY() and macros without parentheses like Q_OBJECT. - - The \\macro command must be followed by a \l - {relates}{\\relates} command which attaches the - documentation to that of a related class, header file. or - namespace. Otherwise the documentation will be lost. - - For example: + \target macro-command + \section1 \\macro - \code - / *! - \macro void Q_ASSERT(bool test) - \relates <QtGlobal> - - Prints a warning message containing the source code - file name and line number if \a test is false. - - ... - - \sa Q_ASSERT_X(), qFatal(), {Debugging Techniques} - * / - \endcode + The \\macro command is for documententin a C++ macro. The argument + is the macro in one of three styles: function-like macros like + Q_ASSERT(), declaration-style macros like Q_PROPERTY(), and macros + without parentheses like Q_OBJECT. - will be rendered as + The \\macro comment must contain a \l {relates-command} + {\\relates} command that attaches the macro comment to a class, + header file, or namespace. Otherwise, the documentation will be + lost. Here are three example macro comments followed by what they + might look like in \c {qtglobal.html} or \c {qobject.html}: - \quotation - \raw HTML - <h3>void Q_ASSERT ( bool <i>test</i> )</h3> - \endraw - - Prints a warning message containing the source code - file name and line number if \a test is false. - - ... - - See also Q_ASSERT_X(), qFatal() and \l {Debugging - Techniques}. - \endquotation + \code + / *! + \macro void Q_ASSERT(bool test) + \relates <QtGlobal> - in qtglobal.html. And + Prints a warning message containing the source code + file name and line number if \a test is false. - \code - / *! - \macro Q_PROPERTY(...) - \relates QObject + ... - This macro declares a QObject property. The syntax is: + \sa Q_ASSERT_X(), qFatal(), {Debugging Techniques} + * / + \endcode - ... + \quotation + \raw HTML + <h3>void Q_ASSERT ( bool <i>test</i> )</h3> + \endraw - \sa {Qt's Property System} - * / - \endcode + Prints a warning message containing the source code + file name and line number if \a test is false. - will be rendered as + ... - \quotation - \raw HTML - <h3>Q_PROPERTY ( ... )</h3> - \endraw + See also Q_ASSERT_X(), qFatal() and \l {Debugging Techniques}. + + \endquotation - This macro declares a QObject property. The syntax is: + \code + / *! + \macro Q_PROPERTY(...) + \relates QObject - ... + This macro declares a QObject property. The syntax is: - See also \l {Qt's Property System}. - \endquotation + ... - in qobject.html. And + \sa {Qt's Property System} + * / + \endcode - \code - / *! - \macro Q_OBJECT - \relates QObject + \quotation + \raw HTML + <h3>Q_PROPERTY ( ... )</h3> + \endraw - The Q_OBJECT macro must appear in the private section - of a class definition that declares its own signals and - slots or that uses other services provided by Qt's - meta-object system. + This macro declares a QObject property. The syntax is: - ... + ... - \sa {Meta-Object System}, {Signals and Slots}, {Qt's - Property System} - * / - \endcode + See also \l {Qt's Property System}. + \endquotation - will be rendered as + \code + / *! + \macro Q_OBJECT + \relates QObject - \quotation - \raw HTML - <h3>Q_OBJECT</h3> - \endraw + The Q_OBJECT macro must appear in the private section + of a class definition that declares its own signals and + slots or that uses other services provided by Qt's + meta-object system. - The Q_OBJECT macro must appear in the private section - of a class definition that declares its own signals and - slots or that uses other services provided by Qt's - meta-object system. + ... - ... + \sa {Meta-Object System}, {Signals and Slots}, {Qt's + Property System} + * / + \endcode - See also \l {Meta-Object System}, \l {Signals and - Slots} and \l {Qt's Property System}. - \endquotation + \quotation + \raw HTML + <h3>Q_OBJECT</h3> + \endraw - in qobject.html. + The Q_OBJECT macro must appear in the private section + of a class definition that declares its own signals and + slots or that uses other services provided by Qt's + meta-object system. - \row - \o \bold \\module \target module - \o \bold {The \\module creates a separate page that lists the - classes belonging to the module specified by the command's - argument.} + ... - The command follows \l {topical argument}{the general - topical command convention} for the argument. + See also \l {Meta-Object System}, \l {Signals & + Slots} and \l {Qt's Property System}. + \endquotation - A class can be related to a module using the \l - {inmodule}{\\inmodule} command. + \target module-command + \section1 \\module - The \\module command is typically followed by the \l - {title}{\\title} and \l {brief}{\\brief} commands. Each - class is listed with a link to the class reference page and - a brief description based on the classes' \l - {brief}{\\brief} texts. + The \\module creates a page that lists the classes belonging to + the module specified by the command's argument. A class included + in the module by including the \l {inmodule-command} {\\inmodule} + command in the \\class comment. - For example: + The \\module command is typically followed by a \l {title-command} + {\\title} and a \l {brief-command} {\\brief} command. Each class + is listed as a link to the class reference page followed by the + text from the class's \l {brief-command} {\\brief} command. For + example: - \code - / *! - \module QtNetwork + \code + / *! + \module QtNetwork - \title QtNetwork Module + \title QtNetwork Module - \brief The QtNetwork module offers classes that allow - you to write TCP/IP clients and servers. + \brief The QtNetwork module offers classes that allow + you to write TCP/IP clients and servers. - The network module provides classes to make network - programming easier and portable. It offers both - high-level classes such as QHttp and QFtp that - implement specific application-level protocols, and - lower-level classes such as QTcpSocket, QTcpServer, and - QUdpSocket. - * / - \endcode + The network module provides classes to make network + programming easier and portable. It offers both + high-level classes such as QHttp and QFtp that + implement specific application-level protocols, and + lower-level classes such as QTcpSocket, QTcpServer, and + QUdpSocket. + * / + \endcode - will be rendered as + QDoc renders this in \c {qtnetwork.html} like this: \quotation \raw HTML @@ -5242,7 +4961,7 @@ The QtNetwork module offers classes that allow you to write TCP/IP clients and servers.\l {module - details}{More...} + details} {More...} \raw HTML <p> @@ -5296,43 +5015,33 @@ \endquotation - in qtnetwork.html. + See also \l {inmodule-command} {\\inmodule} - See also \l {inmodule}{\\inmodule} + \target namespace-command + \section1 \\namespace - \row - \o \bold \\namespace \target namespace - \o \bold {The \\namespace command allows you to document a C++ - namespace.} - - The command follows \l {topical argument}{the general - topical command convention} for the argument. - - QDoc will generate the same additional links and - documentation for all the members of the namespace as it - does for \l {framework}{classes}. The documentation for - the specified namespace is put in <lower-case>\i - {namespace}.html. - - For example: + The \\namespace command is for documenting the contents of the C++ + namespace named as its argument. The documentation outline QDoc + generates for a namespace is similar to the outline it generates + for a C++ class. - \code - / *! - \namespace Qt + \code + / *! + \namespace Qt - \brief The Qt namespace contains miscellaneous - identifiers used throughout the Qt library. - * / - \endcode + \brief The Qt namespace contains miscellaneous + identifiers used throughout the Qt library. + * / + \endcode - will be rendered as + QDoc renders this in \c{qt.html} like this: \quotation \raw HTML <center><h1>Qt Namespace Reference</h1></center> <p>The Qt namespace contains miscellaneous identifiers used throughout the Qt library. - <a href="13-qdoc-commands-topical.html#name">More...</a> + <a href="13-qdoc-commands-topics.html#name">More...</a> </p> <pre>#include <Qt></pre> @@ -5362,18 +5071,13 @@ ... \endquotation - in qt.html. - - \row - \o \bold \\page \target page - \o \bold {The \\page command allows you to create a stand-alone - documentation page.} - - The command follows \l {topical argument}{the general - topical command convention} for the argument. + \target page-command + \section1 \\page - The page's title can be set using the \l {title}{\\title} - command. For example: + The \\page command is for creating a stand-alone documentation + page. The argument is the name of the file where QDoc should + store the page. The page title is set using the \l {title-command} + {\\title} command. \code / *! @@ -5398,470 +5102,587 @@ * / \endcode - will be rendered in its own HTML file: \l{About Qt}. + QDoc renders this page in \c {aboutqt.html}. - \row - \o \bold {\\externalpage} \target externalpage - \o \bold {The \\externalpage command gives a title to - an external URL.} + \target property-command + \section1 \\property - The command follows \l {topical argument}{the general - topical command convention} for the argument. + The \\property command is for documenting a Qt property. The + argument is the full property name. - For example: + A property is defined using the Q_PROPERTY() macro. The macro + takes as arguments the property's name and its set, reset and get + functions. - \code - / *! - \externalpage http://www.trolltech.com/products/embedded/index.html - \title Qtopia Core - * / - \endcode + \code + Q_PROPERTY(QString state READ state WRITE setState) + \endcode - The QDoc comment above allows you to link to the Qtopia - Core webpage by simply linking to the given title. For - example: + The set, reset and get functions don't need to be documented, + documenting the property is sufficient. QDoc will generate a list + of the access function that will appear in the property + documentation which in turn will be located in the documentation + of the class that defines the property. - \code - / *! - The broad scope of the \l {Qtopia Core} API enables it to - be used across a wide variety of development projects. - * / - \endcode + The \\property command comment typically includes a \l + {brief-command} {\\brief} command. Forproperties the \l + {brief-command} {\\brief} command's argument is a sentence + fragment that will be included in a one line description of the + property. The command follows the same rules for the \l + {brief-property} {description} as the \l {variable-command} + {\\variable} command. - will be rendered as + \code + / *! + \property QPushButton::flat + \brief whether the border is disabled - \quotation - The broad scope of the \l - {http://www.trolltech.com/products/embedded/index.html}{Qtopia - Core} API enables it to be used across a wide variety - of development projects. - \endquotation + This property's default is false. + * / + \endcode - To achieve the same result without using the - \\externalpage command, you would have to hard code the - adress into your documentation: + QDoc includes this in \c {qpushbutton.html} like this: - \code - / *! - The broad scope of the \l - {http://www.trolltech.com/products/embedded/index.html}{Qtopia - Core} API enables it to be used across a wide variety - of development projects. - * / - \endcode + \quotation + \raw HTML + <h3>flat : bool</h3> + \endraw - The \\externalpage command makes it easier to maintain the - documentation. If the adress changes, you only need to change the - argument of the \\externalpage command. + This property holds whether the border is disabled. - \row - \o \bold \\property \target property - \o \bold {The \\property command allows you to document a Qt - property.} + This property's default is false. - The command follows \l {topical argument}{the general - topical command convention} for the argument. + Access functions: - A property is defined using the Q_PROPERTY() macro. The - macro takes as arguments the property's name and its set, - reset and get functions. For example: + \list + \o \bold { bool isFlat () const} + \o \bold { void setFlat ( bool )} + \endlist - \code - Q_PROPERTY(QString state READ state WRITE setState) - \endcode + \endquotation - The set, reset and get functions don't need to be - documented, documenting the property is sufficient. QDoc - will generate a list of the access function that will - appear in the property documentation which in turn will be - located in the documentation of the class that defines the - property. + \code + / *! + \property QWidget::width + \brief the width of the widget excluding any window frame - The \\property command is typically accompanied with a \l - {brief}{\\brief} command. In the case of a property, the - \l {brief}{\\brief} command's argument is a sentence - fragment that will be included in a one-sentence - description of the property generated by QDoc. The command - follows the same rules for the \l {brief - property}{description} as the \l {variable}{\\variable} - command. + See the \l {Window Geometry} documentation for an + overview of window geometry. - For example: + \sa geometry, height, size + * / + \endcode - \code - / *! - \property QPushButton::flat - \brief whether the border is disabled + QDoc includes this in \c {qwidget.html} like this: - This property's default is false. - * / - \endcode + \quotation + \raw HTML + <h3>width : const int</h3> + \endraw - will be rendered as + This property holds the width of the widget excluding + any window frame. - \quotation - \raw HTML - <h3>flat : bool</h3> - \endraw + See the \l {Window Geometry} documentation for an + overview of window geometry. - This property holds whether the border is disabled. + Access functions: - This property's default is false. + \list + \o \bold { int width () const} + \endlist - Access functions: + See also \l{QWidget::geometry} {geometry}, + \l{QWidget::height} {height}, and \l{QWidget::size} {size}. + \endquotation - \list - \o \bold { bool isFlat () const} - \o \bold { void setFlat ( bool )} - \endlist + \target service-command + \section1 \\service + + The \\service command tells QDoc that a class is a service class + and names the service. The command takes two arguments, the name + of the class and the name of the service. Currently, this command + is not used in the Qt documentation. + + \code + / *! + \service TimeService Time + ... + * / + class TimeService : public QCopObjectService + { + ... + } + \endcode + + See also \l {class-command} {\\class} and \l + {generatelist-command} {\\generatelist}. + + \target qmlattachedproperty-command + \section1 \\qmlattachedproperty \span {class="newStuff"} {(new)} + + The \\qmlattachedproperty command is for documenting a QML + property that will be attached to some QML element type. See + \l{http://doc.trolltech.com/4.7/qdeclarativeintroduction.html#attached-properties} + {Attached Properties}. The argument is the rest of the line. The + argument text should be the property type, followed by the QML + element name where the property is being declared, the \c{::} + qualifier, and finally the property name. If we have a QML + attached property named \c isCurrentItem in QML element \c ListView, + and the property has type \c {bool}, the \\qmlattachedproperty for + it would look like this: - \endquotation + \code + / *! + \qmlattachedproperty bool ListView::isCurrentItem + This attached property is true if this delegate is the current + item; otherwise false. - in qpushbutton.html. And + It is attached to each instance of the delegate. - \code - / *! - \property QWidget::width - \brief the width of the widget excluding any window frame + This property may be used to adjust the appearance of the current + item, for example: - See the \l {Window Geometry} documentation for an - overview of window geometry. + \snippet doc/src/snippets/declarative/listview/listview.qml isCurrentItem + * / + \endcode - \sa geometry, height, size - * / - \endcode + QDoc includes this attached property on the QML reference page for the + \l{http://doc.trolltech.com/4.7/qml-listview.html#isCurrentItem-prop} + {ListView} element. - will be rendered as + \target qmlattachedsignal-command + \section1 \\qmlattachedsignal \span {class="newStuff"} {(new)} - \quotation - \raw HTML - <h3>width : const int</h3> - \endraw + The \\qmlattachedsignal command is for documenting an attachable + \l{http://doc.trolltech.com/4.7/qdeclarativeintroduction.html#signal-handlers} + {signal handler}. The \\qmlattachedsignal command is used just like + the \l{qmlsignal-command} {\\qmlsignal} command. - This property holds the width of the widget excluding - any window frame. + The argument is the rest of the line. It should be the name of the + QML element where the signal handler is declared, the \c{::} + qualifier, and finally the signal handler name. If we have a QML + attached signal handler named \c onAdd() in the \c GridView + element, the \\qmlattachedsignal for it would look like this: - See the \l {Window Geometry} documentation for an - overview of window geometry. + \code + / *! + \qmlattachedsignal GridView::onAdd() + This attached handler is called immediately after an item is + added to the view. + * / + \endcode - Access functions: + QDoc includes this documentation on the QML reference page for the + \l{http://doc.trolltech.com/4.7/qml-gridview.html#onAdd-signal} + {GridView} element. - \list - \o \bold { int width () const} - \endlist + \target qmlbasictype-command + \section1 \\qmlbasictype \span {class="newStuff"} {(new)} - See also \l{QWidget::geometry}{geometry}, - \l{QWidget::height}{height}, and \l{QWidget::size}{size}. - \endquotation + The \\qmlbasictype command is for documenting a basic type for QML. + The argument is the type name. The type must be included in the + QML basic types group using the \l{ingroup-command}{\\ingroup} + command as shown below. This will cause QDoc to include the + documentation for the type on the + \l{http://doc.trolltech.com/4.7/qdeclarativebasictypes.html} + {QML Basic Types} page. The \l{brief-command} {\\brief} command + is also required, because it appears on the + \l{http://doc.trolltech.com/4.7/qdeclarativebasictypes.html} + {QML Basic Types} page as well. - in qwidget.html. + \code + / *! + \qmlbasictype int + \ingroup qmlbasictypes - \row - \o \bold \\service \target service + \brief An integer is a whole number, e.g. 0, 10, or -20. - \o \bold {The \\service command tells QDoc that a class is a - service class and specifies its alias, i.e. the associated - service's name.} + An integer is a whole number, e.g. 0, 10, or -20. The possible + \c int values range from around -2000000000 to around + 2000000000, although most elements will only accept a reduced + range (which they mention in their documentation). - The command takes two arguments, the service class's name - and the associated alias. For example: + Example: + \qml + Item { width: 100; height: 200 } + \endqml - \code - / *! - \service TimeService Time - ... - * / - class TimeService : public QCopObjectService - { - ... - } - \endcode + \sa {QML Basic Types} + * / + \endcode - See also \l {class}{\\class} and \l - {generatelist}{\\generatelist}. + QDoc outputs this as \l{http://doc.trolltech.com/4.7/qml-int.html} + {qml-int.html}. - \row - \o \bold \\typedef \target typedef - \o \bold {The \\typedef command allows you to document a C++ type - definition.} + \target qmlclass-command + \section1 \\qmlclass \span {class="newStuff"} {(new)} - The command follows \l {topical argument}{the general - topical command convention} for the argument. + The \\qmlclass command is for documenting a QML element that is + instantiated by a C++ class. The command has two arguments. The + first argument is the name of the QML element. The second argument + is the name of the C++ class that instantiates the QML element. - The documentation will be located in the associated class, - header file or namespace documentation. When documenting a - global type definition, the \\typedef command must be - accompanied with a \l {relates}{\\relates} command. For - example: + \code + / *! + \qmlclass Transform QGraphicsTransform + \ingroup qml-transform-elements + \since 4.7 + \brief The Transform elements provide a way of building + advanced transformations on Items. - \code - / *! - \typedef QObjectList - \relates QObject + The Transform element is a base type which cannot be + instantiated directly. The following concrete Transform types + are available: - Synonym for QList<QObject>. - * / - \endcode + \list + \o \l Rotation + \o \l Scale + \o \l Translate + \endlist - will be rendered as + The Transform elements let you create and control advanced + transformations that can be configured independently using + specialized properties. - \quotation - \raw HTML - <h3>typedef QObjectList</h3> - \endraw + You can assign any number of Transform elements to an \l + Item. Each Transform is applied in order, one at a time. - Synonym for QList<QObject>. - \endquotation + * / + \endcode - in qobject.html. Another, although more rare, example is + This example generates the + \l {http://doc.trolltech.com/4.7/qml-transform.html} {QML Trasform + Element} page. The \\qmlclass comment should include the \l + {since-command} {\\since} command, because all QML elements are + new. It should also include the \l{brief-command} {\\brief} + command. And since every QML element is a member of a group of QML + elements, it should also include one or more \l{ingroup-command} + {\\ingroup} commands. - \code - / *! - \typedef QMsgHandler - \relates QtGlobal + \target qmlmethod-command + \section1 \\qmlmethod \span {class="newStuff"} {(new)} - This is a typedef for a pointer to a function with the - following signature: + The \\qmlmethod command is for documenting a QML method. The + argument is the complete method signature, including return + type and parameter names and types. - \code - void myMsgHandler(QtMsgType, const char *); - \ endcode + \code + / *! + \qmlmethod void TextInput::select(int start, int end) - \sa QtMsgType, qInstallMsgHandler() - * / - \endcode + Causes the text from \a start to \a end to be selected. - will be rendered as + If either start or end is out of range, the selection is not changed. - \quotation - \raw HTML - <h3>typedef QtMsgHandler</h3> - \endraw + After calling this, selectionStart will become the lesser and + selectionEnd will become the greater (regardless of the order + passed to this method). - This is a typedef for a pointer to a function with the - following signature: + \sa selectionStart, selectionEnd + * / + \endcode - \raw HTML - <tt> - <pre> void myMsgHandler(QtMsgType, const char *);</pre> - </tt> - \endraw + QDoc includes this documentation on the element refence page for the + \l{http://doc.trolltech.com/4.7/qml-textinput.html#select-method} + {TextInput} element. - See also QtMsgType and qInstallMsgHandler(). + \target qmlproperty-command + \section1 \\qmlproperty \span {class="newStuff"} {(new)} - \endquotation + The \\qmlproperty command is for documenting a QML property. The + argument is the rest of the line. The argument text should be the + property type, followed by the QML element name, the \c{::} + qualifier, and finally the property name. If we have a QML + property named \c x in QML element \c Translate, and the property + has type \c {real}, the \\qmlproperty for it would look like this: - in qtglobal.html. Other type definitions are located in the - documentation of the class that defines it, for example: + \code + / *! + \qmlproperty real Translate::x - \code - / *! - \typedef QLinkedList::Iterator + The translation along the X axis. + * / + \endcode - Qt-style synonym for QList::iterator. - * / - \endcode + QDoc includes this QML property on the QML reference page for the + \l {http://doc.trolltech.com/4.7/qml-translate.html} {Translate} + element. - will be rendered as + \target qmlsignal-command + \section1 \\qmlsignal \span {class="newStuff"} {(new)} - \quotation - \raw HTML - <h3>typedef QLinkedList::Iterator</h3> - \endraw + The \\qmlsignal command is for documenting a + \l{http://doc.trolltech.com/4.7/qdeclarativeintroduction.html#signal-handlers} + {signal handler}. + The argument is the rest of the line. It should be the QML element where the + signal handler is declared, the \c{::} qualifier, and finally the signal + handler name. If we have a QML signal handler named \c onAdd() in QML + element \c MouseArea, the \\qmlsignal for it would look like this: - Qt-style synonym for QList::iterator. - \endquotation + \code + / *! + \qmlsignal MouseArea::onEntered() - in qlinkedlist.html. + This handler is called when the mouse enters the mouse area. - \row - \o \bold \\variable \target variable - \o \bold {The \\variable command allows you to document a - member variable or a constant.} + By default the onEntered handler is only called while a button is + pressed. Setting hoverEnabled to true enables handling of + onEntered when no mouse button is pressed. - The command follows \l {topical argument}{the general - topical command convention} for the argument. + \sa hoverEnabled + * / + \endcode - The \\variable command is typically followed by a \l - {brief}{\\brief} command; QDoc will generate the - documentation for the variable based on the brief - description. The command follows the same rules for the \l - {brief property}{description} as the \l - {property}{\\property} command. + QDoc includes this documentation on the QML reference page for the + \l{http://doc.trolltech.com/4.7/qml-mousearea.html#onEntered-signal} + {MouseArea} element. - The documentation will be located in the in the associated - class, header file or namespace documentation. + \target typedef-command + \section1 \\typedef - In case of a member variable: + The \\typedef command is for documenting a C++ typedef. The + argument is the name of the typedef. The documentation for + the typedef will be included in the refernece documentation + for the class, namespace, or header file in which the typedef + is declared. To relat the \\typedef to a class, namespace, or + header file, the \\typedef comment must contain a + \l {relates-command} {\\relates} command. - \code - / *! - \variable QStyleOption::palette - \brief the palette that should be used when painting - the control - * / - \endcode + \code + / *! + \typedef QObjectList + \relates QObject - will be rendered as + Synonym for QList<QObject>. + * / + \endcode - \quotation - \raw HTML - <h3> - <a href="http://qt.nokia.com/doc/4.0/qpalette.html"> - QPalette - </a> - QStyleOption::palette - </h3> - \endraw + QDoc includes this in \c {qobject.html} as: - This variable holds the palette that should be used - when painting the control. - \endquotation + \quotation + \raw HTML + <h3>typedef QObjectList</h3> + \endraw - in qstyleoption.html. + Synonym for QList<QObject>. + \endquotation - But you can also use the \\variable command to document - constants like for example the \c Type and \c UserType - constants in the QTreeWidgetItem class: + Another, although more rare, example: - \code - enum { Type = 0, UserType = 1000 }; - \endcode + \code + / *! + \typedef QMsgHandler + \relates QtGlobal - Then + This is a typedef for a pointer to a function with the + following signature: - \code - / *! - \variable QTreeWidgetItem::Type + \code + void myMsgHandler(QtMsgType, const char *); + \ endcode - The default type for tree widget items. + \sa QtMsgType, qInstallMsgHandler() + * / + \endcode - \sa UserType, type() - * / - \endcode + QDoc includes this in \c {qtglobal.html} as: - and + \quotation + \raw HTML + <h3>typedef QtMsgHandler</h3> + \endraw - \code - / *! - \variable QTreeWidgetItem::UserType + This is a typedef for a pointer to a function with the + following signature: - The minimum value for custom types. Values below - UserType are reserved by Qt. + \raw HTML + <tt> + <pre> void myMsgHandler(QtMsgType, const char *);</pre> + </tt> + \endraw - \sa Type, type() - * / - \endcode + See also QtMsgType and qInstallMsgHandler(). + \endquotation - will be rendered as + Other typedefs are located on the reference page for the class + that defines them. - \quotation - \raw HTML - <h3> - const int QTreeWidgetItem::Type - </h3> - \endraw + \code + / *! + \typedef QLinkedList::Iterator - The default type for tree widget items. + Qt-style synonym for QList::iterator. + * / + \endcode - See also \l {QTreeWidgetItem::UserType}{UserType} and - \l {QTreeWidgetItem::type()}{type()}. + QDoc includes this one on the reference page for class QLinkedList as: - \raw HTML - <h3> - const int QTreeWidgetItem::UserType - </h3> - \endraw + \quotation + \raw HTML + <h3>typedef QLinkedList::Iterator</h3> + \endraw - The minimum value for custom types. Values below - UserType are reserved by Qt. + Qt-style synonym for QList::iterator. + \endquotation - See also \l {QTreeWidgetItem::Type}{Type} and - \l{QTreeWidgetItem::type()}{type()}. + \target variable-command + \section1 \\variable - \endquotation + The \\variable command is for documenting a class member variable + or a constant. The argument is the variable or constant name. The + \\variable command comment includes a \l {brief-command} {\\brief} + command. QDoc generates the documentation based on the text from + \\brief command. - in qtreewidget.html. - \endtable + The documentation will be located in the in the associated class, + header file or namespace documentation. + + In case of a member variable: + + \code + / *! + \variable QStyleOption::palette + \brief the palette that should be used when painting + the control + * / + \endcode + + QDoc includes this in qstyleoption.html as: + + \quotation + \raw HTML + <h3> + <a href="http://qt.nokia.com/doc/4.0/qpalette.html"> + QPalette + </a> + QStyleOption::palette + </h3> + \endraw + + This variable holds the palette that should be used + when painting the control. + \endquotation + + You can also document constants with the \\variable command. For + example, suppose you have the \c Type and \c UserType constants in + the QTreeWidgetItem class: + + \code + enum { Type = 0, UserType = 1000 }; + \endcode + + For these, the \\vaqriable command can be used this way: + + \code + / *! + \variable QTreeWidgetItem::Type + + The default type for tree widget items. + + \sa UserType, type() + * / + \endcode + \code + / *! + \variable QTreeWidgetItem::UserType + + The minimum value for custom types. Values below + UserType are reserved by Qt. + + \sa Type, type() + * / + \endcode + + QDoc includes these in qtreewidget.html as: + + \quotation + \raw HTML + <h3> + const int QTreeWidgetItem::Type + </h3> + \endraw + + The default type for tree widget items. + + See also \l {QTreeWidgetItem::UserType} {UserType} and \l + {QTreeWidgetItem::type()} {type()}. + + \raw HTML + <h3> + const int QTreeWidgetItem::UserType + </h3> + \endraw + + The minimum value for custom types. Values below + UserType are reserved by Qt. + + See also \l {QTreeWidgetItem::Type} {Type} and + \l{QTreeWidgetItem::type()} {type()}. + + \endquotation */ /*! - \page 14-qdoc-commands-contextualcommands.html - \previouspage Topical Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Navigation Commands - - \title Contextual Commands - - The contextual commands provide QDoc with information, that it - wouldn't figure out otherwise, about the documented object. For - example whether a class is thread-safe or not. - - These commands can appear anywhere within a QDoc comment. - - \section1 Alphabetical List - - \l {16-qdoc-commands-status.html#compat}{\\compat}, - \l {15-qdoc-commands-navigation.html#contentspage}{\\contentspage}, - \l {15-qdoc-commands-navigation.html#indexpage}{\\indexpage}, - \l {19-qdoc-commands-grouping.html#ingroup}{\\ingroup}, - \l {19-qdoc-commands-grouping.html#inmodule}{\\inmodule}, - \l {16-qdoc-commands-status.html#internal}{\\internal}, - \l {19-qdoc-commands-grouping.html#mainclass}{\\mainclass}, - \l {15-qdoc-commands-navigation.html#nextpage}{\\nextpage}, - \l {17-qdoc-commands-thread.html#nonreentrant}{\\nonreentrant}, - \l {16-qdoc-commands-status.html#obsolete}{\\obsolete}, - \l {18-qdoc-commands-relating.html#overload}{\\overload}, - \l {16-qdoc-commands-status.html#preliminary}{\\preliminary}, - \l {15-qdoc-commands-navigation.html#previouspage}{\\previouspage}, - \l {17-qdoc-commands-thread.html#reentrant}{\\reentrant}, - \l {18-qdoc-commands-relating.html#reimp}{\\reimp}, - \l {18-qdoc-commands-relating.html#relates}{\\relates}, - \l {15-qdoc-commands-navigation.html#startpage}{\\startpage}, - \l {17-qdoc-commands-thread.html#threadsafe}{\\threadsafe}, - \l {20-qdoc-commands-title.html#title}{\\title} + \page 14-qdoc-commands-contextcommands.html + \previouspage Topic Commands + \contentspage Table of Contents + \nextpage Document Navigation + + \title Context Commands + + The context commands provide information about the element being + documented that QDoc can't deduce on its own. e.g. Is a class + thread-safe? Is a function reentrant? Which module is the class a + member of? Context commands can appear anywhere in a QDoc comment, + but they are normally placed near the top of the comment, just + below the \l {Topic Commands} {topic} command. - \section1 Categories \list - \o \l {Navigation Commands} - \o \l {Status Commands} - \o \l {Thread Support Commands} - \o \l {Relating Commands} - \o \l {Grouping Commands} - \o \l {Title Commands} + \o \l {16-qdoc-commands-status.html#compat-command}{\\compat}, + \o \l {15-qdoc-commands-navigation.html#contentspage-command}{\\contentspage}, + \o \l {15-qdoc-commands-navigation.html#indexpage-command}{\\indexpage}, + \o \l {19-qdoc-commands-grouping.html#ingroup-command}{\\ingroup}, + \o \l {18-qdoc-commands-relating.html#inherits-command}{\\inherits}, + \o \l {19-qdoc-commands-grouping.html#inmodule-command}{\\inmodule}, + \o \l {16-qdoc-commands-status.html#internal-command}{\\internal}, + \o \l {19-qdoc-commands-grouping.html#mainclass-command}{\\mainclass}, + \o \l {15-qdoc-commands-navigation.html#nextpage-command}{\\nextpage}, + \o \l {17-qdoc-commands-thread.html#nonreentrant-command}{\\nonreentrant}, + \o \l {16-qdoc-commands-status.html#obsolete-command}{\\obsolete}, + \o \l {18-qdoc-commands-relating.html#overload-command}{\\overload}, + \o \l {16-qdoc-commands-status.html#preliminary-command}{\\preliminary}, + \o \l {15-qdoc-commands-navigation.html#previouspage-command}{\\previouspage}, + \o \l {17-qdoc-commands-thread.html#reentrant-command}{\\reentrant}, + \o \l {18-qdoc-commands-relating.html#reimp-command}{\\reimp}, + \o \l {18-qdoc-commands-relating.html#relates-command}{\\relates}, + \o \l {16-qdoc-commands-status.html#since-command}{\\since}, + \o \l {15-qdoc-commands-navigation.html#startpage-command}{\\startpage}, + \o \l {20-qdoc-commands-namingthings.html#subtitle-command}{\\subtitle} + \o \l {17-qdoc-commands-thread.html#threadsafe-command}{\\threadsafe}, + \o \l {20-qdoc-commands-namingthings.html#title-command}{\\title} \endlist + */ /*! \page 15-qdoc-commands-navigation.html - \previouspage Contextual Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Status Commands - - \title Navigation Commands - - The navigation commands allow you to link the pages of a multipage - document together. They provide the components of a navigation bar - at the top and bottom of the document. They also provide browser - and search engine support. + \previouspage Context Commands + \contentspage Table of Contents + \nextpage Reporting Status - \section1 Alphabetical List + \title Document Navigation - \l {15-qdoc-commands-navigation.html#contentspage}{\\contentspage}, - \l {15-qdoc-commands-navigation.html#indexpage}{\\indexpage}, - \l {15-qdoc-commands-navigation.html#nextpage}{\\nextpage}, - \l {15-qdoc-commands-navigation.html#previouspage}{\\previouspage}, - \l {15-qdoc-commands-navigation.html#startpage}{\\startpage} + The navigation commands are for linking the pages of a document in + a meaningful sequence. Below is a sequence of QDoc comments that + shows a typical use of the navigation commands. - \section1 General Description - - The QDoc comments below shows a typical example using the - navigation commands. + \section1 Example \code / *! \page basicqt.html - \contentspage {Basic Qt}{Contents} + \contentspage {Basic Qt} {Contents} \nextpage Getting Started \indexpage Index @@ -5885,7 +5706,7 @@ / *! \page gettingstarted.html \previouspage Basic Qt - \contentspage {Basic Qt}{Contents} + \contentspage {Basic Qt} {Contents} \nextpage Creating Dialogs \indexpage Index @@ -5901,7 +5722,7 @@ / *! \page creatingdialogs.html \previouspage Getting Started - \contentspage {Basic Qt}{Contents} + \contentspage {Basic Qt} {Contents} \indexpage Index \startpage Basic Qt @@ -5927,8 +5748,7 @@ * / \endcode - The second page of this multipage document, "Getting Started", - will be rendered as + QDoc renders the "Getting Started" page in \c{creatingdialogs.html}: \quotation \raw HTML @@ -5963,18 +5783,16 @@ \endraw \endquotation - in creatingdialogs.html. - - In addition, the \l {indexpage}{\\indexpage} and \l - {startpage}{\\startpage} commands specifies links to the page's - index page and start page. These links are used by browsers and - search engines. + The \l {indexpage-command} {\\indexpage} and \l + {startpage-command} {\\startpage} commands create links to the + page's index page and start page. These links can be used by + browsers and search engines. The index page is typically an alphabetical list of the document's titles and topics, while the start page is the page considered by the author to be the starting point of a multipage document. - The links are included in the generated HTML source code but has + The links are included in the generated HTML source code but have no visual effect on the documentation: \code @@ -5986,414 +5804,377 @@ </head> \endcode - \section1 Command Descriptions - - \table - \header - \o Command - \o Description - - \row - \o \bold \\previouspage \target previouspage - \o \bold {The \\previouspage command links the current page - to the previous one in an ordered series of documents}. - - The command has two arguments, each enclosed by curly - braces: The first is the link target, i.e. the title of the - previous page, the second is the link text. If the page's - title is equivalent to the link text, the second argument - can be omitted. - - The command must stand alone on its own line. - - In the end, the link is rendered at the top and bottom of - the current page. For an example, see the \l {General - Description} section. + \section1 Commands - \row - \o \bold \\nextpage \target nextpage - \o \bold {The \\nextpage command links the current - page to the next page in an ordered series of documents}. - - The command follows the same syntax and argument convention - as the \l {previouspage}{\\previouspage} command. + \target previouspage-command + \section2 \\previouspage - For an example, see the \l {General Description} section. - - \row - \o \bold \\startpage \target startpage - \o \bold {The \\startpage command specifies the first document - in a collection of documents.} + The \\previouspage command links the current page to the previous + page in a sequence.a The command has two arguments, each enclosed + by curly braces: The first is the link target, i.e. the title of + the previous page, the second is the link text. If the page's + title is equivalent to the link text, the second argument can be + omitted. - The command must stand alone on its own line, and its - unique argument is the title of the first document. + The command must stand alone on its own line. - QDoc will generate a link to the specified document which - is included in the HTML file but has no visual effect on - the documentation. The generated link type tells browsers - and search engines which document is considered by the - author to be the starting point of the collection. + \target nextpage-command + \section2 \\nextpage - For an example, see the \l {General Description} section. + The \\nextpage command links the current page to the next page in + a sequence. The command follows the same syntax and argument + convention as the \l {previouspage-command} {\\previouspage} + command. - \row - \o \bold \\contentspage \target contentspage - \o \bold {The \\contentspage command links the current - page to a contents page}. + \target startpage-command + \section2 \\startpage - The command follows the same syntax and argument convention - as the \l {previouspage}{\\previouspage} command. + The \\startpage command specifies the first page of a sequence of + pages. The command must stand alone on its own line, and its + unique argument is the title of the first document. - For an example, see the \l {General Description} section. + QDoc will generate a link to the start page and include it in the + generated HTML file, but this has no visual effect on the + documentation. The generated link type tells browsers and search + engines which document is considered by the author to be the + starting point of the collection. - \row - \o \bold \\indexpage \target indexpage - \o \bold {The \\indexpage command specifies a document providing - an index for the current document}. + \target contentspage-command + \section2 \\contentspage - The command must stand alone on its own line, and its - unique argument is the title of the index document. + The \\contentspage command links the current page to a table of + contents page. The command follows the same syntax and argument + convention as the \l {previouspage-command} {\\previouspage} + command. - QDoc will generate a link to the specified document which - is included in the HTML file but has no visual effect on - the documentation. The generated link type tells browsers - and search engines which document is considered by the - author to be the index page for the current document. + \target indexpage-command + \section2 \\indexpage - For an example, see the \l {General Description} section. + The \\indexpage command specifies an index page for the current + document. The command must stand alone on its own line, and its + unique argument is the title of the index document. - \endtable + QDoc will generate a link to the index page and include it in the + generated HTML file, but this has no visual effect on the + documentation. The generated link type tells browsers and search + engines which document is considered by the author to be the + index page of the collection. */ /*! \page 16-qdoc-commands-status.html - \previouspage Navigation Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Thread Support Commands - - \title Status Commands + \previouspage Document Navigation + \contentspage Table of Contents + \nextpage Thread Support - The usage commands can indicate whether a documented object is - under development, becoming obsolete, provided for compatibility - reasons or simply not part of the public interface. They can - describe the history of minor versions. And they can also describe - a documented object's ability to handle multithreaded programming. + \title Reporting Status - \section1 Alphabetical List + These commands are for indicating that a documented element is + still under development, is becoming obsolete, is provided for + compatibility reasons, or is simply not to be included in the + public interface. The \l {since-command}{\\since} command is for + including information about the version when a function or class + first appeared. - \l {16-qdoc-commands-status.html#compat}{\\compat}, - \l {16-qdoc-commands-status.html#internal}{\\internal}, - \l {16-qdoc-commands-status.html#obsolete}{\\obsolete}, - \l {16-qdoc-commands-status.html#preliminary}{\\preliminary}, - \l {16-qdoc-commands-status.html#since}{\\since} + \target compat-command + \section1 \\compat - \section1 Command Description + The \\compat command is for indicating that a class or function is + part of the support library provided to keep old source code + working. - \table - \header - \o Command - \o Description - - \row - \o \bold \\preliminary \target preliminary - \o \bold {The \\preliminary command indicates that the - referenced function is under development.} - - The command must stand on its own line. + The command must stand on its own line. - The \\preliminary command expands to a notification in the - function documentation, and marks the function as - preliminary when it appears in lists. For example: - - \code - / *! - \preliminary + Usually an equivalent function or class is provided as an + alternative. - Returns information about the joining properties of the - character (needed for certain languages such as - Arabic). - * / - QChar::Joining QChar::joining() const - { - return ::joining(*this); - } - \endcode + If the command is used in the documentation of a class, the + command expands to a warning that the referenced class is part of + the support library. The warning is located at the top of the + documentation page. - will be rendered as + \code + / *! + \class MyQt3SupportClass + \compat + * / + \endcode - \quotation - \raw HTML - <h3> - <a href="http://qt.nokia.com/doc/4.0/qchar.html#Joining-enum">Joining</a> - QChar::joining () const</h3> - \endraw + QDoc renders this at the top of the MyQt3SupportClass class + reference page. - \bold {This function is under development and - is subject to change.} + \quotation + \bold {This class is part of the Qt 3 support + library.} It is provided to keep old source code + working. We strongly advise against using it in new + code. See the \l + {http://qt.nokia.com/doc/4.0/porting4.html} {Porting + Guide} for more information. + \endquotation - Returns information about the joining properties of the - character (needed for certain languages such as - Arabic). - \endquotation + If the command is used when documenting a function, QDoc will + create and link to a separate page documenting Qt 3 support + members when generating the reference documentation for the + associated class. - And the function's entry in QChar's list of functions will - be rendered as + \code + / *! + \fn MyClass::MyQt3SupportMemberFunction + \compat - \quotation - \list - \o ... - \o Joining - \l {http://qt.nokia.com/doc/4.0/qchar.html#Joining-enum} - {joining}() - const \c (preliminary) - \o ... - \endlist - \endquotation + Use MyNewFunction() instead. + * / + \endcode - \row - \o \bold \\obsolete \target obsolete - \o \bold {The \\obsolete command indicates that the referenced - function no longer should be used in new code; - there is no guarantee for how long it will remain in - the library.} + QDoc renders this in \c{myclass-qt3.html} as: - The command must stand on its own line. + \quotation + \raw HTML + <h1>Qt 3 Support Members for MyClass</h1> + \endraw - When generating the reference documentation for a class, - QDoc will create and link to a separate page documenting - its obsolete functions. Usually an equivalent function is - provided as an alternative. + \bold {The following class members are part of the Qt 3 + support layer.} They are provided to help you port old code to + Qt 4. We advise against using them in new code. - For example: + ... - \code - / *! - \fn MyClass::MyObsoleteFunction - \obsolete + \list + \o void MyQt3SupportMemberFunction() + \o ... + \endlist - Use MyNewFunction() instead. - * / - \endcode + \raw HTML + <hr /> + <h2>Member Function Documentation</h2> + <h3>void MyQt3SupportMemberFunction ()</h3> + <p>Use MyNewFunction() instead.</p> + \endraw + ... + \endquotation - will be rendered as + \target default-command + \section1 \\default \span {class="newStuff"} {(new)} - \quotation - \raw HTML - <h1>Obsolete Members for MyClass</h1> - \endraw + The \\default command is for marking a QML property as the + \l {http://doc.trolltech.com/4.7/qdeclarativeintroduction.html#default-properties} + {default property}. The word \span {class="newStuff"} {default} is shown in red in + the documentation of the property. - \bold {The following class members are obsolete.} They - are provided to keep old source code working. We - strongly advise against using them in new code. + \code + / *! + \qmlproperty list<Change> State::changes + This property holds the changes to apply for this state + \default - ... + By default these changes are applied against the default state. If the state + extends another state, then the changes are applied against the state being + extended. + * / + \endcode - \list - \o void MyObsoleteFunction() \c (obsolete) - \o ... - \endlist + See how QDoc renders this property on the reference page for the + \l {http://doc.trolltech.com/4.7/qml-state.html#changes-prop} {State} + element. - \raw HTML - <hr /> - <h2>Member Function Documentation</h2> - <h3>void MyObsoleteFunction ()</h3> - <p>Use MyNewFunction() instead.</p> - \endraw + \target obsolete-command + \section1 \\obsolete - ... - \endquotation + The \\obsolete command is for indicating that a function is being + deprecated, and it should no longer be used in new code. There is + no guarantee for how long it will remain in the library. - in myclass-obsolete.html + The command must stand on its own line. + When generating the reference documentation for a class, QDoc will + create and link to a separate page documenting its obsolete + functions. Usually an equivalent function is provided as an + alternative. - \row - \o \bold \\compat \target compat - \o \bold {The \\compat command indicates that the referenced class - or function is part of the support library provided to keep - old source code working.} + \code + / *! + \fn MyClass::MyObsoleteFunction + \obsolete - The command must stand on its own line. + Use MyNewFunction() instead. + * / + \endcode - Usually an equivalent function or class is provided as an - alternative. + QDoc renders this in \c{myclass-obsolete.html} as: - If the command is used within the documentation of a class, - the command expands to a warning that the referenced class - is part of the support library. The warning is located on - top of the associated documentation. For example: + \quotation + \raw HTML + <h1>Obsolete Members for MyClass</h1> + \endraw - \code - / *! - \class MyQt3SupportClass - \compat - * / - \endcode + \bold {The following class members are obsolete.} They are + provided to keep old source code working. We strongly advise + against using them in new code. - will be rendered as + ... - \quotation - \bold {This class is part of the Qt 3 support - library.} It is provided to keep old source code - working. We strongly advise against using it in new - code. See the \l - {http://qt.nokia.com/doc/4.0/porting4.html}{Porting - Guide} for more information. - \endquotation + \list + \o void MyObsoleteFunction() \c (obsolete) + \o ... + \endlist - on the top of the MyQt3SupportClass class reference. + \raw HTML + <hr /> + <h2>Member Function Documentation</h2> + <h3>void MyObsoleteFunction ()</h3> + <p>Use MyNewFunction() instead.</p> + \endraw + ... + \endquotation - If the command is used when documenting a function, QDoc - will create and link to a separate page documenting Qt 3 - support members when generating the reference documentation - for the associated class. For example: + \target internal-command + \section1 \\internal - \code - / *! - \fn MyClass::MyQt3SupportMemberFunction - \compat + The \\internal command indicates that the referenced + function is not part of the public interface. - Use MyNewFunction() instead. - * / - \endcode + The command must stand on its own line. - will be rendered as + QDoc ignores the documentation as well as the documented item, + when generating the associated class reference documenation. - \quotation - \raw HTML - <h1>Qt 3 Support Members for MyClass</h1> - \endraw + \code + / *! + \internal - \bold {The following class members are part of the Qt - 3 support layer.} They are provided to help you port - old code to Qt 4. We advise against using them in new - code. + Tries to find the decimal separator. If it can't find + it and the thousand delimiter is != '.' it will try to + find a '.'; + * / + int QDoubleSpinBoxPrivate::findDelimiter + (const QString &str, int index) const + { + int dotindex = str.indexOf(delimiter, index); + if (dotindex == -1 && thousand != dot && delimiter != dot) + dotindex = str.indexOf(dot, index); + return dotindex; + } + \endcode - ... + This function will not be included in the documentation. - \list - \o void MyQt3SupportMemberFunction() - \o ... - \endlist + \target preliminary-command + \section1 \\preliminary - \raw HTML - <hr /> - <h2>Member Function Documentation</h2> - <h3>void MyQt3SupportMemberFunction ()</h3> - <p>Use MyNewFunction() instead.</p> - \endraw + The \\preliminary command is for indicating that a referenced + function is still under development. - ... - \endquotation + The command must stand on its own line. - in myclass-qt3.html + The \\preliminary command expands to a notification in the + function documentation, and marks the function as preliminary when + it appears in lists. + \code + / *! + \preliminary - \row - \o \bold \\internal \target internal - \o \bold {The \\internal command indicates that the referenced - function is not part of the public interface.} + Returns information about the joining properties of the + character (needed for certain languages such as + Arabic). + * / + QChar::Joining QChar::joining() const + { + return ::joining(*this); + } + \endcode - The command must stand on its own line. + QDoc renders this as: - QDoc ignores the documentation as well as the documented - item, when generating the associated class reference - documenation. For example: + \quotation + \raw HTML + <h3> + <a href="http://qt.nokia.com/doc/4.0/qchar.html#Joining-enum">Joining</a> + QChar::joining () const</h3> + \endraw - \code - / *! - \internal + \bold {This function is under development and + subject to change.} - Tries to find the decimal separator. If it can't find - it and the thousand delimiter is != '.' it will try to - find a '.'; - * / - int QDoubleSpinBoxPrivate::findDelimiter - (const QString &str, int index) const - { - int dotindex = str.indexOf(delimiter, index); - if (dotindex == -1 && thousand != dot && delimiter != dot) - dotindex = str.indexOf(dot, index); - return dotindex; - } - \endcode + Returns information about the joining properties of the + character (needed for certain languages such as + Arabic). + \endquotation - in qspinbox.cpp, will not be rendered at all. + And the function's entry in QChar's list of functions will be + rendered as: - \row - \o \bold \\since \target since - \o \bold {The \\since command tells in which minor release - the associated functionality was added.} + \quotation + \list + \o ... + \o Joining + \l {http://qt.nokia.com/doc/4.0/qchar.html#Joining-enum} + {joining}() + const \c (preliminary) + \o ... + \endlist + \endquotation - For example: + \target since-command + \section1 \\since - \code - / *! - \since 4.1 + The \\since command tells in which minor release + the associated functionality was added. - Returns an icon for \a standardIcon. + \code + / *! + \since 4.1 - ... + Returns an icon for \a standardIcon. - \sa standardIconImplementation(), standardPixmap() - * / - QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const - { - } - \endcode + ... - will be rendered as + \sa standardIconImplementation(), standardPixmap() + * / + QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const + { + } + \endcode - \quotation - \raw HTML - <h3>QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const</h3> - \endraw + QDoc renders this as: - This function was introduced in Qt version 4.1 + \quotation + \raw HTML + <h3>QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const</h3> + \endraw - Returns an icon for \a standardIcon. + This function was introduced in Qt version 4.1 - ... + Returns an icon for \a standardIcon. - See also \l - {QStyle::standardIconImplementation()}{standardIconImplementation()} - and \l {QStyle::standardPixmap()}{standardPixmap()}. - \endquotation + ... - QDoc generates the "Qt" reference from the \l - {25-qdoc-configuration-derivedprojects.html#project}{\c - project} configuration variable. For that reason this - reference will change according to the current - documentation project. + See also \l {QStyle::standardIconImplementation()} + {standardIconImplementation()} and \l + {QStyle::standardPixmap()} {standardPixmap()}. + \endquotation - See also \l - {25-qdoc-configuration-derivedprojects.html#project}{\c - project}. + QDoc generates the "Qt" reference from the \l + {25-qdoc-configuration-derivedprojects.html#project} {\c project} + configuration variable. For that reason this reference will change + according to the current documentation project. - \endtable + See also \l {25-qdoc-configuration-derivedprojects.html#project} + {\c project}. */ /*! \page 17-qdoc-commands-thread.html - \previouspage Status Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Relating Commands - - \title Thread Support Commands - - The thread support commands specify the level of support for - multithreaded programming of a class or function. - - \section1 Alphabetical List - - \l {17-qdoc-commands-thread.html#nonreentrant}{\\nonreentrant}, - \l {17-qdoc-commands-thread.html#reentrant}{\\reentrant}, - \l {17-qdoc-commands-thread.html#threadsafe}{\\threadsafe} + \previouspage Reporting Status + \contentspage Table of Contents + \nextpage Relating Things - \section1 General Description + \title Thread Support - There are three levels of support for multithreaded programming of - a class or function: \c threadsafe, \c reentrant and \c - nonreentrant. + The thread support commands are for specifying the level of + support for multithreaded programming in a class or function. + There are three levels of support: \c threadsafe, \c reentrant and + \c nonreentrant. The default is \c nonreentrant which means that the associated class or function cannot be called by multiple threads. \c @@ -6406,15 +6187,14 @@ can be called simultaneously by multiple threads even when each invocation references shared data. - When a class is declared \c reentrant or \c threadsafe, using the - \l {reentrant}{\\reentrant} and \l {threadsafe}{\\threadsafe} - commands respectively, functions in the referenced class can be - declared \c nonreentrant, using the \l - {nonreentrant}{\\nonreentrant} command, excluding the functions - from the general view. + When a class is marked \l {reentrant-command} {\\reentrant} or \l + {threadsafe-command} {\\threadsafe}, functions in that class can + be marked \c nonreentrant using the \l {nonreentrant-command} + {\\nonreentrant} command. - For example: + \section1 Example + \target reentrant-example \code / *! \class QLocale @@ -6453,7 +6233,7 @@ } \endcode - will be rendered as + QDoc renders this as: \quotation \raw HTML @@ -6468,8 +6248,8 @@ \endcode \bold {Note:} All the functions in this class are \l - {threads.html#reentrant}{reentrant}, except \l - {QLocale::setDefault()}{setDefault()}. + {threads.html#reentrant} {reentrant}, except \l + {QLocale::setDefault()} {setDefault()}. ... @@ -6495,8 +6275,8 @@ \warning This function is not reentrant. - See also \l {QLocale::system()}{system()} and \l - {QLocale::c()}{c()}. + See also \l {QLocale::system()} {system()} and \l + {QLocale::c()} {c()}. ... \endquotation @@ -6504,7 +6284,7 @@ As shown above, QDoc generates a notification when a class is declared reentrant, and lists the exceptions (the declared nonreentrant functions). A link to the general documentation on \l - {threads.html#reentrant}{reentrancy and thread-safety} is + {threads.html#reentrant} {reentrancy and thread-safety} is included. In addition a warning, "\bold Warning: This function is not reentrant.", is generated in the nonreentrant functions' documentation. @@ -6513,477 +6293,469 @@ is declared threadsafe. For more information see the general documentation on \l - {threads.html#reentrant}{reentrancy and thread-safety}. + {threads.html#reentrant} {reentrancy and thread-safety}. - \section1 Command Descriptions + \section1 Commands - \table - \header - \o Command - \o Description + \target threadsafe-command + \section2 \\threadsafe - \row - \o \bold \\threadsafe \target threadsafe - \o \bold {The \\threadsafe command indicates that the - associated class or function can be called simultaneously by - multiple threads even when each invocation references - shared data.} + The \\threadsafe command includes a line in the documentation to + indicate that the associated class or function is \e threadsafe + and can be called simultaneously by multiple threads, even when + separate invocations reference shared data. - The command must stand on its own line. + The command must stand on its own line. - The generated documentation resulting from using the - \\threadsafe command is similar to the result of using the - \l {reentrant}{\\reentrant} command. For an example, see - the \l {General Description} section. + The documentation generated from this command will be similar to + the what is generated for the \l {reentrant-command} {\\reentrant} + command. See the example above in the \l {reentrant-example} + {introduction}. - See also \l{reentrant}{\\reentrant} and - \l{nonreentrant}{\\nonreentrant}. + See also \l{reentrant-command} {\\reentrant} and + \l{nonreentrant-command} {\\nonreentrant}. - \row - \o \bold \\reentrant \target reentrant - \o \bold {The \\reentrant command indicates that the associated - class or function can be called simultaneously - by multiple threads, provided that each invocation of the - functions reference unique data.} + \target reentrant-command + \section2 \\reentrant - The command must stand on its own line. + The \\reentrant command indicates that the associated class or + function can be called simultaneously by multiple threads, + provided that each invocation references its own data. See the \l + {reentrant-example} {example} above. - For an example, see the \l {General Description} section. + The command must stand on its own line. - See also \l{nonreentrant}{\\nonreentrant} and - \l{threadsafe}{\\threadsafe}. + See also \l{nonreentrant-command} {\\nonreentrant} and + \l{threadsafe-command} {\\threadsafe}. - \row - \o \bold \\nonreentrant \target nonreentrant - \o \bold {The \\nonreentrant command indicates that the - associated class or function cannot be called by - multiple threads.} + \target nonreentrant-command + \section2 \\nonreentrant - The command must stand on its own line. + The \\nonreentrant command indicates that the associated class or + function cannot be called by multiple threads. Nonreentrant is the + default case. - For an example, see the \l {General Description} section. + The command must stand on its own line. - See also \l{reentrant}{\\reentrant} and - \l{threadsafe}{\\threadsafe}. + When a class is marked \l {reentrant-command} {\\reentrant} or \l + {threadsafe-command} {\\threadsafe}, functions in that class can + be marked \c nonreentrant using this command in the \l{fn-command} + {\\fn} comment of the functions to be excluded. - \endtable + See also \l{reentrant-command} {\\reentrant} and + \l{threadsafe-command} {\\threadsafe}. */ /*! \page 18-qdoc-commands-relating.html - \previouspage Thread Support Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Grouping Commands + \previouspage Thread Support + \contentspage Table of Contents + \nextpage Grouping Things - \title Relating Commands + \title Relating Things - The relation commands discribe how the documented object relates - to its context: Whether it is an overloaded function, a - reimplemented function or a global function related to a specified - class or header file. + The relating commands are for specifying how one documented + element relates to another documented element. e.g., This function + is an overload of another function, or this function is a + reimplementation of another function, or this typedef is \e + related to some class or header file. There is also a command + for documenting that a QML element inherits some other QML + element. - \section1 Alphabetical List + \section1 Commands - \l {18-qdoc-commands-relating.html#overload}{\\overload}, - \l {18-qdoc-commands-relating.html#reimp}{\\reimp}, - \l {18-qdoc-commands-relating.html#relates}{\\relates}, + \target inherits-command + \section2 \\inherits \span {class="newStuff"} {(new)} - \section1 Command Descriptions + The \\inherits command is for documenting that one QML element + inherits some other QML element. It must be included in the + inheriting element's \l{qmlclass-command}{\\qmlclass} comment. + The argument is the name of the inherited QML element. - \table - \header - \o Command - \o Description + \code + / *! + \qmlclass PauseAnimation QDeclarativePauseAnimation + \ingroup qml-animation-transition + \since 4.7 + \inherits Animation + \brief The PauseAnimation element provides a pause for an animation. - \row - \o \bold \\overload \target overload - \o \bold {The \\overload command indicates that the - function is a secondary overload of its name.} + When used in a SequentialAnimation, PauseAnimation is a step + when nothing happens, for a specified duration. - The command must stand on its own line. + A 500ms animation sequence, with a 100ms pause between two animations: - For any overloaded function (except constructors), QDoc - expects one primary version of the function and all the - the overloads marked with the \bold{\\overload command}. - The primary version should be fully documented. Each - overload can have whatever extra documentation you want - to add for just that overload. + SequentialAnimation { + NumberAnimation { ... duration: 200 } + PauseAnimation { duration: 100 } + NumberAnimation { ... duration: 200 } + } - From Qt 4.5, you can include the function name plus '()' - as a parameter to the \bold{\\overload} command, which - will include a standard \i{This function overloads...} - line of text with a link to the documentation for the - primary version of the function. + \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} + * / + \endcode - For example: + QDoc includes this line on the reference page for the + \l{http://doc.trolltech.com/4.7/qml-pauseanimation.html} {PauseAnimation} + element: - \code - / *! - \overload addAction() + \quotation + Inherits \l{http://doc.trolltech.com/4.7/qml-animation.html} {Animation} + \endquotation - This convenience function creates a new action with an - \a icon and some \a text. The function adds the newly - created action to the menu's list of actions, and - returns it. + \target overload-command + \section2 \\overload - \sa QWidget::addAction() - * / - QAction *QMenu::addAction(const QIcon &icon, const QString &text) - { - QAction *ret = new QAction(icon, text, this); - addAction(ret); - return ret; - } - \endcode + The \\overload command is for indicating that a function is a + secondary overload of its name. - will be rendered as + The command must stand on its own line. - \quotation - \raw HTML - <h3><a href="http://qt.nokia.com/doc/4.0/qaction.html">QAction</a> - * QMenu::addAction ( const QIcon & <i>icon</i>, - const QString & <i>text</i> ) - </h3> - \endraw + For a function name that is overloaded (except constructors), QDoc + expects one primary version of the function, and all the others + marked with the \bold {\\overload command}. The primary version + should be fully documented. Each overload can have whatever extra + documentation you want to add for just that overloaded version. - This function overloads \l {http://qt.nokia.com/doc/4.0/qwidget.html#addAction}{addAction()} + From Qt 4.5, you can include the function name plus '()' as a + parameter to the \bold{\\overload} command, which will include a + standard \e{This function overloads...} line of text with a link + to the documentation for the primary version of the function. - This convenience function creates a new action with an - \i icon and some \i text. The function adds the newly - created action to the menu's list of actions, and - returns it. + \code + / *! + \overload addAction() - See also - \l {http://qt.nokia.com/doc/4.0/qwidget.html#addAction} - {QWidget::addAction}(). - \endquotation + This convenience function creates a new action with an + \a icon and some \a text. The function adds the newly + created action to the menu's list of actions, and + returns it. - If you don't include the function name with the - \bold{\\overlaod} command, then instead of the "This - function overloads..." line with the link to the - documentation for the primary version, you get the old - standard line: + \sa QWidget::addAction() + * / + QAction *QMenu::addAction(const QIcon &icon, const QString &text) + { + QAction *ret = new QAction(icon, text, this); + addAction(ret); + return ret; + } + \endcode - \quotation - This is an overloaded member function, provided for - convenience. - \endquotation. + QDoc renders this as: - \row - \o \bold \\reimp \target reimp - \o \bold {The \\reimp command indicates that the - referenced function is a reimplementation of a virtual function, - where the reimplementation has no effect on the interface.} + \quotation + \raw HTML + <h3><a href="http://qt.nokia.com/doc/4.0/qaction.html">QAction</a> + * QMenu::addAction ( const QIcon & <i>icon</i>, + const QString & <i>text</i> ) + </h3> + \endraw - The command must stand on its own line. + This function overloads \l {http://qt.nokia.com/doc/4.0/qwidget.html#addAction} {addAction()} - QDoc will omit the reimplemented function from the class - reference. For example: + This convenience function creates a new action with an + \e icon and some \e text. The function adds the newly + created action to the menu's list of actions, and + returns it. - \code - / *! - \reimp - * / - void QToolButton::nextCheckState() - { - Q_D(QToolButton); - if (!d->defaultAction) - QAbstractButton::nextCheckState(); - else - d->defaultAction->trigger(); - } - \endcode + See also + \l {http://qt.nokia.com/doc/4.0/qwidget.html#addAction} + {QWidget::addAction}(). + \endquotation - will not be rendered at all; only a link to the inherited - QAbstractButton::nextCheckState() will appear in the - documentation. + If you don't include the function name with the \bold{\\overlaod} + command, then instead of the "This function overloads..." line + with the link to the documentation for the primary version, you + get the old standard line: - \row - \o \bold \\relates \target relates - \o \bold {The \\relates command attaches the documentation of - a global function to that of a related class or header file.} + \quotation + This is an overloaded member function, provided for + convenience. + \endquotation. - The command's argument is a class name, an the command (and - its argument) must stand on its own line. + \target reimp-command + \section2 \\reimp - \code - / *! - \relates QChar + The \\reimp command is for indicating that a function is a + reimplementation of a virtual function. - Reads a char from the stream \a in into char \a chr. + The command must stand on its own line. - \sa {Format of the QDataStream operators} - * / - QDataStream &operator>>(QDataStream &in, QChar &chr) - { - quint16 u; - in >> u; - chr.unicode() = ushort(u); - return in; - } - \endcode + QDoc will omit the reimplemented function from the class + reference. + + \code + / *! + \reimp + * / + void QToolButton::nextCheckState() + { + Q_D(QToolButton); + if (!d->defaultAction) + QAbstractButton::nextCheckState(); + else + d->defaultAction->trigger(); + } + \endcode - will be rendered with the QChar documentation. + This function will not be included in the documentation. Instead, + a link to the base function QAbstractButton::nextCheckState() will + appear in the documentation. - \endtable + \target relates-command + \section2 \\relates + + The \\relates command is for including the documentation of a + global element to some class or header file. The argument is a + class name or header file. + + \code + / *! + \relates QChar + + Reads a char from the stream \a in into char \a chr. + + \sa {Format of the QDataStream operators} + * / + QDataStream &operator>>(QDataStream &in, QChar &chr) + { + quint16 u; + in >> u; + chr.unicode() = ushort(u); + return in; + } + \endcode + + The documentation for this function will be included on the reference page + for class QChra. */ /*! \page 19-qdoc-commands-grouping.html - \previouspage Relating Commands - \contentspage QDoc Manual - Table of Contents - \nextpage Title Commands + \previouspage Relating Things + \contentspage Table of Contents + \nextpage Naming Things - \title Grouping Commands + \title Grouping Things The grouping commands relate classes to defined groups and modules. The groups are used when generating lists of related classes in the documentation, while the modules are elements of Qt's structure. - \section1 Alphabetical List + \section1 Commands - \l {19-qdoc-commands-grouping.html#ingroup}{\\ingroup}, - \l {19-qdoc-commands-grouping.html#inmodule}{\\inmodule}, - \l {19-qdoc-commands-grouping.html#mainclass}{\\mainclass}, + \target mainclass-command + \section2 \\mainclass - \section1 Command Descriptions + The \\mainclass command relates the documented class to + a group called mainclasses. - \table - \header - \o Command - \o Description + The command must stand on its own line. - \row - \o \bold \\mainclass \target mainclass - \o \bold {The \\mainclass command relates the documented class to - a group called mainclasses.} + \code + / *! + \class QWidget qwidget.h + \brief The QWidget class is the base class of + all user interface objects. - The command must stand on its own line. + \mainclass - For example: + ... + * / + \endcode - \code - / *! - \class QWidget qwidget.h - \brief The QWidget class is the base class of - all user interface objects. + This will include the QWidget class in the \e mainclasses + group, which means, for example, that the class will appear on the + list created by calling the \l {generatelist-command} + {\\generatelist} command with the \c mainclasses argument: - \mainclass + \l http://qt.nokia.com/doc/4.0/mainclasses.html - ... - * / - \endcode + \note The Qt documentation no longer includes the \e mainclasses + page. - will ensure that the QWidget class is included in the \c - mainclasses group, which means, for example, that the class - will appear on the list created by calling the \l - {generatelist}{\\generatelist} command with the \c - mainclasses argument: + See also \l {generatelist-command} {\\generatelist}. - \l http://qt.nokia.com/doc/4.0/mainclasses.html + \target ingroup-command + \section2 \\ingroup - See also \l {generatelist}{\\generatelist}. + The \\ingroup command indicates that the given + overview or documented class belongs to a certain group of + related docmentation. - \row - \o \bold \\ingroup \target ingroup + A class or overview may belong to many groups. - \o \bold {The \\ingroup command indicates that the given - overview or documented class belongs to a certain group of - related docmentation.} + The \\ingroup command's argument is a group name, but note + that the command considers the rest of the line as part of + its argument. Make sure that the group name is followed by + a linebreak. - A class or overview may belong to many groups. + \code + / *! + \class QDir + \brief The QDir class provides access to directory + structures and their contents. - The \\ingroup command's argument is a group name, but note - that the command considers the rest of the line as part of - its argument. Make sure that the group name is followed by - a linebreak. For example: + \ingroup io + ... + * / + \endcode - \code - / *! - \class QDir - \brief The QDir class provides access to directory - structures and their contents. + This will include the QDir class in the \c io group, which means, + for example, that QDir will appear on the list created by calling + the \l {group-command} {\\group} command with the \c io argument. - \ingroup io - ... - * / - \endcode + To list overviews that are related to a certain group, you must + generate the list explicitly using the \l {generatelist-command} + {\\generatelist} command with the \c related argument. - will ensure that the QDir class is included in the \c io - group, which means, for example, that QDir will appear on - the list created by calling the \l {group}{\\group} command - with the \c io argument. + See also \l {group-command} {\\group}. - Note that to list overviews that are related to a given - group, you must generate the list exlicitly by using the \l - {generatelist}{\\generatelist} command with the \c related - argument. + \target inmodule-command + \section2 \\inmodule - See also \l {group}{\\group}. - \row - \o \bold \\inmodule \target inmodule - \o \bold {The \\inmodule command relates the documented class - to the module specified by the command's argument.} + The \\inmodule command relates a class to the module specified by + the command's argument. - For the basic classes in Qt, a class's module is determined - by its location, i.e. its directory. However, for - extensions, like ActiveQt and Qt Designer, a class needs to - be related to a module explicitly. + For the basic classes in Qt, a class's module is determined by its + location, i.e. its directory. However, for extensions, like + ActiveQt and Qt Designer, a class must be related to a module + explicitly. - The command's argument is a module name, but note that the - command considers the rest of the line as part of its - argument. Make sure that the module name is followed by a - linebreak. For example: + The command's argument is a module name, but note that the command + considers the rest of the line as part of its argument. Make sure + that the module name is followed by a linebreak. - \code - /*! - \class QDesignerTaskMenuExtension - \inmodule QtDesigner - * / - \endcode + \code + /*! + \class QDesignerTaskMenuExtension + \inmodule QtDesigner + * / + \endcode - will ensure that the QDesignerTaskMenuExtension class is - included in the \c QtDesigner module, which means, for - example, that the class will appear on the list created by - calling the \l {generatelist}{\\generatelist} command with - the \c {{classesbymodule QtDesigner}} argument. + This ensures that the QDesignerTaskMenuExtension class is included + in the \c QtDesigner module, which means, for example, that the + class will appear on the list created by calling the \l + {generatelist-command} {\\generatelist} command with the \c + {{classesbymodule QtDesigner}} argument. - See also \l {module}{\\module} and \l - {generatelist}{\\generatelist}. - \endtable + See also \l {module-command} {\\module} and \l + {generatelist-command} {\\generatelist}. */ /*! - \page 20-qdoc-commands-title.html - \previouspage Grouping Commands - \contentspage QDoc Manual - Table of Contents - \nextpage QDoc Configuration - - \title Title Commands - - In general a title command considers everything that follows it - until the first line break as its argument. If the title needs to - be spanned over several lines, make sure to end each line (except - the last one) with a backslash. - - \section1 Alphabetical List - - \l {20-qdoc-commands-title.html#title}{\\title}, - \l {20-qdoc-commands-title.html#subtitle}{\\subtitle} - - \section1 Command Descriptions + \page 20-qdoc-commands-namingthings.html + \previouspage Grouping Things + \contentspage Table of Contents + \nextpage Markup Commands - \table - \header - \o Command - \o Description + \title Naming Things - \row - \o \bold \\title \target title - \o \bold {The \\title command sets the title for a - documentation page, or allows you to override it.} + In general, a title command considers everything that follows it + until the first line break as its argument. If the title is so + long it must span multiple lines, end each line (except the last + one) with a backslash. - For example: + \section1 Commands - \code - / *! - \page signalandslots.html + \target title-command + \section2 \\title - \title Signals and Slots + The \\title command sets the title for a documentation page, or + allows you to override it. - Signals and slots are used for communication between - objects. The signals and slots mechanism is a central - feature of Qt and probably the part that differs most - from the features provided by other frameworks. + \code + / *! + \page signalandslots.html - ... - * / - \endcode + \title Signals & Slots - will be rendered as + Signals and slots are used for communication between + objects. The signals and slots mechanism is a central + feature of Qt and probably the part that differs most + from the features provided by other frameworks. - \quotation - \raw HTML - <h1><center>Signal and Slots</center></h1> - \endraw + ... + * / + \endcode - Signals and slots are used for communication between - objects. The signals and slots mechanism is a central - feature of Qt and probably the part that differs most - from the features provided by other frameworks. + QDoc renders this as: - ... - \endquotation - See also \l {subtitle}{\\subtitle}. + \quotation + \raw HTML + <h1><center>Signal and Slots</center></h1> + \endraw - \row - \o \bold \\subtitle \target subtitle - \o \bold {The \\subtitle command sets a subtitle for a - documentation page.} + Signals and slots are used for communication between + objects. The signals and slots mechanism is a central + feature of Qt and probably the part that differs most + from the features provided by other frameworks. + ... + \endquotation + See also \l {subtitle-command} {\\subtitle}. - For example: + \target subtitle-command + \section2 \\subtitle - \code - / *! - \page qtopiacore-overview.html + The \\subtitle command sets a subtitle for a documentation page. - \title Qtopia Core - \subtitle Qt for Embedded Linux + \code + / *! + \page qtopiacore-overview.html - Qt/Embedded, the embedded Linux port of Qt, is a - complete and self-contained C++ GUI and platform - development tool for Linux-based embedded development. + \title Qtopia Core + \subtitle Qt for Embedded Linux - ... - * / - \endcode + Qt/Embedded, the embedded Linux port of Qt, is a + complete and self-contained C++ GUI and platform + development tool for Linux-based embedded development. + ... + * / + \endcode - will be rendered as + QDoc renders this as: - \quotation - \raw HTML - <h1><center>Qtopia Core</center></h1> - <h2><center>Qt for Embedded Linux</center></h2> - \endraw + \quotation + \raw HTML + <h1><center>Qtopia Core</center></h1> + <h2><center>Qt for Embedded Linux</center></h2> + \endraw - Qt/Embedded, the embedded Linux port of Qt, is a - complete and self-contained C++ GUI and platform - development tool for Linux-based embedded development. + Qt/Embedded, the embedded Linux port of Qt, is a + complete and self-contained C++ GUI and platform + development tool for Linux-based embedded development. + ... + \endquotation - ... - \endquotation + See also \l {title-command} {\\title}. - See also \l {title}{\\title}. - \endtable */ /*! \page 21-0-qdoc-configuration.html - \previouspage Title Commands - \contentspage QDoc Manual - Table of Contents + \previouspage Miscellaneous + \contentspage Table of Contents \nextpage General Configuration Variables - \title QDoc Configuration + \title The QDoc Configuration File - \tableofcontents + Before running QDoc to to extract and format your QDOC comments, + you must create a QDoc configuration file to tell QDoc where to find + them. \list \o \l {Supporting Derived Projects} - \o \l {QDoc Compatibility} + \o \l {Compatibility Issues} \endlist When running QDoc to generate the documentation, you must specify a configuration file on the command line: - \quotation - \bold {/currentdirectory$ qdoc3 my-documentation.qdocconf} - \endquotation - \section1 General Description The configuration file is a list of entries of entries of the form - \i {"variable = value"}. Using the configuration variables, you + \e {"variable = value"}. Using the configuration variables, you can define where QDoc should find the various source files, images and examples, where to put generated documentation etc. The configuration file can also contain directives like \c @@ -6998,7 +6770,7 @@ projects. If some of the variable keys have the same values, they can be set - at the same time. For example: + at the same time. \code {header, source}dirs = kernel @@ -7020,7 +6792,7 @@ provide a variable of the latter type with several strings they will simply be concatenated. The quotes around the value string are optional. But applying them allows you to use special - characters like '=' and ' \" ' within the string. For example: + characters like '=' and ' \" ' within the string. \code HTML.postheader = "<a href=\"index.html\">Home</a>" @@ -7037,51 +6809,43 @@ \section1 Configuration Variables - \section2 Alphabetical List - - \l {22-qdoc-configuration-generalvariables.html#alias}{alias}, - \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoredirectives} - {Cpp.ignoredirectives}, - \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoretoken} - {Cpp.ignoretokens}, - \l {22-qdoc-configuration-generalvariables.html#definesvariable}{defines}, - \l {22-qdoc-configuration-generalvariables.html#edition}{edition}, - \l {22-qdoc-configuration-generalvariables.html#exampledirs}{exampledirs}, - \l {22-qdoc-configuration-generalvariables.html#examples}{examples}, - \l {22-qdoc-configuration-generalvariables.html#examples.fileextensions} - {examples.fileextensions}, - \l {22-qdoc-configuration-generalvariables.html#extraimages}{extraimages}, - \l {22-qdoc-configuration-generalvariables.html#falsehoods}{falsehoods}, - \l {22-qdoc-configuration-generalvariables.html#headerdirs}{headerdirs}, - \l {22-qdoc-configuration-generalvariables.html#headers}{headers}, - \l {22-qdoc-configuration-generalvariables.html#headers.fileextensions} - {headers.fileextensions}, - \l {24-qdoc-configuration-htmlvariables.html#HTML.footer}{HTML.footer}, - \l {24-qdoc-configuration-htmlvariables.html#HTML.postheader} - {HTML.postheader}, - \l {24-qdoc-configuration-htmlvariables.html#HTML.style}{HTML.style}, - \l {22-qdoc-configuration-generalvariables.html#imagedirs}{imagedirs}, - \l {22-qdoc-configuration-generalvariables.html#images}{images}, - \l {22-qdoc-configuration-generalvariables.html#images.fileextensions} - {images.fileextensions}, - \l {22-qdoc-configuration-generalvariables.html#language}{language}, - \l {22-qdoc-configuration-generalvariables.html#macro}{macro}, - \l {22-qdoc-configuration-generalvariables.html#outputdir}{outputdir}, - \l {22-qdoc-configuration-generalvariables.html#outputformats} - {outputformats}, - \l {22-qdoc-configuration-generalvariables.html#outputprefixes} - {outputprefixes}, - \l {22-qdoc-configuration-generalvariables.html#slow}{slow}, - \l {22-qdoc-configuration-generalvariables.html#sourcedirs}{sourcedirs}, - \l {22-qdoc-configuration-generalvariables.html#sources}{sources}, - \l {22-qdoc-configuration-generalvariables.html#sources.fileextensions} - {sources.fileextensions}, - \l {22-qdoc-configuration-generalvariables.html#spurious}{spurious}, - \l {22-qdoc-configuration-generalvariables.html#tabsize}{tabsize}, - \l {22-qdoc-configuration-generalvariables.html#version}{version}, - \l {22-qdoc-configuration-generalvariables.html#versionsym}{versionsym} - - \section2 Categories + \section1 Variable List + + \list + \o \l {22-qdoc-configuration-generalvariables.html#alias-variable} {alias} + \o \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoredirectives-variable} {Cpp.ignoredirectives} + \o \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoretokens-variable} {Cpp.ignoretokens} + \o \l {22-qdoc-configuration-generalvariables.html#defines-variable} {defines} + \o \l {22-qdoc-configuration-generalvariables.html#edition-variable} {edition} + \o \l {22-qdoc-configuration-generalvariables.html#exampledirs-variable} {exampledirs} + \o \l {22-qdoc-configuration-generalvariables.html#examples-variable} {examples} + \o \l {22-qdoc-configuration-generalvariables.html#examples.fileextensions-variable} {examples.fileextensions} + \o \l {22-qdoc-configuration-generalvariables.html#extraimages-variable} {extraimages} + \o \l {22-qdoc-configuration-generalvariables.html#falsehoods-variable} {falsehoods} + \o \l {22-qdoc-configuration-generalvariables.html#headerdirs-variable} {headerdirs} + \o \l {22-qdoc-configuration-generalvariables.html#headers-variable} {headers} + \o \l {22-qdoc-configuration-generalvariables.html#headers.fileextensions-variable} {headers.fileextensions} + \o \l {24-qdoc-configuration-htmlvariables.html#HTML.footer-variable} {HTML.footer} + \o \l {24-qdoc-configuration-htmlvariables.html#HTML.postheader-variable} {HTML.postheader} + \o \l {24-qdoc-configuration-htmlvariables.html#HTML.style-variable} {HTML.style} + \o \l {22-qdoc-configuration-generalvariables.html#imagedirs-variable} {imagedirs} + \o \l {22-qdoc-configuration-generalvariables.html#images-variable} {images} + \o \l {22-qdoc-configuration-generalvariables.html#images.fileextensions-variable} {images.fileextensions} + \o \l {22-qdoc-configuration-generalvariables.html#language-variable} {language} + \o \l {22-qdoc-configuration-generalvariables.html#macro-variable} {macro} + \o \l {22-qdoc-configuration-generalvariables.html#outputdir-variable} {outputdir} + \o \l {22-qdoc-configuration-generalvariables.html#outputformats-variable} {outputformats} + \o \l {22-qdoc-configuration-generalvariables.html#slow-variable} {slow} + \o \l {22-qdoc-configuration-generalvariables.html#sourcedirs-variable} {sourcedirs} + \o \l {22-qdoc-configuration-generalvariables.html#sources-variable} {sources} + \o \l {22-qdoc-configuration-generalvariables.html#sources.fileextensions-variable} {sources.fileextensions} + \o \l {22-qdoc-configuration-generalvariables.html#spurious-variable} {spurious} + \o \l {22-qdoc-configuration-generalvariables.html#tabsize-variable} {tabsize} + \o \l {22-qdoc-configuration-generalvariables.html#version-variable} {version} + \o \l {22-qdoc-configuration-generalvariables.html#versionsym-variable} {versionsym} + \endlist + + \section1 Categories \list \o \l {General Configuration Variables} @@ -7099,8 +6863,9 @@ /*! \page 21-1-minimum-qdocconf.html - \previouspage QDoc Configuration - \contentspage QDoc Manual - Table of Contents + \previouspage qt.qdocconf + \contentspage Table of Contents + \nextpage Table of Contents \title minimum.qdocconf @@ -7109,8 +6874,9 @@ /*! \page 21-2-qt-qdocconf.html - \previouspage QDoc Configuration - \contentspage QDoc Manual - Table of Contents + \previouspage Compatibility Issues + \contentspage Table of Contents + \nextpage minimum.qdocconf \title qt.qdocconf @@ -7119,8 +6885,8 @@ /*! \page 22-qdoc-configuration-generalvariables.html - \previouspage QDoc Configuration - \contentspage QDoc Manual - Table of Contents + \previouspage The QDoc Configuration File + \contentspage Table of Contents \nextpage Creating Help Project Files \title General Configuration Variables @@ -7131,938 +6897,877 @@ documentation. You can also do some minor manipulation of QDoc itself, controlling its output and processing behavior. - \section1 Alphabetical List - - \l {22-qdoc-configuration-generalvariables.html#alias}{alias}, - \l {22-qdoc-configuration-generalvariables.html#codeindent}{codeindent}, - \l {22-qdoc-configuration-generalvariables.html#definesvariable}{defines}, - \l {22-qdoc-configuration-generalvariables.html#edition}{edition}, - \l {22-qdoc-configuration-generalvariables.html#exampledirs}{exampledirs}, - \l {22-qdoc-configuration-generalvariables.html#examples}{examples}, - \l {22-qdoc-configuration-generalvariables.html#examples.fileextensions} - {examples.fileextensions}, - \l {22-qdoc-configuration-generalvariables.html#extraimages}{extraimages}, - \l {22-qdoc-configuration-generalvariables.html#falsehoods}{falsehoods}, - \l {22-qdoc-configuration-generalvariables.html#generateindex}{generateindex}, - \l {22-qdoc-configuration-generalvariables.html#headerdirs}{headerdirs}, - \l {22-qdoc-configuration-generalvariables.html#headers}{headers}, - \l {22-qdoc-configuration-generalvariables.html#headers.fileextensions} - {headers.fileextensions}, - \l {22-qdoc-configuration-generalvariables.html#imagedirs}{imagedirs}, - \l {22-qdoc-configuration-generalvariables.html#images}{images}, - \l {22-qdoc-configuration-generalvariables.html#images.fileextensions} - {images.fileextensions}, - \l {22-qdoc-configuration-generalvariables.html#language}{language}, - \l {22-qdoc-configuration-generalvariables.html#macro}{macro}, - \l {22-qdoc-configuration-generalvariables.html#outputdir}{outputdir}, - \l {22-qdoc-configuration-generalvariables.html#outputformats} - {outputformats}, - \l {22-qdoc-configuration-generalvariables.html#outputprefixes} - {outputprefixes}, - \l {22-qdoc-configuration-generalvariables.html#slow}{slow}, - \l {22-qdoc-configuration-generalvariables.html#sourcedirs}{sourcedirs}, - \l {22-qdoc-configuration-generalvariables.html#sources}{sources}, - \l {22-qdoc-configuration-generalvariables.html#sources.fileextensions} - {sources.fileextensions}, - \l {22-qdoc-configuration-generalvariables.html#spurious}{spurious}, - \l {22-qdoc-configuration-generalvariables.html#tabsize}{tabsize}, - \l {22-qdoc-configuration-generalvariables.html#tagfile}{tagfile}, - \l {22-qdoc-configuration-generalvariables.html#version}{version}, - \l {22-qdoc-configuration-generalvariables.html#versionsym}{versionsym} - - \section1 Variable Descriptions + \target alias-variable + \section1 alias - \table + The \c alias variable renames a QDoc command. - \header - \o Variable - \o Description + The general syntax is \tt {alias.\e{original-command-name} = \e + temporary-command-name}. - \row - \o \bold alias \target alias - \o \bold {The \c alias variable renames a QDoc command.} + \code + alias.i = e + \endcode - The general syntax is \tt {alias.\i{original-command-name} - = \i temporary-command-name}. + This renames the built-in command \\i (italics) to \\e. The \c + alias variable is often used for compatibility reasons; for more + information see the \l {Compatibility Issues} {compatibility + section}. - For example: + See also \l {macro-command} {macro}. - \code - alias.i = e - \endcode + \target codeindent-variable + \section1 codeindent - renames the built-in command \\i (italics) to \\e. + The \c codeindent variable specifies the level of indentation that + QDoc uses when writing code snippets. - The \c alias variable is often used for compatibility - reasons; for more information see the \l {QDoc - Compatibility}{compatibility section}. + QDoc originally used a hard-coded value of four spaces for code + indentation to ensure that code snippets could be easily + distinguished from surrounding text. Since we can use \l{HTML + Specific Configuration Variables#HTML.stylesheets} {stylesheets} + to adjust the appearance of certain types of HTML elements, this + level of indentation is not always required. - See also \l macro. + \target defines-variable + \section1 defines - \row - \o \bold codeindent \target codeindent - \o \bold {The \c codeindent variable specifies the level of - indentation that QDoc uses when writing code snippets.} + The \c defines variable specifies the C++ preprocessor symbols + that QDoc will recognize and respond to. - QDoc originally used a hard-coded value of four spaces for - code indentation to ensure that code snippets could be easily - distinguished from surrounding text. Since we can use - \l{HTML Specific Configuration Variables#HTML.stylesheets}{stylesheets} to - adjust the appearance of certain types of HTML elements, this - level of indentation is not always required. + When a preprocessor symbol is specified using the \c defines + variable, you can also use the \l {if-command} {\\if} command to + enclose documentation that only will be included if the + preprocessor symbol is defined. - \row - \o \bold defines \target definesvariable - \o \bold {The \c defines variable specifies the C++ preprocessor - symbols that QDoc will recognize and respond to.} + The values of the variable are regular expressions (see QRegExp + for details). By default, no symbol is defined, meaning that code + protected with #ifdef...#endif will be ignored. - When a preprocessor symbol is specified using the \c - defines variable, you can also use the \l {if}{\\if} - command to enclose documentation that only will be included - if the preprocessor symbol is defined. + \code + defines = Q_QDOC \ + QT_.*_SUPPORT \ + QT_.*_LIB \ + QT_COMPAT \ + QT3_SUPPORT \ + Q_WS_.* \ + Q_OS_.* \ + Q_BYTE_ORDER \ + __cplusplus + \endcode - The values of the variable are regular expressions (see - QRegExp for details). By default, no symbol is defined, - meaning that code protected with #ifdef...#endif will be - ignored. + This ensures that QDoc will process the code that requires these + symbols to be defined. For example: - For example: + \code + #ifdef Q_WS_WIN + HDC getDC() const; + void releaseDC(HDC) const; + #endif + \endcode - \code - defines = Q_QDOC \ - QT_.*_SUPPORT \ - QT_.*_LIB \ - QT_COMPAT \ - QT3_SUPPORT \ - Q_WS_.* \ - Q_OS_.* \ - Q_BYTE_ORDER \ - __cplusplus - \endcode + Since the Q_WS_.* regular expression (specified using the \c + defines variable) matches Q_WS_WIN, QDoc will process the code + within #ifdef and #endif in our example. - ensures that QDoc will process the code that requires these - symbols to be defined. For example: + You can also define preprocessor symbols manually on the command + line using the -D option. For example: - \code - #ifdef Q_WS_WIN - HDC getDC() const; - void releaseDC(HDC) const; - #endif - \endcode + \code + currentdirectory$ qdoc3 -Dconsoleedition qt.qdocconf + \endcode - Since the Q_WS_.* regular expression (specified using the - \c defines variable) matches Q_WS_WIN, QDoc will process - the code within #ifdef and #endif in our example. + In this case the -D option ensures that the \c consoleedition + preprocessor symbol is defined when QDoc processes the source + files defined in the qt.qdocconf file. - You can also define preprocessor symbols manually on the - command line using the -D option. For example: + See also \l {falsehoods-variable} {falsehoods} and \l {if-command} {\\if}. - \code - currentdirectory$ qdoc3 -Dconsoleedition qt.qdocconf - \endcode + \target edition-variable + \section1 edition - In this case the -D option ensures that the \c - consoleedition preprocessor symbol is defined when QDoc - processes the source files defined in the qt.qdocconf file. + The \c edition variable specifies which modules are included in + each edition of a package, and provides QDoc with information to + provide class lists for each edition. - See also \l falsehoods and \l {if}{\\if}. + This feature is mostly used when providing documentation for Qt + packages. - \row - \o \bold edition \target edition - \o \bold {The \c edition variable specifies which modules are - included in each edition of a package, and provides QDoc - with information to provide class lists for each edition.} + The \c edition variable is always used with a particular edition + name to define the modules for that edition: - This feature is mostly used when providing documentation - for Qt packages. + \code + edition.Console = QtCore QtNetwork QtSql QtXml + edition.Desktop = QtCore QtGui QtNetwork QtOpenGL QtSql QtXml \ + QtDesigner QtAssistant Qt3Support QAxContainer \ + QAxServer + edition.DesktopLight = QtCore QtGui Qt3SupportLight + \endcode - The \c edition variable is always used with a particular - edition name to define the modules for that edition: + In the above examples, the \c Console edition only includes the + contents of four modules. Only the classes from these modules will + be used when the \l{Miscellaneous#generatelist-command} + {generatelist} command is used to generate a list of classes for + this edition: - \code - edition.Console = QtCore QtNetwork QtSql QtXml - edition.Desktop = QtCore QtGui QtNetwork QtOpenGL QtSql QtXml \ - QtDesigner QtAssistant Qt3Support QAxContainer \ - QAxServer - edition.DesktopLight = QtCore QtGui Qt3SupportLight - \endcode + \code + \generatelist{classesbyedition Console} + \endcode - In the above examples, the \c Console edition only includes - the contents of four modules. Only the classes from these - modules will be used when the - \l{Miscellaneous Commands#generatelist}{generatelist} command - is used to generate a list of classes for this edition: + \target exampledirs-variable + \section1 exampledirs - \code - \generatelist{classesbyedition Console} - \endcode + The \c exampledirs variable specifies the directories containing + the source code of the example files. - \row - \o \bold exampledirs \target exampledirs - \o \bold {The \c exampledirs variable specifies the directories - containing the source code of the example files.} + The \l {examples-variable} {examples} {examples} and \l + {exampledirs-variable} {exampledirs} variables are used by the \l + {quotefromfile-command} {\\quotefromfile}, \l {quotefile-command} + {\\quotefile} and \l {example-command} {\\example} commands. If + both the \l {examples-variable} {examples} and \l + {exampledirs-variable} {exampledirs} variables are defined, QDoc + will search in both, first in \l {examples-variable} {examples} + then in \l {exampledirs-variable} {exampledirs}. - The \l {examples}{\c examples} and \c exampledirs variables - are used by the \l {quotefromfile}{\\quotefromfile}, \l - {quotefile}{\\quotefile} and \l {example}{\\example} - commands. If both the \l {examples}{\c examples} and \c - exampledirs variables are defined, QDoc will search in - both, first in \l {examples}{\c examples} then in \c - exampledirs. + QDoc will search through the directories in the specified order, + and accept the first matching file it finds. It will only search + in the specified directories, \e not in subdirectories. - QDoc will search through the directories in the specified - order, and accept the first matching file it finds. It will - only search in the specified directories, \i not in - subdirectories. + \code + exampledirs = $QTDIR/doc/src \ + $QTDIR/examples \ + $QTDIR \ + $QTDIR/qmake/examples - For example: + examples = $QTDIR/examples/widgets/analogclock/analogclock.cpp + \endcode - \code - exampledirs = $QTDIR/doc/src \ - $QTDIR/examples \ - $QTDIR \ - $QTDIR/qmake/examples + When processing - examples = $QTDIR/examples/widgets/analogclock/analogclock.cpp - \endcode + \code + \quotefromfile widgets/calculator/calculator.cpp + \endcode - When processing + QDoc will then see if there exists a file called \c calculator.cpp + listed as a value in the \l {examples} {\c examples} variable. If + it doesn't, it will search in the \c exampledirs variable, and + first see if there exists a file called - \code - \quotefromfile widgets/calculator/calculator.cpp - \endcode + \code + $QTDIR/doc/src/widgets/calculator/calculator.cpp + \endcode - QDoc will then see if there exists a file called \c - calculator.cpp listed as a value in the \l {examples}{\c - examples} variable. If it doesn't, it will search in the \c - exampledirs variable, and first see if there exists a file - called + If it doesn't, QDoc will continue looking for a file called - \code - $QTDIR/doc/src/widgets/calculator/calculator.cpp - \endcode + \code + $QTDIR/examples/widgets/calculator/calculator.cpp + \endcode - If it doesn't, QDoc will continue looking for a file - called + and so forth. - \code - $QTDIR/examples/widgets/calculator/calculator.cpp - \endcode + See also \l examples. - and so forth. + \target examples-variable + \section1 examples - See also \l examples. + The \c examples variable allows you to specify individual example + files in addition to those located in the directories specified by + the \l {exampledirs-variable} {\c exampledirs} variable. - \row - \o \bold examples \target examples - \o \bold {The \c examples variable allows you to specify individual - example files in addition to those located in the directories - specified by the \l {exampledirs}{\c exampledirs} variable.} - - The \c examples and \l {exampledirs}{\c exampledirs} - variables are used by the \l - {quotefromfile}{\\quotefromfile}, \l - {quotefile}{\\quotefile} and \l {example}{\\example} - commands. If both the \c examples and \l {exampledirs}{\c - exampledirs} variables are defined, QDoc will search in - both, first in \c examples then in \l {exampledirs}{\c - exampledirs}. - - QDoc will search through the values listed for the \c - examples variable, in the specified order, and accept - the first one it finds. - - For an extensive example, see the \l {exampledirs}{\c - exampledirs} command. But note that if you know the file is - listed in the \c examples variable, you don't need to - specify its path: + The \c examples and \l {exampledirs-variable} {\c exampledirs} + variables are used by the \l {quotefromfile-command} + {\\quotefromfile}, \l {quotefile-command} {\\quotefile} and \l + {example} {\\example} commands. If both the \c examples and \l + {exampledirs-variable} {\c exampledirs} variables are defined, + QDoc will search in both, first in \c examples then in \l + {exampledirs-variable} {\c exampledirs}. - \code - \quotefromfile calculator.cpp - \endcode + QDoc will search through the values listed for the \c examples + variable, in the specified order, and accept the first one it + finds. - See also \l exampledirs. + For an extensive example, see the \l {exampledirs-variable} {\c + exampledirs} command. But note that if you know the file is listed + in the \c examples variable, you don't need to specify its path: - \row - \o \bold examples.fileextensions \target examples.fileextensions - \o \bold {The \c examples.fileextensions variable specifies the - file extensions that qdoc will look for when collecting example - files for display in the documentation.} + \code + \quotefromfile calculator.cpp + \endcode - The default extensions are *.cpp, *.h, *.js, *.xq, *.svg, *.xml - and *.ui. However, if + See also \l {exampledirs-variable} {exampledirs}. - The extensions are given as standard wildcard expressions. - You can add a file extension to the filter using '+='. For - example: + \target examples.fileextensions-variable + \section1 examples.fileextensions - \code - examples.fileextensions += *.qrc - \endcode + The \c examples.fileextensions variable specifies the file + extensions that qdoc will look for when collecting example files + for display in the documentation. - See also \l{headers.fileextensions}. + The default extensions are *.cpp, *.h, *.js, *.xq, *.svg, *.xml + and *.ui. However, if - \row - \o \bold extraimages \target extraimages - \o \bold {The \c extraimages variable tells QDoc to incorporate - specific images in the generated documentation.} + The extensions are given as standard wildcard expressions. You + can add a file extension to the filter using '+='. For example: - QDoc will not recognize images used within HTML (or any - other markup language). If we want the images to be copied - from the directories specified by \l {imagedirs}{\c - imagedirs} (the images in question must be located in these - directories) to the output directory, we must specify the - images using the \c extraimages variable. + \code + examples.fileextensions += *.qrc + \endcode - The general syntax is \tt {extraimages.\i{format} = \i - image}. The file extension is optional. + See also \l{headers.fileextensions}. - For example, in \l qt.qdocconf we use a couple of images - within the HTML.postheader variable which value is pure - HTML. For that reason, these images are specified using the - \c extraimages variable: + \target extraimages-variable + \section1 extraimages - \code - extraimages.HTML = qt-logo - \endcode + The \c extraimages variable tells QDoc to incorporate specific + images in the generated documentation. - See also \l images and \l imagedirs. + QDoc will not recognize images used within HTML (or any other + markup language). If we want the images to be copied from the + directories specified by \l {imagedirs} {\c imagedirs} (the images + in question must be located in these directories) to the output + directory, we must specify the images using the \c extraimages + variable. - \row - \o \bold falsehoods \target falsehoods - \o \bold {The \c falsehoods variable defines the truth value of - specified preprocessor symbols as false.} + The general syntax is \tt {extraimages.\e{format} = \e image}. The + file extension is optional. - If this variable is not set for a preprocessor symbol, QDoc - assumes its truth value is true. The exception is '0', - which value always is false. + For example, in \l qt.qdocconf we use a couple of images within + the HTML.postheader variable which value is pure HTML. For that + reason, these images are specified using the \c extraimages + variable: - QDoc will recognize, and is able to evaluate, the following - preprocessor syntax: + \code + extraimages.HTML = qt-logo + \endcode - \code - #ifdef NOTYET - ... - #endif + See also \l images and \l imagedirs. - #if defined (NOTYET) - ... - #end if - \endcode + \target falsehoods-variable + \section1 falsehoods - However, faced with unknown syntax like + The \c falsehoods variable defines the truth value of specified + preprocessor symbols as false. - \code - #if NOTYET - ... - #endif - \endcode + If this variable is not set for a preprocessor symbol, QDoc + assumes its truth value is true. The exception is '0', which value + always is false. - QDoc will evaluate it as true by default, \i unless the - preprocessor symbol is specified within the \c falsehoods - variable entry: + QDoc will recognize, and is able to evaluate, the following + preprocessor syntax: - \code - falsehoods = NOTYET - \endcode + \code + #ifdef NOTYET + ... + #endif - See also \l defines. + #if defined (NOTYET) + ... + #end if + \endcode - \row - \o \bold generateindex \target generateindex - \o \bold{The \c generateindex variable contains a boolean value that - specifies whether to generate an index file when HTML documentation - is generated.} - - By default, an index file is always generated with HTML documentation, - so this variable is typically only used when disabling this feature - (by setting the value to \c false) or when enabling index generation - for the WebXML output (by setting the value to \c true). - \row - \o \bold headerdirs \target headerdirs - \o \bold {The \c headerdirs variable specifies the directories - containing the header files associated with the \c .cpp source - files used in the documentation.} + However, faced with unknown syntax like - For example: + \code + #if NOTYET + ... + #endif + \endcode - \code - headerdirs = $QTDIR/src \ - $QTDIR/extensions/activeqt \ - $QTDIR/extensions/motif \ - $QTDIR/tools/designer/src/lib/extension \ - $QTDIR/tools/designer/src/lib/sdk \ - $QTDIR/tools/designer/src/lib/uilib - \endcode + QDoc will evaluate it as true by default, \e unless the + preprocessor symbol is specified within the \c falsehoods variable + entry: - When executed, the first QDoc will do is to read through - the headers specified in the \l {headers}{\c headers} - variable, and the ones located in the directories specified - in the \c headerdir variable (including all - subdirectories), building an internal structure of the - classes and their functions. - - Then it will read through the sources specified in the \l - {sources}{\c sources}, and the ones located in the - directories specified in the \l {sourcedirs}{\c sourcedirs} - varible (including all subdirectories), merging the - documentation with the structure it retrieved from the - header files. - - If both the \c headers and \c headerdirs variables are - defined, QDoc will read through both, first \l {headers}{\c - headers} then \c headerdirs. - - In the specified directories, QDoc will only read the files - with the fileextensions specified in the \l - {headers.fileextensions}{\c headers.fileextensions} - variable. The default extensions are *.ch, *.h, *.h++, - *.hh, *.hpp and *.hxx". The files specified by \l - {headers}{\c headers} will be read independent of their - fileextensions. - - See also \l headers and \l headers.fileextensions. + \code + falsehoods = NOTYET + \endcode - \row - \o \bold headers \target headers - \o \bold {The \c headers variable allows you to specify individual - header files in addition to those located in the directories - specified by the \l {headerdirs}{\c headerdirs} variable.} + See also \l defines. - For example: + \target generateindex-variable + \section1 generateindex - \code - headers = $QTDIR/src/gui/widgets/qlineedit.h \ - $QTDIR/src/gui/widgets/qpushbutton.h - \endcode + The \c generateindex variable contains a boolean value that + specifies whether to generate an index file when HTML + documentation is generated. - When processing the \c headers variable, QDoc behaves in the - same way as it does when processing the \l {headerdirs}{\c - headerdirs} variable. For more information, see the \l - {headerdirs}{\c headerdirs} variable. + By default, an index file is always generated with HTML + documentation, so this variable is typically only used when + disabling this feature (by setting the value to \c false) or when + enabling index generation for the WebXML output (by setting the + value to \c true). - See also \l headerdirs. + \target headerdirs-variable + \section1 headerdirs - \row - \o \bold headers.fileextensions \target headers.fileextensions - \o \bold {The \c headers.fileextensions variable specify the - extension used by the headers.} + The \c headerdirs variable specifies the directories containing + the header files associated with the \c .cpp source files used in + the documentation. - When processing the header files specified in the \l - {headerdirs}{\c headerdirs} variable, QDoc will only read - the files with the fileextensions specified in the \c - headers.fileextensions variable. In this way QDoc avoid - spending time reading irrelevant files. + \code + headerdirs = $QTDIR/src \ + $QTDIR/extensions/activeqt \ + $QTDIR/extensions/motif \ + $QTDIR/tools/designer/src/lib/extension \ + $QTDIR/tools/designer/src/lib/sdk \ + $QTDIR/tools/designer/src/lib/uilib + \endcode - The default extensions are *.ch, *.h, *.h++, *.hh, *.hpp - and *.hxx. + When executed, the first QDoc will do is to read through the + headers specified in the \l {headers} {\c headers} variable, and + the ones located in the directories specified in the \c headerdir + variable (including all subdirectories), building an internal + structure of the classes and their functions. - The extensions are given as standard wildcard expressions. - You can add a file extension to the filter using '+='. For - example: + Then it will read through the sources specified in the \l + {sources-variable} {\c sources}, and the ones located in the + directories specified in the \l {sourcedirs-variable} {\c + sourcedirs} varible (including all subdirectories), merging the + documentation with the structure it retrieved from the header + files. - \code - header.fileextensions += *.H - \endcode + If both the \c headers and \c headerdirs variables are defined, + QDoc will read through both, first \l {headers} {\c headers} then + \c headerdirs. - \warning The above assignment may not work as described. + In the specified directories, QDoc will only read the files with + the fileextensions specified in the \l {headers.fileextensions} + {\c headers.fileextensions} variable. The default extensions are + *.ch, *.h, *.h++, *.hh, *.hpp and *.hxx". The files specified by + \l {headers} {\c headers} will be read independent of their + fileextensions. - See also \l headerdirs. + See also \l headers and \l headers.fileextensions. - \row - \o \bold imagedirs \target imagedirs - \o \bold {The \c imagedirs variable specifies the directories - containing the images used in the documentation.} + \target headers-variable + \section1 headers - The \l {images}{\c images} and \c imagedirs variables are - used by the \l {image}{\\image} and \l - {inlineimage}{\\inlineimage} commands. If both the \l - {images}{\c images} and \c imagedirs variables are defined, - QDoc will search in both, first in \l {images}{\c images} - then in \c imagedirs. + The \c headers variable allows you to specify individual header + files in addition to those located in the directories specified by + the \l {headerdirs} {\c headerdirs} variable. - QDoc will search through the directories in the specified - order, and accept the first matching file it finds. It will - only search in the specified directories, \i not in - subdirectories. + \code + headers = $QTDIR/src/gui/widgets/qlineedit.h \ + $QTDIR/src/gui/widgets/qpushbutton.h + \endcode - For example: + When processing the \c headers variable, QDoc behaves in the same + way as it does when processing the \l {headerdirs} {\c headerdirs} + variable. For more information, see the \l {headerdirs} {\c + headerdirs} variable. - \code - imagedirs = $QTDIR/doc/src/images \ - $QTDIR/examples + See also \l headerdirs. - images = $QTDIR/doc/src/images/calculator-example.png - \endcode + \target headers.fileextensions-variable + \section1 headers.fileextensions - When processing + The \c headers.fileextensions variable specify the extension used + by the headers. - \code - \image calculator-example.png - \endcode + When processing the header files specified in the \l {headerdirs} + {\c headerdirs} variable, QDoc will only read the files with the + fileextensions specified in the \c headers.fileextensions + variable. In this way QDoc avoid spending time reading irrelevant + files. - QDoc will then see if there exists a file called - calculator-example.png listed as a value in the \c images - variable. If it doesn't, it will search in the \c imagedirs - variable, and first see if there exists a file called + The default extensions are *.ch, *.h, *.h++, *.hh, *.hpp and + *.hxx. - \code - $QTDIR/doc/src/images/calculator-example.png - \endcode + The extensions are given as standard wildcard expressions. You + can add a file extension to the filter using '+='. For example: - If it doesn't, QDoc will look for a file called + \code + header.fileextensions += *.H + \endcode - \code - $QTDIR/examples/calculator-example.png - \endcode + \warning The above assignment may not work as described. - You can filter the images in an image directory using the - \l {images.fileextensions}{\c images.fileextensions} - variable. The general idea behind the \l - {images.fileextensions}{\c images.fileextensions} variable - is to enable different image format for different output - format. + See also \l headerdirs. - \warning The \l {images.fileextensions}{\c - images.fileextensions} variable's functionality is - preliminay since QDoc at this point only support HTML. + \target imagedirs-variable + \section1 imagedirs - See also \l images and \l images.fileextensions. + The \c imagedirs variable specifies the directories containing the + images used in the documentation. - \row - \o \bold images \target images - \o \bold {The \c images variable allows you to specify individual - image files in addition to those located in the directories - specified by the \l {imagedirs}{\c imagedirs} variable.} + The \l {images} {\c images} and \c imagedirs variables are used by + the \l {image-command} {\\image} and \l {inlineimage-command} + {\\inlineimage} commands. If both the \l {images} {\c images} and + \c imagedirs variables are defined, QDoc will search in both, + first in \l {images} {\c images} then in \c imagedirs. - For example: + QDoc will search through the directories in the specified order, + and accept the first matching file it finds. It will only search + in the specified directories, \e not in subdirectories. - \code - images = $QTDIR/doc/src/images/calculator-example.png - \endcode + \code + imagedirs = $QTDIR/doc/src/images \ + $QTDIR/examples - When processing the \c images variable, QDoc behaves in the - same way as it does when processing the \l {imagedirs}{\c - imagedirs} variable. For more information, see the \l - {imagedirs}{\c imagedirs} variable. + images = $QTDIR/doc/src/images/calculator-example.png + \endcode - See also \l imagedirs and \l images.fileextensions. + When processing - \row - \o \bold images.fileextensions \target images.fileextensions - \o \bold {The images.fileextensions variable filters the files within - an image directory.} + \code + \image calculator-example.png + \endcode - The variable's values (the extensions) are given as - standard wildcard expressions. The general syntax is: \tt - {images.fileextensions.\i{format} = *.\i{extension}}. + QDoc will then see if there exists a file called + calculator-example.png listed as a value in the \c images + variable. If it doesn't, it will search in the \c imagedirs + variable, and first see if there exists a file called - The idea is to enable different image format for different - output format. For example: + \code + $QTDIR/doc/src/images/calculator-example.png + \endcode - \code - images.fileextensions.HTML = *.png - images.fileextensions.LOUT = *.eps - \endcode + If it doesn't, QDoc will look for a file called - Then, when processing the \l {image}{\\image} and \l - {inlineimage}{\\inlineimage} commands, QDoc will only - search for files with extensions specified in the output - format's associated image extension variable. + \code + $QTDIR/examples/calculator-example.png + \endcode - \warning This is preliminary functionality since QDoc at - this point only support HTML. + You can filter the images in an image directory using the \l + {images.fileextensions} {\c images.fileextensions} variable. The + general idea behind the \l {images.fileextensions} {\c images.fileextensions} + variable is to enable different image format for different output format. - The default extensions for HTML are *.png, *.jpg, *.jpeg - and *.gif. + \warning The \l {images.fileextensions} {\c images.fileextensions} + variable's functionality is preliminay since QDoc at this point + only support HTML. - You can add a file extension to the filter using '+='. For - example: + See also \l images and \l images.fileextensions. - \code - images.fileextensions.HTML += *.eps - \endcode + \target images-variable + \section1 images - See also \l imagedirs and \l images. + The \c images variable allows you to specify individual image + files in addition to those located in the directories specified by + the \l {imagedirs} {\c imagedirs} variable. - \row - \o \bold language \target language - \o \bold {The \c language variable specifies the language of the - source code that is used in the documentation.} + \code + images = $QTDIR/doc/src/images/calculator-example.png + \endcode - Currently, C++ is the only language that QDoc - understands. It is also the default language, and doesn't - really need to be specified. But for example in \l - qt.qdocconf: + When processing the \c images variable, QDoc behaves in the same + way as it does when processing the \l {imagedirs} {\c imagedirs} + variable. For more information, see the \l {imagedirs} {\c + imagedirs} variable. - \code - language = Cpp - \endcode + See also \l imagedirs and \l images.fileextensions. - identifies the language of the Qt source code as C++. + \target images.fileextensions-variable + \section1 images.fileextensions - \row - \o \bold macro \target macro - \o \bold {The \c macro variable can be used to create your - own QDoc commands.} + The images.fileextensions variable filters the files within an + image directory. - The general syntax is \tt {macro.\i{command} = - "\i{definition}}". The definition can be described using - QDoc syntax. In addition it is possible to provide an HTML - definition by appending .HTML to the variable. + The variable's values (the extensions) are given as standard + wildcard expressions. The general syntax is: \tt + {images.fileextensions.\e{format} = *.\e{extension}}. - For example in \l qt.qdocconf: + The idea is to enable different image format for different output + format. - \code - macro.gui = "\\bold" - macro.raisedaster.HTML = "<sup>*</sup>" - \endcode + \code + images.fileextensions.HTML = *.png + images.fileextensions.LOUT = *.eps + \endcode - makes sure that the \\gui command renders its argument using a - bold font, and that \\raisedaster renders a '*'. + Then, when processing the \l {image-command} {\\image} and \l + {inlineimage-command} {\\inlineimage} commands, QDoc will only + search for files with extensions specified in the output format's + associated image extension variable. - \row - \o \bold naturallanguage \target naturallanguage - \o \bold {The \c naturallanguage variable specifies the natural - language used for the documentation generated by qdoc.} + \warning This is preliminary functionality since QDoc at this + point only support HTML. - For example: + The default extensions for HTML are *.png, *.jpg, *.jpeg and + *.gif. - \code - naturallanguage = zh-Hans - \endcode + You can add a file extension to the filter using '+='. For + example: - By default, the natural language is \c en for compatibility - with legacy documentation. + \code + images.fileextensions.HTML += *.eps + \endcode - qdoc will add the natural language information to the HTML - it generates, using the \c lang and \c xml:lang attributes. + See also \l imagedirs and \l images. - See also \l sourceencoding, \l outputencoding, - \l{http://www.w3.org/TR/xhtml1/#C_7}{C.7. The lang and xml:lang Attributes} and - \l{http://www.w3.org/TR/i18n-html-tech-lang/#ri20040429.113217290}{Best Practice 13: Using Hans and Hant codes}. + \target language-variable + \section1 language - \row - \o \bold outputdir \target outputdir - \o \bold {The \c outputdir variable specifies the directory - where QDoc will put the generated documentation.} + The \c language variable specifies the language of the source code + that is used in the documentation. - In qt.qdocconf: + Currently, C++ is the only language that QDoc understands. It is + also the default language, and doesn't really need to be + specified. But for example in \l qt.qdocconf: - \code - outputdir = $QTDIR/doc/html - \endcode + \code + language = Cpp + \endcode - locates the generated Qt reference documentation in - $QTDIR/doc/html. For example, the documentation of the - QWidget class is located in + identifies the language of the Qt source code as C++. - \code - $QTDIR/doc/html/qwidget.html - \endcode + \target macro-variable + \section1 macro - The associated images will be put in an \c images subdirectory. + The \c macro variable can be used to create your own QDoc + commands. - \warning When running QDoc multiple times using the same output - directory, all files from the previous run will be lost. + The general syntax is \tt {macro.\e{command} = + "\e{definition}}". The definition can be described using QDoc + syntax. In addition it is possible to provide an HTML definition + by appending .HTML to the variable. - \row - \o \bold outputencoding \target outputencoding - \o \bold {The \c outputencoding variable specifies the encoding - used for the documentation generated by qdoc.} + For example in \l qt.qdocconf: - For example: + \code + macro.gui = "\\bold" + macro.raisedaster.HTML = "<sup>*</sup>" + \endcode - \code - outputencoding = UTF-8 - \endcode + makes sure that the \\gui command renders its argument using a + bold font, and that \\raisedaster renders a '*'. - By default, the output encoding is \c ISO-8859-1 (Latin1) for - compatibility with legacy documentation. When generating - documentation for some languages, particularly non-European - languages, this is not sufficient and an encoding such as UTF-8 - is required. + \target naturallanguage-variable + \section1 naturallanguage - qdoc will encode HTML using this encoding and generate the - correct declarations to indicate to browsers which encoding - is being used. The \l naturallanguage configuration variable - should also be specified to provide browsers with a complete - set of character encoding and language information. + The \c naturallanguage variable specifies the natural language + used for the documentation generated by qdoc. - See also \l outputencoding and \l naturallanguage. + \code + naturallanguage = zh-Hans + \endcode - \row - \o \bold outputformats \target outputformats - \o \bold {The \c outputformats variable specifies the format of - the generated documentation.} + By default, the natural language is \c en for compatibility with + legacy documentation. - Currently, QDoc only supports the HTML format. It is also - the default format, and doesn't need to be specified. + qdoc will add the natural language information to the HTML it + generates, using the \c lang and \c xml:lang attributes. - \row - \o \bold outputprefixes \target outputprefixes - \o \bold {The \c outputprefixes variable specifies a mapping between - types of files and the prefixes to prepend to the HTML file names - in the generated documentation.} + See also \l {sourceencoding-variable} {sourceencoding}, + \l {outputencoding-variable} {outputencoding}, + \l{http://www.w3.org/TR/xhtml1/#C_7} + {C.7. The lang and xml:lang Attributes} and + \l{http://www.w3.org/TR/i18n-html-tech-lang/#ri20040429.113217290} + {Best Practice 13: Using Hans and Hant codes}. - For example: + \target outputdir-variable + \section1 outputdir - \code - outputprefixes = QML - outputprefixes.QML = qt-components- - \endcode + The \c outputdir variable specifies the directory where QDoc will + put the generated documentation. - Be default, files containing the API documentation for QML elements - or components are prefixed with "qml-". In the above example, the - prefix "qt-components-" is used instead. + In qt.qdocconf: - \row - \o \bold qhp \target qhp - \o \bold{The \c qhp variable is used to define the information to be - written out to Qt Help Project (\c{qhp}) files.} + \code + outputdir = $QTDIR/doc/html + \endcode - See the \l{Creating Help Project Files} chapter for information - about this process. + locates the generated Qt reference documentation in + $QTDIR/doc/html. For example, the documentation of the QWidget + class is located in - \row - \o \bold slow (removed) \target slow - \o \bold {The \c slow variable previously specified whether QDoc should - do time-consuming processing, such as syntax highlighting.} + \code + $QTDIR/doc/html/qwidget.html + \endcode - This option has been replaced by the \l{syntaxhighlighing} option. + The associated images will be put in an \c images subdirectory. - For compatibility, the \c -slow command-line option has been - retained. This has the effect of enabling syntax highlighting. + \warning When running QDoc multiple times using the same output + directory, all files from the previous run will be lost. - \row - \o \bold sourcedirs \target sourcedirs - \o \bold {The \c sourcedirs variable specifies the directories - containing the \c .cpp or \c .qdoc files used in - the documentation.} + \target outputencoding-variable + \section1 outputencoding - For example in \l qt.qdocconf + The \c outputencoding variable specifies the encoding used for the + documentation generated by qdoc. - \code - sourcedirs = $QTDIR/src \ - $QTDIR/doc/src \ - $QTDIR/extensions/activeqt \ - $QTDIR/extensions/motif \ - $QTDIR/tools/designer/src/lib/extension \ - $QTDIR/tools/designer/src/lib/sdk \ - $QTDIR/tools/designer/src/lib/uilib - \endcode + \code + outputencoding = UTF-8 + \endcode - When executed, the first QDoc will do is to read through - the headers specified in the \l {header}{\c header} - variable, and the ones located in the directories specified - in the \c headerdir variable (including all - subdirectories), building an internal structure of the - classes and their functions. - - Then it will read through the sources specified in the \l - {sources}{\c sources}, and the ones located in the - directories specified in the \l {sourcedirs}{\c sourcedirs} - varible (including all subdirectories), merging the - documentation with the structure it retrieved from the - header files. - - If both the \c sources and \c sourcedirs variables are - defined, QDoc will read through both, first \l {sources}{\c - sources} then \c sourcedirs. - - In the specified directories, QDoc will only read the files - with the fileextensions specified in the \l - {sources.fileextensions}{\c sources.fileextensions} - variable. The default extensions are *.c++, *.cc, *.cpp and - *.cxx. The files specified by \l {sources}{\c sources} will - be read independent of their fileextensions. - - See also \l sources and \l sources.fileextensions. + By default, the output encoding is \c ISO-8859-1 (Latin1) for + compatibility with legacy documentation. When generating + documentation for some languages, particularly non-European + languages, this is not sufficient and an encoding such as UTF-8 is + required. - \row - \o \bold sourceencoding \target sourceencoding - \o \bold {The \c sourceencoding variable specifies the encoding - used for the source code and documentation.} + qdoc will encode HTML using this encoding and generate the correct + declarations to indicate to browsers which encoding is being + used. The \l naturallanguage configuration variable should also be + specified to provide browsers with a complete set of character + encoding and language information. - For example: + See also \l outputencoding and \l naturallanguage. - \code - sourceencoding = UTF-8 - \endcode + \target outputformats-variable + \section1 outputformats - By default, the source encoding is \c ISO-8859-1 (Latin1) for - compatibility with legacy documentation. For some languages, - particularly non-European languages, this is not sufficient - and an encoding such as UTF-8 is required. + The \c outputformats variable specifies the format of + the generated documentation. - Although qdoc will use the encoding to read source and - documentation files, limitations of C++ compilers may prevent - you from using non-ASCII characters in source code comments. - In cases like these, it is possible to write API documentation - completely in documentation files. + Currently, QDoc only supports the HTML format. It is also + the default format, and doesn't need to be specified. - See also \l naturallanguage and \l outputencoding. + \target outputprefixes + \section1 outputprefixes - \row - \o \bold sources \target sources - \o \bold {The \c sources variable allows you to specify - individual source files in addition to those located in the - directories specified by the \l {sourcedir}{\c sourcedir} - variable.} + The \c outputprefixes variable specifies a mapping between types of files + and the prefixes to prepend to the HTML file names in the generated + documentation. - For example: + \code + outputprefixes = QML + outputprefixes.QML = qt-components- + \endcode - \code - sources = $QTDIR/src/gui/widgets/qlineedit.cpp \ - $QTDIR/src/gui/widgets/qpushbutton.cpp - \endcode + By default, files containing the API documentation for QML elements + or components are prefixed with "qml-". In the above example, the + prefix "qt-components-" is used instead. - When processing the \c sources variable, QDoc behaves in the - same way as it does when processing the \l {sourcedirs}{\c - sourcedirs} variable. For more information, see the \l - {sourcedirs}{\c sourcedirs} variable. + \target qhp-variable + \section1 qhp - See also \l sourcedirs. + The \c qhp variable is used to define the information to be + written out to Qt Help Project (\c{qhp}) files. - \row - \o \bold sources.fileextensions \target sources.fileextensions - \o \bold {The \c sources.fileextensions variable filters the - files within a source directory.} + See the \l{Creating Help Project Files} chapter for information + about this process. - When processing the source files specified in the \l - {sourcedirs}{\c sourcedirs} variable, QDoc will only read - the files with the fileextensions specified in the \c - sources.fileextensions variable. In this way QDoc avoid - spending time reading irrelevant files. - The default extensions are *.c++, *.cc, *.cpp and *.cxx. + \target slow-variable + \section1 slow - The extensions are given as standard wildcard expressions. - You can add a file extension to the filter using '+='. For - example: + The \c slow variable specifies whether QDoc should do + time-consuming processing, such as syntax highlighting. The + default value is false. - \code - sources.fileextensions += *.CC - \endcode + \note This option has been replaced by the \l{syntaxhighlighting} option. - \warning The above assignment may not work as described. + For compatibility, the \c -slow command-line option has been + retained. This has the effect of enabling syntax highlighting. - See also \l sourcedirs and \l sources. + \target sourcedirs-variable + \section1 sourcedirs - \row - \o \bold spurious \target spurious - \o \bold {The \c spurious variable excludes specified - QDoc warnings from the output.} + The \c sourcedirs variable specifies the directories containing + the \c .cpp or \c .qdoc files used in the documentation. - The warnings are specified using standard wildcard - expressions. For example: + For example in \l qt.qdocconf - \code - spurious = "Cannot find .*" \ - "Missing .*" - \endcode + \code + sourcedirs = $QTDIR/src \ + $QTDIR/doc/src \ + $QTDIR/extensions/activeqt \ + $QTDIR/extensions/motif \ + $QTDIR/tools/designer/src/lib/extension \ + $QTDIR/tools/designer/src/lib/sdk \ + $QTDIR/tools/designer/src/lib/uilib + \endcode - makes sure that warnings matching either of these - expressions, will not be part of the output when running - QDoc. For example would the following warning be omitted - from the output: + When executed, the first QDoc will do is to read through the + headers specified in the \l {header-command} {\c header} variable, + and the ones located in the directories specified in the \c + headerdir variable (including all subdirectories), building an + internal structure of the classes and their functions. - \code - qt-4.0/src/opengl/qgl_mac.cpp:156: Missing parameter name - \endcode + Then it will read through the sources specified in the \l + {sources} {\c sources}, and the ones located in the directories + specified in the \l {sourcedirs} {\c sourcedirs} varible + (including all subdirectories), merging the documentation with the + structure it retrieved from the header files. - \row - \o \bold syntaxhighlighting \target syntaxhighlighting - \o \bold{The \c syntaxhighlighting variable specifies whether QDoc - should perform syntax highlighting on source code quoted in the - documentation it output.} + If both the \c sources and \c sourcedirs variables are defined, + QDoc will read through both, first \l {sources} {\c sources} then + \c sourcedirs. - For example: + In the specified directories, QDoc will only read the files with + the fileextensions specified in the \l {sources.fileextensions} + {\c sources.fileextensions} variable. The default extensions are + *.c++, *.cc, *.cpp and *.cxx. The files specified by \l {sources} + {\c sources} will be read independent of their fileextensions. - \code - syntaxhighlighting = true - \endcode + See also \l {sources-variable} {sources} and + \l {sources.fileextensions-variable} {sources.fileextensions}. - will enable syntax highlighting for all supported programming - languages. + \target sourceencoding-variable + \section1 sourceencoding - \row - \o \bold tabsize \target tabsize - \o \bold {The \c tabsize variable defines the size of a tab - character.} + The \c sourceencoding variable specifies the encoding used for the + source code and documentation. - For example: + \code + sourceencoding = UTF-8 + \endcode - \code - tabsize = 4 - \endcode + By default, the source encoding is \c ISO-8859-1 (Latin1) for + compatibility with legacy documentation. For some languages, + particularly non-European languages, this is not sufficient and an + encoding such as UTF-8 is required. - will give the tab character the size of 4 spaces. + Although qdoc will use the encoding to read source and + documentation files, limitations of C++ compilers may prevent you + from using non-ASCII characters in source code comments. In cases + like these, it is possible to write API documentation completely + in documentation files. - The default value of the variable is 8, and doesn't need to - be specified. + See also \l {naturallanguage-variable} {naturallanguage} and + \l {outputencoding-variable} {outputencoding}. - \row - \o \bold tagfile \target tagfile - \o \bold{The \c tagfile variable specifies the Doxygen tag file to be written - when HTML is generated.} - \row - \o \bold version \target version - \o \bold {The \c version variable specifies the version number of the - documented software.} + \target sources-variable + \section1 sources - For example: + The \c sources variable allows you to specify individual source + files in addition to those located in the directories specified by + the \l {sourcedirs-variable} {sourcedirs} variable. - \code - version = 4.0.1 - \endcode + \code + sources = $QTDIR/src/gui/widgets/qlineedit.cpp \ + $QTDIR/src/gui/widgets/qpushbutton.cpp + \endcode - When a version number is specified (using the \tt{\l - version} or \tt {\l versionsym} variables in a \c .qdocconf - file), it is accessible through the corresponding \\version - command for use in the documentation. + When processing the \c sources variable, QDoc behaves in the same + way as it does when processing the \l {sourcedirs-variable} + {sourcedirs} variable. For more information, see the \l + {sourcedirs-variable} {sourcedirs} variable. - \warning The \\version command's functionality is not - fully implemented; currently it only works within raw HTML - code. + See also \l {sourcedirs-variable} {sourcedirs}. - See also \l versionsym. + \target sources.fileextensions-variable + \section1 sources.fileextensions - \row - \o \bold versionsym \target versionsym - \o \bold {The \c versionsym variable specifies a C++ - preprocessor symbol that defines the version number - of the documented software.} + The \c sources.fileextensions variable filters the files within a + source directory. - For example in \l qt.qdocconf: + When processing the source files specified in the \l {sourcedirs} + {\c sourcedirs} variable, QDoc will only read the files with the + fileextensions specified in the \c sources.fileextensions + variable. In this way QDoc avoid spending time reading irrelevant + files. - \code - versionsym = QT_VERSION_STR - \endcode + The default extensions are *.c++, *.cc, *.cpp and *.cxx. - QT_VERSION_STR is defined in qglobal.h as follows + The extensions are given as standard wildcard expressions. You + can add a file extension to the filter using '+='. For example: - \code - #define QT_VERSION_STR "4.0.1" - \endcode + \code + sources.fileextensions += *.CC + \endcode - When a version number is specified (using the \tt{\l - version} or \tt {\l versionsym} variables in a \c .qdocconf - file), it is accessible through the corresponding \\version - command for use in the documentation. + \warning The above assignment may not work as described. - \warning The \\version command's functionality is not fully - implemented; currently it only works within raw HTML code. + See also \l {sourcedirs-variable} {sourcedirs} and \l + (sources-variable} {sources}. - See also \l {version}{\\version}. - \endtable + \target spurious-variable + \section1 spurious + + The \c spurious variable excludes specified QDoc warnings from the + output. The warnings are specified using standard wildcard + expressions. + + \code + spurious = "Cannot find .*" \ + "Missing .*" + \endcode + + makes sure that warnings matching either of these expressions, + will not be part of the output when running QDoc. For example + would the following warning be omitted from the output: + + \code + qt-4.0/src/opengl/qgl_mac.cpp:156: Missing parameter name + \endcode + + \target syntaxhighlighting + \section1 syntaxhighlighting + + The \c syntaxhighlighting variable specifies whether QDoc should + perform syntax highlighting on source code quoted in the + documentation it generates. + + \code + syntaxhighlighting = true + \endcode + + will enable syntax highlighting for all supported programming + languages. + + \target tabsize-variable + \section1 tabsize + + The \c tabsize variable defines the size of a tab character. + + \code + tabsize = 4 + \endcode + + will give the tab character the size of 4 spaces. The default + value of the variable is 8, and doesn't need to be specified. + + \target tagfile-variable + \section1 tagfile + + The \c tagfile variable specifies the Doxygen tag file to be + written when HTML is generated. + + \target version-variable + \section1 version + + The \c version variable specifies the version number of the + documented software. + + \code + version = 4.0.1 + \endcode + + When a version number is specified (using the \tt{\l version} or + \tt {\l versionsym} variables in a \c .qdocconf file), it is + accessible through the corresponding \\version command for use in + the documentation. + + \warning The \\version command's functionality is not fully + implemented; currently it only works within raw HTML code. + + See also \l versionsym. + + \target versionsym-variable + \section1 versionsym + + The \c versionsym variable specifies a C++ preprocessor symbol + that defines the version number of the documented software. + + For example in \l qt.qdocconf: + + \code + versionsym = QT_VERSION_STR + \endcode + + QT_VERSION_STR is defined in qglobal.h as follows + + \code + #define QT_VERSION_STR "4.0.1" + \endcode + + When a version number is specified (using the \tt{\l version} or + \tt {\l versionsym} variables in a \c .qdocconf file), it is + accessible through the corresponding \\version command for use in + the documentation. + + \warning The \\version command's functionality is not fully + implemented; currently it only works within raw HTML code. + + See also \l {version} {\\version}. */ /*! \page 22-creating-help-project-files.html \previouspage General Configuration Variables - \contentspage QDoc Manual - Table of Contents + \contentspage Table of Contents \nextpage C++ Specific Configuration Variables \title Creating Help Project Files @@ -8131,7 +7836,7 @@ /*! \page 23-qdoc-configuration-cppvariables.html \previouspage Creating Help Project Files - \contentspage QDoc Manual - Table of Contents + \contentspage Table of Contents \nextpage HTML Specific Configuration Variables \title C++ Specific Configuration Variables @@ -8139,137 +7844,114 @@ The C++ specific configuration variables are provided to avoid erroneous documentation due to non-standard C++ constructs. - \section1 Alphabetical List - - \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoredirectives} - {Cpp.ignoredirectives}, - \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoretoken} - {Cpp.ignoretokens} - - \section1 Variable Descriptions + \target Cpp.ignoredirectives-variable + \section1 Cpp.ignoredirectives - \table - - \header - \o Variable - \o Description + The \c Cpp.ignoredirectives variable makes QDoc ignore the + specified non-standard constructs, within C++ source code. - \row - \o \bold Cpp.ignoredirectives \target Cpp.ignoredirectives - \o \bold {The \c Cpp.ignoredirectives variable makes QDoc ignore - the specified non-standard constructs, within C++ source code.} - - If not specified by the \tt {\l Cpp.ignoretokens} or \tt - {\l Cpp.ignoredirectives} variables, non-standard - constructs (typically macros) can result in erroneous - documentation. + If not specified by the \tt {\l Cpp.ignoretokens} or \tt {\l + Cpp.ignoredirectives} variables, non-standard constructs + (typically macros) can result in erroneous documentation. - In \l qt.qdocconf: + In \l qt.qdocconf: - \code - Cpp.ignoredirectives = Q_DECLARE_INTERFACE \ - Q_DECLARE_OPERATORS_FOR_FLAGS \ - Q_DECLARE_PRIVATE \ - Q_DECLARE_PUBLIC \ - Q_DISABLE_COPY \ - Q_DUMMY_COMPARISON_OPERATOR \ - Q_ENUMS \ - Q_FLAGS \ - Q_INTERFACES \ - __attribute__ - \endcode + \code + Cpp.ignoredirectives = Q_DECLARE_INTERFACE \ + Q_DECLARE_OPERATORS_FOR_FLAGS \ + Q_DECLARE_PRIVATE \ + Q_DECLARE_PUBLIC \ + Q_DISABLE_COPY \ + Q_DUMMY_COMPARISON_OPERATOR \ + Q_ENUMS \ + Q_FLAGS \ + Q_INTERFACES \ + __attribute__ + \endcode - makes sure that when processing the code below, for - example, QDoc will simply ignore the 'Q_ENUMS' and - 'Q_FLAGS' expressions: + makes sure that when processing the code below, for example, QDoc + will simply ignore the 'Q_ENUMS' and 'Q_FLAGS' expressions: - \code - class Q_CORE_EXPORT Qt { - Q_OBJECT - Q_ENUMS(Orientation TextFormat BackgroundMode - DateFormat ScrollBarPolicy FocusPolicy - ContextMenuPolicy CaseSensitivity - LayoutDirection ArrowType) - Q_ENUMS(ToolButtonStyle) - Q_FLAGS(Alignment) - Q_FLAGS(Orientations) - Q_FLAGS(DockWidgetAreas) - - public: - ... - }; - \endcode + \code + class Q_CORE_EXPORT Qt { + Q_OBJECT + Q_ENUMS(Orientation TextFormat BackgroundMode + DateFormat ScrollBarPolicy FocusPolicy + ContextMenuPolicy CaseSensitivity + LayoutDirection ArrowType) + Q_ENUMS(ToolButtonStyle) + Q_FLAGS(Alignment) + Q_FLAGS(Orientations) + Q_FLAGS(DockWidgetAreas) + + public: + ... + }; + \endcode - The Q_OBJECT macro, however, is an exception: QDoc - recognizes this particular non-standard construct, so there - is no need specifying it using the \tt {\l - Cpp.ignoredirectives} variable. + The Q_OBJECT macro, however, is an exception: QDoc recognizes this + particular non-standard construct, so there is no need specifying + it using the \tt {\l Cpp.ignoredirectives} variable. - Regarding the Q_CORE_EXPORT macro; see the documentation of - the \tt {\l Cpp.ignoretokens} variable. + Regarding the Q_CORE_EXPORT macro; see the documentation of the + \tt {\l Cpp.ignoretokens} variable. - See also \l Cpp.ignoretokens. + See also \l Cpp.ignoretokens. - \row - \o \bold Cpp.ignoretokens \target Cpp.ignoretokens - \o \bold {The \c Cpp.ignoretokens variable makes QDoc ignore - the specified non-standard constructs, within C++ source code.} + \target Cpp.ignoretokens-variable + \section1 Cpp.ignoretokens - If not specified by the \tt {\l Cpp.ignoretokens} or \tt - {\l Cpp.ignoredirectives} variables, non-standard - constructs (typically macros) can result in erroneous - documentation. + The \c Cpp.ignoretokens variable makes QDoc ignore the specified + non-standard constructs, within C++ source code. - In \l qt.qdocconf: + If not specified by the \tt {\l Cpp.ignoretokens} or \tt {\l + Cpp.ignoredirectives} variables, non-standard constructs + (typically macros) can result in erroneous documentation. - \code - Cpp.ignoretokens = QAXFACTORY_EXPORT \ - QM_EXPORT_CANVAS \ - ... - Q_COMPAT_EXPORT \ - Q_CORE_EXPORT \ - Q_EXPLICIT \ - Q_EXPORT \ - ... - Q_TYPENAME \ - Q_XML_EXPORT - \endcode + In \l qt.qdocconf: - makes sure that when processing the code below, for - example, QDoc will simply ignore the 'Q_CORE_EXPORT' - expression: + \code + Cpp.ignoretokens = QAXFACTORY_EXPORT \ + QM_EXPORT_CANVAS \ + ... + Q_COMPAT_EXPORT \ + Q_CORE_EXPORT \ + Q_EXPLICIT \ + Q_EXPORT \ + ... + Q_TYPENAME \ + Q_XML_EXPORT + \endcode - \code - class Q_CORE_EXPORT Qt { - Q_OBJECT - Q_ENUMS(Orientation TextFormat BackgroundMode - DateFormat ScrollBarPolicy FocusPolicy - ContextMenuPolicy CaseSensitivity - LayoutDirection ArrowType) - Q_ENUMS(ToolButtonStyle) - Q_FLAGS(Alignment) - Q_FLAGS(Orientations) - Q_FLAGS(DockWidgetAreas) - - public: - ... - }; - \endcode + makes sure that when processing the code below, for example, QDoc + will simply ignore the 'Q_CORE_EXPORT' expression: - Regarding the Q_OBJECT, Q_ENUMS and Q_FLAGS macros; see the - documentation of the \tt {\l Cpp.ignoredirectives} - variable. + \code + class Q_CORE_EXPORT Qt { + Q_OBJECT + Q_ENUMS(Orientation TextFormat BackgroundMode + DateFormat ScrollBarPolicy FocusPolicy + ContextMenuPolicy CaseSensitivity + LayoutDirection ArrowType) + Q_ENUMS(ToolButtonStyle) + Q_FLAGS(Alignment) + Q_FLAGS(Orientations) + Q_FLAGS(DockWidgetAreas) + public: + ... + }; + \endcode - See also \l Cpp.ignoredirectives. + Regarding the Q_OBJECT, Q_ENUMS and Q_FLAGS macros; see the + documentation of the \tt {\l Cpp.ignoredirectives} variable. - \endtable + See also \l Cpp.ignoredirectives. */ - /*! \page 24-qdoc-configuration-htmlvariables.html \previouspage C++ Specific Configuration Variables - \contentspage QDoc Manual - Table of Contents + \contentspage Table of Contents \nextpage Supporting Derived Projects \title HTML Specific Configuration Variables @@ -8279,219 +7961,188 @@ documentation's footer or postheader. The format of the variable values are raw HTML. - \section1 Alphabetical List - - \l {24-qdoc-configuration-htmlvariables.html#HTML.footer}{HTML.footer}, - \l {24-qdoc-configuration-htmlvariables.html#HTML.postheader} - {HTML.postheader}, - \l {24-qdoc-configuration-htmlvariables.html#HTML.style}{HTML.style}, - \l {24-qdoc-configuration-htmlvariables.html#HTML.stylesheets}{HTML.stylesheets} + \target HTML.footer-variable + \section1 HTML.footer + The \c HTML.footer variable defines the content of the generated + HTML documentation's footer. - \section1 Variable Descriptions + The footer is rendered at the bottom of the generated + documentation page. - \table + The variable's value is given as raw HTML code enclosed by + quotation marks. Note that if the value spans several lines, each + line needs to be enclosed by quotation marks. - \header - \o Variable - \o Description + For example in \l qt.qdocconf: - \row - \o \bold HTML.footer \target HTML.footer - \o \bold {The \c HTML.footer variable defines the content - of the generated HTML documentation's footer.} + \code + HTML.footer = "<p /><address><hr /><div align=\"center\">\n" \ + ... + "</tr></table></div></address>" + \endcode - The footer is rendered at the bottom of the generated - documentation page. + The complete variable entry in \l qt.qdocconf provides the + standard footer of the \l {http://qt.nokia.com/doc/4.0/index.html} + {Qt Reference Documentation}. - The variable's value is given as raw HTML code enclosed by - quotation marks. Note that if the value spans several - lines, each line needs to be enclosed by quotation marks. + \target HTML.postheader-variable + \section1 HTML.postheader - For example in \l qt.qdocconf: + The \c HTML.postheader variable defines the content of the + generated HTML documentation's postheader. - \code - HTML.footer = "<p /><address><hr /><div align=\"center\">\n" \ - ... - "</tr></table></div></address>" - \endcode + The header is rendered at the top of the generated documentation + page. - The complete variable entry in \l qt.qdocconf provides the - standard footer of the \l - {http://qt.nokia.com/doc/4.0/index.html}{Qt Reference - Documentation}. + The variable's value is given as raw HTML enclosed by quotation + marks. Note that if the value spans several lines, each line needs + to be enclosed by quotation marks. - \row - \o \bold HTML.postheader \target HTML.postheader - \o \bold {The \c HTML.postheader variable defines the content - of the generated HTML documentation's postheader.} + For example in \l qt.qdocconf: - The header is rendered at the top of the generated - documentation page. + \code + HTML.postheader = "<table border=\"0\"..." \ + ... + "<img src=\"images/trolltech-logo.png\" \ + "align=\"right\" width=\"203\" height=\"32\""\ + "border=\"0\" />" \ + "</td></tr>" \ + "</table>" + \endcode - The variable's value is given as raw HTML enclosed by - quotation marks. Note that if the value spans several - lines, each line needs to be enclosed by quotation marks. + The complete variable entry in \l qt.qdocconf provides the + standard header of the \l {http://qt.nokia.com/doc/4.0/index.html} + {Qt Reference Documentation}. - For example in \l qt.qdocconf: + \target HTML.style-variable + \section1 HTML.style - \code - HTML.postheader = "<table border=\"0\"..." \ - ... - "<img src=\"images/trolltech-logo.png\" \ - "align=\"right\" width=\"203\" height=\"32\""\ - "border=\"0\" />" \ - "</td></tr>" \ - "</table>" - \endcode + The HTML.style variable defines the style for + the generated HTML documentation. - The complete variable entry in \l qt.qdocconf provides the - standard header of the \l - {http://qt.nokia.com/doc/4.0/index.html}{Qt Reference - Documentation}. + The variable's value is given as raw HTML enclosed by quotation + marks. Note that if the value spans several lines, each line needs + to be enclosed by quotation marks. - \row - \o \bold HTML.style \target HTML.style - \o \bold {The HTML.style variable defines the style for - the generated HTML documentation.} + For example in \l qt.qdocconf: - The variable's value is given as raw HTML enclosed by - quotation marks. Note that if the value spans several - lines, each line needs to be enclosed by quotation marks. + \code + HTML.style = "h3.fn,span.fn" \ + "{ margin-left: 1cm; text-indent: -1cm; }\n" \ + "a:link { color: #004faf; text-decoration: none }\n" \ + "a:visited" \ + "{ color: #672967; text-decoration: none }\n" \ + "td.postheader { font-family: sans-serif }\n" \ + "tr.address { font-family: sans-serif }\n" \ + "body { background: #ffffff; color: black; }" + \endcode - For example in \l qt.qdocconf: + provides the HTML style for the \l + {http://qt.nokia.com/doc/4.0/index.html} {Qt Reference + Documentation}. - \code - HTML.style = "h3.fn,span.fn" \ - "{ margin-left: 1cm; text-indent: -1cm; }\n" \ - "a:link { color: #004faf; text-decoration: none }\n" \ - "a:visited" \ - "{ color: #672967; text-decoration: none }\n" \ - "td.postheader { font-family: sans-serif }\n" \ - "tr.address { font-family: sans-serif }\n" \ - "body { background: #ffffff; color: black; }" - \endcode + \target HTML.stylesheets-variable + \section1 HTML.stylesheets - provides the HTML style for the \l - {http://qt.nokia.com/doc/4.0/index.html}{Qt Reference - Documentation}. + The HTML.stylesheets variable defines a list of stylesheets + to use for the generated HTML documentation. - \row - \o \bold HTML.stylesheets \target HTML.stylesheets - \o \bold {The HTML.stylesheets variable defines a list of stylesheets - to use for the generated HTML documentation.} + Using separate stylesheets for the documentation makes it easier + to customize and experiment with the style used once the contents + has been generated. Typically, it is only necessary to define a + single stylesheet for any set of documentation; for example: - Using separate stylesheets for the documentation makes it easier to - customize and experiment with the style used once the contents has - been generated. Typically, it is only necessary to define a single - stylesheet for any set of documentation; for example: + \code + HTML.stylesheets = classic.css + \endcode - \code - HTML.stylesheets = classic.css - \endcode + QDoc expects to find stylesheets in the directory containing the + \l qt.qdocconf file, and it will copy those specified to the output + directory alongside the HTML pages. - QDoc expects to find stylesheets in the directory containing the - \l qt.qdocconf file, and it will copy those specified to the output - directory alongside the HTML pages. - \endtable */ /*! \page 25-qdoc-configuration-derivedprojects.html \previouspage HTML Specific Configuration Variables - \contentspage QDoc Manual - Table of Contents - \nextpage QDoc Compatibility + \contentspage Table of Contents + \nextpage Compatibility Issues \title Supporting Derived Projects - \tableofcontents + Some configuration variables allow you to use QDoc to support + Qt-based projects; i.e allow your project to contain links to the + online Qt documentation. This means that QDoc will be able to + create links to the class reference documentation, without any + explicit linking command. - Some particular configuration variables allow you to use QDoc to - support Qt-based projects; i.e to make projects, such as Qt Solutions, - contain references to the online Qt documentation. This - means that QDoc will be able to create links to the class reference - documentation, without any explicit linking command. + \target description-variable + \section1 description - \section1 The Configuration Variables + The description variable holds a short description of the + associated project. - \section2 Alphabetical List + See also \l project. - \l{25-qdoc-configuration-derivedprojects.html#description}{description}, - \l{25-qdoc-configuration-derivedprojects.html#indexes}{indexes}, - \l{25-qdoc-configuration-derivedprojects.html#project}{project}, - \l{25-qdoc-configuration-derivedprojects.html#url}{url} + \target indexes-variable + \section1 indexes - \section2 Variable Descriptions + The \c indexes variable lists the index files that will be used to + generate references. - \table - \header - \o Variable - \o Description - \row - \o \bold description \target description - \o \bold {The description variable holds a short description of - the associated project.} + For example. to make a derived Qt project contain links to the Qt + Reference documentation, you need to specify the associated index + file: - See also \l project. - - \row - \o \bold indexes \target indexes - \o \bold {The \c indexes variable lists the index files - that will be used to generate references.} - - For example. to make a derived Qt project contain links to - the Qt Reference documentation, you need to specify the - associated index file: + \code + indexes = $QTDIR/doc/html/qt.index + \endcode - \code - indexes = $QTDIR/doc/html/qt.index - \endcode + See also \l project and \l url. - See also \l project and \l url. + \target project-variable + \section1 project - \row - \o \bold project \target project - \o \bold {The \c project variable provides a name for the project - associated with the \c .qdocconf file.} + The \c project variable provides a name for the project associated + with the \c .qdocconf file. - The project's name is used to form a file name for the - associated project's \i index file. For example: + The project's name is used to form a file name for the associated + project's \e index file. - \code - project = QtMotif - \endcode + \code + project = QtMotif + \endcode - This will cause an index file called \c qtmotif.index to be - created. + This will cause an index file called \c qtmotif.index to be + created. - See also \l description and \l indexes. - \row - \o \bold url \target url - \o \bold {The \c url variable holds the base URL for the - reference documentation associated with the current project.} + See also \l description and \l indexes. - The URL is stored in the generated index file for the - project. When we use the index on its own, QDoc will use - this as the base URL when constructing links to classes, - functions, and other things listed in the index. + \target url-variable + \section1 url - For example: + The \c url variable holds the base URL for the reference + documentation associated with the current project. - \code - project = Qt - description = Qt Reference Documentation - url = http://qt.nokia.com/doc/4.0 + The URL is stored in the generated index file for the + project. When we use the index on its own, QDoc will use this as + the base URL when constructing links to classes, functions, and + other things listed in the index. - ... - \endcode + \code + project = Qt + description = Qt Reference Documentation + url = http://qt.nokia.com/doc/4.0 - This makes sure that whenever \c qt.index is used to generate - references to for example Qt classes, the base URL is - \c http://qt.nokia.com/doc/4.0. + ... + \endcode - See also \l indexes. + This makes sure that whenever \c qt.index is used to generate + references to for example Qt classes, the base URL is \c + http://qt.nokia.com/doc/4.0. - \endtable + See also \l indexes. \target howto \section1 How to Support Derived Projects @@ -8544,7 +8195,7 @@ The code above requires that you run QDoc from the directory that contains this file. You need to include the compat.qdocconf file for compatibility reasons; this is further explained in the - \l {QDoc Compatibility} section. + \l {Compatibility Issues} section. \bold {To resolve the actual links to Qt classes, the mini-project's \c .qdocconf file needs to assign a value to the \l @@ -8561,47 +8212,43 @@ /*! \page 26-qdoc-commands-compatibility.html \previouspage Supporting Derived Projects - \contentspage QDoc Manual - Table of Contents - \nextpage QDoc Commands - Alphabetical List + \contentspage Table of Contents + \nextpage qt.qdocconf - \title QDoc Compatibility - - \tableofcontents + \title Compatibility Issues \section1 General Description \target reason - QDoc is a tool that constantly evolves to suit our needs, for that - reason there are some compatibility issues in the transition - between old and new practices. + Because QDoc evolves to suit our documentation needs, there can be + some compatibility issues when converting to a new version. - To make the transition as smooth and rapid as possible, the - general idea is to adopt the new commands and usage in new - documentation. While waiting for the occurrences of the old - practices to be eliminated from the old parts of the - documentation, you can map the new commands and usage to the old - ones using a compat.qdocconf file. + To allow you to proceed at your own speed when converting your + qdoc comments to use new qdoc commands and formats, the ability to + include a configuration file called \c {compat.qdocconf} is + provided. - A compat.qdocconf file is a separate \c .qdocconf file which you - can include in your main configuration file. It typically contains - the mapping between old and new commands using the \l alias and \l - {22-qdoc-configuration-generalvariables.html#macro}{macro} - configuration variables. + A \c {compat.qdocconf} file is a separate configuration file, + which you include in your main configuration file. It typically + contains the mappings from old qdoc commands to new ones using + \l {alias} and + \l {22-qdoc-configuration-generalvariables.html#macro-variable} + {macro} configuration variables. \section1 Qt Compatibility In Qt's documentation there still exist occurrences of old - commands, and the Qt \l {qt.qdocconf}{configuration file} needs to + commands, and the Qt \l {qt.qdocconf} {configuration file} needs to include the compat.qdocconf file tailored for Qt. For more detailed information about the commands creating compatibility - issues, see the \l {Command Comments}{command comments}. + issues, see the \l {Command Comments} {command comments}. - \section2 Qt's current compat.qdocconf file + \section1 Qt's current compat.qdocconf file \quotefile files/compat.qdocconf - \section2 Command Comments + \section1 Command Comments \table \header @@ -8619,7 +8266,7 @@ \\e command name. \bold {We still need to use the \\e command to render in - italic in new documentation for \l {reason}{compatibility + italic in new documentation for \l {reason} {compatibility reasons}}. \row @@ -8633,7 +8280,7 @@ \bold {We still need to use the \\input command to include plain text in new documentation for \l - {reason}{compatibility reasons}}. + {reason} {compatibility reasons}}. \row \o \\quotefile \target quotefile-versus-include @@ -8646,7 +8293,7 @@ \bold {We still need to use the \\include command to quote the entire contents of a source file in new documentation - for \l {reason}{compatibility reasons}}. + for \l {reason} {compatibility reasons}}. \row \o \\quotefromfile \target quotefromfile-versus-quotefile @@ -8656,7 +8303,7 @@ that command to quote an entire file, we introduce the new \\quotefromfile command to quote from file. - \bold {Use \l {quotefromfile}{\\quotefromfile} to quote + \bold {Use \l {quotefromfile-command} {\\quotefromfile} to quote parts from a source file in new documentation}. \row @@ -8667,7 +8314,7 @@ in italic instead, we introduce the new \\o command for this purpose. - \bold {Use \l {o}{\\o} to indicate list and table items in + \bold {Use \l {o-command} {\\o} to indicate list and table items in new documentation}. \row @@ -8676,7 +8323,7 @@ \o These commands are equivalent, and represent a simple name change. - \bold {Use \l {quotation}{\\quotation} in new + \bold {Use \l {quotation} {\\quotation} in new documentation}. \row @@ -8685,116 +8332,129 @@ \o These commands are equivalent, and represent a simple name change. - \bold {Use \l {image}{\\image} in new documentation}. + \bold {Use \l {image-command} {\\image} in new documentation}. \endtable */ /*! \page 27-qdoc-commmands-alphabetical.html - \previouspage QDoc Compatibility - \contentspage QDoc Manual - Table of Contents + \previouspage Introduction to QDoc + \contentspage Table of Contents + \nextpage Topic Commands + + \title Command Index - \title QDoc Commands - Alphabetical List + This is a complete, alphabetized list of the QDoc commands. \list - \o \l {04-qdoc-commands-textformatting.html#a}{\\a} - \o \l {11-qdoc-commands-documentcontents.html#abstract}{\\abstract} - \o \l {06-qdoc-commands-verbatimcode.html#badcode}{\\badcode} - \o \l {04-qdoc-commands-textformatting.html#bold}{\\bold} - \o \l {11-qdoc-commands-documentcontents.html#brief}{\\brief} - \o \l {04-qdoc-commands-textformatting.html#c}{\\c} - \o \l {09-qdoc-commands-graphic.html#caption}{\\caption} - \o \l {05-qdoc-commands-documentstructuring.html#chapter}{\\chapter} - \o \l {13-qdoc-commands-topical.html#class}{\\class} - \o \l {06-qdoc-commands-verbatimcode.html#code}{\\code} - \o \l {07-0-qdoc-commands-quoting.html#codeline}{\\codeline}, - \o \l {16-qdoc-commands-status.html#compat}{\\compat} - \o \l {15-qdoc-commands-navigation.html#contentspage}{\\contentspage} - \o \l {07-0-qdoc-commands-quoting.html#dots}{\\dots} - \o \l {12-0-qdoc-commands-miscellaneous.html#else}{\\else} - \o \l {12-0-qdoc-commands-miscellaneous.html#endif}{\\endif} - \o \l {13-qdoc-commands-topical.html#enum}{\\enum} - \o \l {13-qdoc-commands-topical.html#example-command}{\\example} - \o \l {12-0-qdoc-commands-miscellaneous.html#expire}{\\expire} - \o \l {13-qdoc-commands-topical.html#externalpage}{\\externalpage} - \o \l {13-qdoc-commands-topical.html#fn}{\\fn} - \o \l {11-qdoc-commands-documentcontents.html#footnote}{\\footnote} - \o \l {12-0-qdoc-commands-miscellaneous.html#generatelist}{\\generatelist} - \o \l {13-qdoc-commands-topical.html#group}{\\group} - \o \l {10-qdoc-commands-container.html#header}{\\header} - \o \l {13-qdoc-commands-topical.html#headerfile}{\\headerfile} - \o \l {04-qdoc-commands-textformatting.html#i}{\\i} - \o \l {12-0-qdoc-commands-miscellaneous.html#if}{\\if} - \o \l {09-qdoc-commands-graphic.html#image}{\\image} - \o \l {12-0-qdoc-commands-miscellaneous.html#include}{\\include} - \o \l {15-qdoc-commands-navigation.html#indexpage}{\\indexpage} - \o \l {19-qdoc-commands-grouping.html#ingroup}{\\ingroup} - \o \l {19-qdoc-commands-grouping.html#inmodule}{\\inmodule} - \o \l {09-qdoc-commands-graphic.html#inlineimage}{\\inlineimage} - \o \l {16-qdoc-commands-status.html#internal}{\\internal} - \o \l {08-qdoc-commands-linking.html#keyword}{\\keyword} - \o \l {08-qdoc-commands-linking.html#l}{\\l} - \o \l {11-qdoc-commands-documentcontents.html#legalese}{\\legalese} - \o \l {10-qdoc-commands-container.html#list}{\\list} - \o \l {13-qdoc-commands-topical.html#macro}{\\macro} - \o \l {19-qdoc-commands-grouping.html#mainclass}{\\mainclass} - \o \l {12-0-qdoc-commands-miscellaneous.html#meta}{\\meta} - \o \l {13-qdoc-commands-topical.html#module}{\\module} - \o \l {13-qdoc-commands-topical.html#namespace}{\\namespace} - \o \l {15-qdoc-commands-navigation.html#nextpage}{\\nextpage} - \o \l {06-qdoc-commands-verbatimcode.html#newcode}{\\newcode} - \o \l {17-qdoc-commands-thread.html#nonreentrant}{\\nonreentrant} - \o \l {10-qdoc-commands-container.html#o}{\\o} - \o \l {16-qdoc-commands-status.html#obsolete}{\\obsolete} - \o \l {06-qdoc-commands-verbatimcode.html#oldcode}{\\oldcode} - \o \l {12-0-qdoc-commands-miscellaneous.html#omit}{\\omit} - \o \l {10-qdoc-commands-container.html#omitvalue}{\\omitvalue} - \o \l {18-qdoc-commands-relating.html#overload}{\\overload} - \o \l {13-qdoc-commands-topical.html#page}{\\page} - \o \l {05-qdoc-commands-documentstructuring.html#part}{\\part} - \o \l {16-qdoc-commands-status.html#preliminary}{\\preliminary} - \o \l {15-qdoc-commands-navigation.html#previouspage}{\\previouspage} - \o \l {07-0-qdoc-commands-quoting.html#printline}{\\printline} - \o \l {07-0-qdoc-commands-quoting.html#printto}{\\printto} - \o \l {07-0-qdoc-commands-quoting.html#printuntil}{\\printuntil} - \o \l {13-qdoc-commands-topical.html#property}{\\property} - \o \l {11-qdoc-commands-documentcontents.html#quotation}{\\quotation} - \o \l {07-0-qdoc-commands-quoting.html#quotefile}{\\quotefile} - \o \l {07-0-qdoc-commands-quoting.html#quotefromfile}{\\quotefromfile} - \o \l {12-0-qdoc-commands-miscellaneous.html#raw}{\\raw} - \o \l {17-qdoc-commands-thread.html#reentrant}{\\reentrant} - \o \l {18-qdoc-commands-relating.html#reimp}{\\reimp} - \o \l {18-qdoc-commands-relating.html#relates}{\\relates} - \o \l {10-qdoc-commands-container.html#row}{\\row} - \o \l {08-qdoc-commands-linking.html#sa}{\\sa} - \o \l {05-qdoc-commands-documentstructuring.html#sectionOne}{\\section1} - \o \l {05-qdoc-commands-documentstructuring.html#sectionTwo}{\\section2} - \o \l {05-qdoc-commands-documentstructuring.html#sectionThree}{\\section3} - \o \l {05-qdoc-commands-documentstructuring.html#sectionFour}{\\section4} - \o \l {13-qdoc-commands-topical.html#service}{\\service} - \o \l {16-qdoc-commands-status.html#since}{\\since} - \o \l {07-0-qdoc-commands-quoting.html#skipline}{\\skipline} - \o \l {07-0-qdoc-commands-quoting.html#skipto}{\\skipto} - \o \l {07-0-qdoc-commands-quoting.html#skipuntil}{\\skipuntil} - \o \l {07-0-qdoc-commands-quoting.html#snippet}{\\snippet}, - \o \l {15-qdoc-commands-navigation.html#startpage}{\\startpage} - \o \l {04-qdoc-commands-textformatting.html#sub}{\\sub} - \o \l {20-qdoc-commands-title.html#subtitle}{\\subtitle} - \o \l {04-qdoc-commands-textformatting.html#sup}{\\sup} - \o \l {10-qdoc-commands-container.html#table}{\\table} - \o \l {11-qdoc-commands-documentcontents.html#tableofcontents} - {\\tableofcontents} - \o \l {08-qdoc-commands-linking.html#target}{\\target} - \o \l {17-qdoc-commands-thread.html#threadsafe}{\\threadsafe} - \o \l {20-qdoc-commands-title.html#title}{\\title} - \o \l {04-qdoc-commands-textformatting.html#tt}{\\tt} - \o \l {13-qdoc-commands-topical.html#typedef}{\\typedef} - \o \l {04-qdoc-commands-textformatting.html#underline}{\\underline} - \o \l {13-qdoc-commands-topical.html#variable}{\\variable} - \o \l {10-qdoc-commands-container.html#value}{\\value} - \o \l {11-qdoc-commands-documentcontents.html#warning}{\\warning} + \o \l {04-qdoc-commands-textmarkup.html#a-command} {\\a} + \o \l {11-qdoc-commands-specialcontent.html#abstract-command} {\\abstract} + \o \l {06-qdoc-commands-includecodeinline.html#badcode-command} {\\badcode} + \o \l {04-qdoc-commands-textmarkup.html#bold-command} {\\bold} + \o \l {11-qdoc-commands-specialcontent.html#brief-command} {\\brief} + \o \l {04-qdoc-commands-textmarkup.html#c-command} {\\c} + \o \l {09-qdoc-commands-includingimages.html#caption-command} {\\caption} + \o \l {05-qdoc-commands-documentstructure.html#chapter-command} {\\chapter} + \o \l {13-qdoc-commands-topics.html#class-command} {\\class} + \o \l {06-qdoc-commands-includecodeinline.html#code-command} {\\code} + \o \l {07-0-qdoc-commands-includingexternalcode.html#codeline-command} {\\codeline}, + \o \l {16-qdoc-commands-status.html#compat-command} {\\compat} + \o \l {15-qdoc-commands-navigation.html#contentspage-command} {\\contentspage} + \o \l {16-qdoc-commands-status.html#default-command} {\\default} \span {class="newStuff"} {(new)} + \o \l {04-qdoc-commands-textmarkup.html#div-command} {\\div} \span {class="newStuff"} {(new)} + \o \l {07-0-qdoc-commands-includingexternalcode.html#dots-command} {\\dots} + \o \l {12-0-qdoc-commands-miscellaneous.html#else-command} {\\else} + \o \l {12-0-qdoc-commands-miscellaneous.html#endif-command} {\\endif} + \o \l {13-qdoc-commands-topics.html#enum-command} {\\enum} + \o \l {13-qdoc-commands-topics.html#example-command} {\\example} + \o \l {12-0-qdoc-commands-miscellaneous.html#expire-command} {\\expire} + \o \l {13-qdoc-commands-topics.html#externalpage-command} {\\externalpage} + \o \l {13-qdoc-commands-topics.html#fn-command} {\\fn} + \o \l {11-qdoc-commands-specialcontent.html#footnote-command} {\\footnote} + \o \l {12-0-qdoc-commands-miscellaneous.html#generatelist-command} {\\generatelist} + \o \l {13-qdoc-commands-topics.html#group-command} {\\group} + \o \l {10-qdoc-commands-tablesandlists.html#header-command} {\\header} + \o \l {13-qdoc-commands-topics.html#headerfile-command} {\\headerfile} + \o \l {04-qdoc-commands-textmarkup.html#i-command} {\\i} + \o \l {12-0-qdoc-commands-miscellaneous.html#if-command} {\\if} + \o \l {09-qdoc-commands-includingimages.html#image-command} {\\image} + \o \l {12-0-qdoc-commands-miscellaneous.html#include-command} {\\include} + \o \l {15-qdoc-commands-navigation.html#indexpage-command} {\\indexpage} + \o \l {19-qdoc-commands-grouping.html#ingroup-command} {\\ingroup} + \o \l {18-qdoc-commands-relating.html#inherits-command}{\\inherits} \span {class="newStuff"} {(new)} + \o \l {19-qdoc-commands-grouping.html#inmodule-command} {\\inmodule} + \o \l {09-qdoc-commands-includingimages.html#inlineimage-command} {\\inlineimage} + \o \l {16-qdoc-commands-status.html#internal-command} {\\internal} + \o \l {08-qdoc-commands-creatinglinks.html#keyword-command} {\\keyword} + \o \l {08-qdoc-commands-creatinglinks.html#l-command} {\\l} + \o \l {11-qdoc-commands-specialcontent.html#legalese-command} {\\legalese} + \o \l {10-qdoc-commands-tablesandlists.html#list-command} {\\list} + \o \l {13-qdoc-commands-topics.html#macro-command} {\\macro} + \o \l {19-qdoc-commands-grouping.html#mainclass-command} {\\mainclass} + \o \l {12-0-qdoc-commands-miscellaneous.html#meta-command} {\\meta} + \o \l {13-qdoc-commands-topics.html#module-command} {\\module} + \o \l {13-qdoc-commands-topics.html#namespace-command} {\\namespace} + \o \l {15-qdoc-commands-navigation.html#nextpage-command} {\\nextpage} + \o \l {06-qdoc-commands-includecodeinline.html#newcode-command} {\\newcode} + \o \l {17-qdoc-commands-thread.html#nonreentrant-command} {\\nonreentrant} + \o \l {10-qdoc-commands-tablesandlists.html#o-command} {\\o} + \o \l {16-qdoc-commands-status.html#obsolete-command} {\\obsolete} + \o \l {06-qdoc-commands-includecodeinline.html#oldcode-command} {\\oldcode} + \o \l {12-0-qdoc-commands-miscellaneous.html#omit-command} {\\omit} + \o \l {10-qdoc-commands-tablesandlists.html#omitvalue-command} {\\omitvalue} + \o \l {18-qdoc-commands-relating.html#overload-command} {\\overload} + \o \l {13-qdoc-commands-topics.html#page-command} {\\page} + \o \l {05-qdoc-commands-documentstructure.html#part-command} {\\part} + \o \l {16-qdoc-commands-status.html#preliminary-command} {\\preliminary} + \o \l {15-qdoc-commands-navigation.html#previouspage-command} {\\previouspage} + \o \l {07-0-qdoc-commands-includingexternalcode.html#printline-command} {\\printline} + \o \l {07-0-qdoc-commands-includingexternalcode.html#printto-command} {\\printto} + \o \l {07-0-qdoc-commands-includingexternalcode.html#printuntil-command} {\\printuntil} + \o \l {13-qdoc-commands-topics.html#property-command} {\\property} + \o \l {13-qdoc-commands-topics.html#qmlattachedproperty-command} {\\qmlattachedproperty} \span {class="newStuff"} {(new)} + \o \l {13-qdoc-commands-topics.html#qmlattachedsignal-command} {\\qmlattachedsignal} \span {class="newStuff"} {(new)} + \o \l {13-qdoc-commands-topics.html#qmlbasictype-command} {\\qmlbasictype} \span {class="newStuff"} {(new)} + \o \l {13-qdoc-commands-topics.html#qmlclass-command} {\\qmlclass} \span {class="newStuff"} {(new)} + \o \l {13-qdoc-commands-topics.html#qmlmethod-command} {\\qmlmethod} \span {class="newStuff"} {(new)} + \o \l {13-qdoc-commands-topics.html#qmlproperty-command} {\\qmlproperty} \span {class="newStuff"} {(new)} + \o \l {13-qdoc-commands-topics.html#qmlsignal-command} {\\qmlsignal} \span {class="newStuff"} {(new)} + \o \l {11-qdoc-commands-specialcontent.html#quotation-command} {\\quotation} + \o \l {07-0-qdoc-commands-includingexternalcode.html#quotefile-command} {\\quotefile} + \o \l {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command} {\\quotefromfile} + \o \l {12-0-qdoc-commands-miscellaneous.html#raw-command} {\\raw} \span {class="newStuff"} {(avoid)} + \o \l {17-qdoc-commands-thread.html#reentrant-command} {\\reentrant} + \o \l {18-qdoc-commands-relating.html#reimp-command} {\\reimp} + \o \l {18-qdoc-commands-relating.html#relates-command} {\\relates} + \o \l {10-qdoc-commands-tablesandlists.html#row-command} {\\row} + \o \l {08-qdoc-commands-creatinglinks.html#sa-command} {\\sa} + \o \l {05-qdoc-commands-documentstructure.html#sectionOne-command} {\\section1} + \o \l {05-qdoc-commands-documentstructure.html#sectionTwo-command} {\\section2} + \o \l {05-qdoc-commands-documentstructure.html#sectionThree-command} {\\section3} + \o \l {05-qdoc-commands-documentstructure.html#sectionFour-command} {\\section4} + \o \l {13-qdoc-commands-topics.html#service-command} {\\service} + \o \l {16-qdoc-commands-status.html#since-command} {\\since} + \o \l {07-0-qdoc-commands-includingexternalcode.html#skipline-command} {\\skipline} + \o \l {07-0-qdoc-commands-includingexternalcode.html#skipto-command} {\\skipto} + \o \l {07-0-qdoc-commands-includingexternalcode.html#skipuntil-command} {\\skipuntil} + \o \l {07-0-qdoc-commands-includingexternalcode.html#snippet-command} {\\snippet}, + \o \l {04-qdoc-commands-textmarkup.html#span-command} {\\span} \span {class="newStuff"} {(new)} + \o \l {15-qdoc-commands-navigation.html#startpage-command} {\\startpage} + \o \l {04-qdoc-commands-textmarkup.html#sub-command} {\\sub} + \o \l {20-qdoc-commands-namingthings.html#subtitle-command} {\\subtitle} + \o \l {04-qdoc-commands-textmarkup.html#sup-command} {\\sup} + \o \l {10-qdoc-commands-tablesandlists.html#table-command} {\\table} + \o \l {11-qdoc-commands-specialcontent.html#tableofcontents-command} {\\tableofcontents} + \o \l {08-qdoc-commands-creatinglinks.html#target-command} {\\target} + \o \l {17-qdoc-commands-thread.html#threadsafe-command} {\\threadsafe} + \o \l {20-qdoc-commands-namingthings.html#title-command} {\\title} + \o \l {04-qdoc-commands-textmarkup.html#tt-command} {\\tt} + \o \l {13-qdoc-commands-topics.html#typedef-command} {\\typedef} + \o \l {04-qdoc-commands-textmarkup.html#underline-command} {\\underline} + \o \l {13-qdoc-commands-topics.html#variable-command} {\\variable} + \o \l {10-qdoc-commands-tablesandlists.html#value-command} {\\value} + \o \l {11-qdoc-commands-specialcontent.html#warning-command} {\\warning} \endlist */ diff --git a/tools/qdoc3/doc/qdoc-manual.qdocconf b/tools/qdoc3/doc/qdoc-manual.qdocconf deleted file mode 100644 index 53486be..0000000 --- a/tools/qdoc3/doc/qdoc-manual.qdocconf +++ /dev/null @@ -1,234 +0,0 @@ -project = QDoc -description = QDoc3 Manual - -indexes = ../../../doc/html/qt.index - -outputdir = html - -sources = qdoc-manual.qdoc -sourcedirs = $PWD - -exampledirs += $PWD \ - ../../../examples - -imagedirs += images - -extraimages.HTML = qt-logo - -HTML.stylesheets = style/style.css \ - style/OfflineStyle.css \ - style/style_ie7.css \ - style/style_ie8.css \ - style/style_ie6.css - -HTML.postheader = " <div class=\"header\" id=\"qtdocheader\">\n" \ - " <div class=\"content\"> \n" \ - " <div id=\"nav-logo\">\n" \ - " <a href=\"index.html\">Home</a></div>\n" \ - " <a href=\"index.html\" class=\"qtref\"><span>Qt Reference Documentation</span></a>\n" \ - " <div id=\"narrowsearch\"></div>\n" \ - " <div id=\"nav-topright\">\n" \ - " <ul>\n" \ - " <li class=\"nav-topright-home\"><a href=\"http://qt.nokia.com/\">Qt HOME</a></li>\n" \ - " <li class=\"nav-topright-dev\"><a href=\"http://developer.qt.nokia.com/\">DEV</a></li>\n" \ - " <li class=\"nav-topright-labs\"><a href=\"http://labs.qt.nokia.com/blogs/\">LABS</a></li>\n" \ - " <li class=\"nav-topright-doc nav-topright-doc-active\"><a href=\"http://doc.qt.nokia.com/\">\n" \ - " DOC</a></li>\n" \ - " <li class=\"nav-topright-blog\"><a href=\"http://blog.qt.nokia.com/\">BLOG</a></li>\n" \ - " </ul>\n" \ - " </div>\n" \ - " <div id=\"shortCut\">\n" \ - " <ul>\n" \ - " <li class=\"shortCut-topleft-inactive\"><span><a href=\"index.html\">Qt 4.8</a></span></li>\n" \ - " <li class=\"shortCut-topleft-active\"><a href=\"http://doc.qt.nokia.com\">ALL VERSIONS" \ - " </a></li>\n" \ - " </ul>\n" \ - " </div>\n" \ - " <ul class=\"sf-menu\" id=\"narrowmenu\"> \n" \ - " <li><a href=\"#\">API Lookup</a> \n" \ - " <ul> \n" \ - " <li><a href=\"classes.html\">Class index</a></li> \n" \ - " <li><a href=\"functions.html\">Function index</a></li> \n" \ - " <li><a href=\"modules.html\">Modules</a></li> \n" \ - " <li><a href=\"namespaces.html\">Namespaces</a></li> \n" \ - " <li><a href=\"qtglobal.html\">Global Declarations</a></li> \n" \ - " <li><a href=\"qdeclarativeelements.html\">QML elements</a></li> \n" \ - " </ul> \n" \ - " </li> \n" \ - " <li><a href=\"#\">Qt Topics</a> \n" \ - " <ul> \n" \ - " <li><a href=\"qt-basic-concepts.html\">Programming with Qt</a></li> \n" \ - " <li><a href=\"qtquick.html\">Device UIs & Qt Quick</a></li> \n" \ - " <li><a href=\"qt-gui-concepts.html\">UI Design with Qt</a></li> \n" \ - " <li><a href=\"developing-with-qt.html\">Cross-platform and Platform-specific</a></li> \n" \ - " <li><a href=\"platform-specific.html\">Platform-specific info</a></li> \n" \ - " <li><a href=\"technology-apis.html\">Qt and Key Technologies</a></li> \n" \ - " <li><a href=\"best-practices.html\">How-To's and Best Practices</a></li> \n" \ - " </ul> \n" \ - " </li> \n" \ - " <li><a href=\"#\">Examples</a> \n" \ - " <ul> \n" \ - " <li><a href=\"all-examples.html\">Examples</a></li> \n" \ - " <li><a href=\"tutorials.html\">Tutorials</a></li> \n" \ - " <li><a href=\"demos.html\">Demos</a></li> \n" \ - " <li><a href=\"qdeclarativeexamples.html\">QML Examples</a></li> \n" \ - " </ul> \n" \ - " </li> \n" \ - " </ul> \n" \ - " </div>\n" \ - " </div>\n" \ - " <div class=\"wrapper\">\n" \ - " <div class=\"hd\">\n" \ - " <span></span>\n" \ - " </div>\n" \ - " <div class=\"bd group\">\n" \ - " <div class=\"sidebar\">\n" \ - " <div class=\"searchlabel\">\n" \ - " Search index:</div>\n" \ - " <div class=\"search\" id=\"sidebarsearch\">\n" \ - " <form id=\"qtdocsearch\" action=\"\" onsubmit=\"return false;\">\n" \ - " <fieldset>\n" \ - " <input type=\"text\" name=\"searchstring\" id=\"pageType\" value=\"\" />\n" \ - " <div id=\"resultdialog\"> \n" \ - " <a href=\"#\" id=\"resultclose\">Close</a> \n" \ - " <p id=\"resultlinks\" class=\"all\"><a href=\"#\" id=\"showallresults\">All</a> | <a href=\"#\" id=\"showapiresults\">API</a> | <a href=\"#\" id=\"showarticleresults\">Articles</a> | <a href=\"#\" id=\"showexampleresults\">Examples</a></p> \n" \ - " <p id=\"searchcount\" class=\"all\"><span id=\"resultcount\"></span><span id=\"apicount\"></span><span id=\"articlecount\"></span><span id=\"examplecount\"></span> results:</p> \n" \ - " <ul id=\"resultlist\" class=\"all\"> \n" \ - " </ul> \n" \ - " </div> \n" \ - " </fieldset>\n" \ - " </form>\n" \ - " </div>\n" \ - " <div class=\"box first bottombar\" id=\"lookup\">\n" \ - " <h2 title=\"API Lookup\"><span></span>\n" \ - " API Lookup</h2>\n" \ - " <div id=\"list001\" class=\"list\">\n" \ - " <ul id=\"ul001\" >\n" \ - " <li class=\"defaultLink\"><a href=\"classes.html\">Class index</a></li>\n" \ - " <li class=\"defaultLink\"><a href=\"functions.html\">Function index</a></li>\n" \ - " <li class=\"defaultLink\"><a href=\"modules.html\">Modules</a></li>\n" \ - " <li class=\"defaultLink\"><a href=\"namespaces.html\">Namespaces</a></li>\n" \ - " <li class=\"defaultLink\"><a href=\"qtglobal.html\">Global Declarations</a></li>\n" \ - " <li class=\"defaultLink\"><a href=\"qdeclarativeelements.html\">QML elements</a></li>\n" \ - " </ul> \n" \ - " </div>\n" \ - " </div>\n" \ - " <div class=\"box bottombar\" id=\"topics\">\n" \ - " <h2 title=\"Qt Topics\"><span></span>\n" \ - " Qt Topics</h2>\n" \ - " <div id=\"list002\" class=\"list\">\n" \ - " <ul id=\"ul002\" >\n" \ - " <li class=\"defaultLink\"><a href=\"qt-basic-concepts.html\">Programming with Qt</a></li> \n" \ - " <li class=\"defaultLink\"><a href=\"qtquick.html\">Device UIs & Qt Quick</a></li> \n" \ - " <li class=\"defaultLink\"><a href=\"qt-gui-concepts.html\">UI Design with Qt</a></li> \n" \ - " <li class=\"defaultLink\"><a href=\"developing-with-qt.html\">Cross-platform and Platform-specific</a></li> \n" \ - " <li class=\"defaultLink\"><a href=\"platform-specific.html\">Platform-specific info</a></li> \n" \ - " <li class=\"defaultLink\"><a href=\"technology-apis.html\">Qt and Key Technologies</a></li> \n" \ - " <li class=\"defaultLink\"><a href=\"best-practices.html\">How-To's and Best Practices</a></li> \n" \ - " </ul> \n" \ - " </div>\n" \ - " </div>\n" \ - " <div class=\"box\" id=\"examples\">\n" \ - " <h2 title=\"Examples\"><span></span>\n" \ - " Examples</h2>\n" \ - " <div id=\"list003\" class=\"list\">\n" \ - " <ul id=\"ul003\">\n" \ - " <li class=\"defaultLink\"><a href=\"all-examples.html\">Examples</a></li>\n" \ - " <li class=\"defaultLink\"><a href=\"tutorials.html\">Tutorials</a></li>\n" \ - " <li class=\"defaultLink\"><a href=\"demos.html\">Demos</a></li>\n" \ - " <li class=\"defaultLink\"><a href=\"qdeclarativeexamples.html\">QML Examples</a></li>\n" \ - " </ul> \n" \ - " </div>\n" \ - " </div>\n" \ - " </div>\n" \ - " <div class=\"wrap\">\n" \ - " <div class=\"toolbar\">\n" \ - " <div class=\"breadcrumb toolblock\">\n" \ - " <ul>\n" \ - " <li class=\"first\"><a href=\"index.html\">Home</a></li>\n" \ - " <!-- Bread crumbs goes here -->\n" - -HTML.postpostheader = " </ul>\n" \ - " </div>\n" \ - " <div class=\"toolbuttons toolblock\">\n" \ - " <ul>\n" \ - " <li id=\"smallA\" class=\"t_button\">A</li>\n" \ - " <li id=\"medA\" class=\"t_button active\">A</li>\n" \ - " <li id=\"bigA\" class=\"t_button\">A</li>\n" \ - " <li id=\"print\" class=\"t_button\"><a href=\"javascript:this.print();\">\n" \ - " <span>Print</span></a></li>\n" \ - " </ul>\n" \ - " </div>\n" \ - " </div>\n" \ - " <div class=\"content mainContent\">\n" - -HTML.footer = "" \ - " <div class=\"feedback t_button\">\n" \ - " [+] Documentation Feedback</div>\n" \ - " </div>\n" \ - " </div>\n" \ - " </div> \n" \ - " <div class=\"ft\">\n" \ - " <span></span>\n" \ - " </div>\n" \ - " </div> \n" \ - " <div class=\"footer\">\n" \ - " <p>\n" \ - " <acronym title=\"Copyright\">©</acronym> 2008-2011 Nokia Corporation and/or its\n" \ - " subsidiaries. Nokia, Qt and their respective logos are trademarks of Nokia Corporation \n" \ - " in Finland and/or other countries worldwide.</p>\n" \ - " <p>\n" \ - " All other trademarks are property of their respective owners. <a title=\"Privacy Policy\"\n" \ - " href=\"http://qt.nokia.com/about/privacy-policy\">Privacy Policy</a></p>\n" \ - " <br />\n" \ - " <p>\n" \ - " Licensees holding valid Qt Commercial licenses may use this document in accordance with the" \ - " Qt Commercial License Agreement provided with the Software or, alternatively, in accordance" \ - " with the terms contained in a written agreement between you and Nokia.</p>\n" \ - " <p>\n" \ - " Alternatively, this document may be used under the terms of the <a href=\"http://www.gnu.org/licenses/fdl.html\">GNU\n" \ - " Free Documentation License version 1.3</a>\n" \ - " as published by the Free Software Foundation.</p>\n" \ - " </div>\n" \ - " <div id=\"feedbackBox\">\n" \ - " <div id=\"feedcloseX\" class=\"feedclose t_button\">X</div>\n" \ - " <form id=\"feedform\" action=\"http://doc.qt.nokia.com/docFeedbck/feedback.php\" method=\"get\">\n" \ - " <p id=\"noteHead\">Thank you for giving your feedback.</p> <p class=\"note\">Make sure it is related to this specific page. For more general bugs and \n" \ - " requests, please use the <a href=\"http://bugreports.qt.nokia.com/secure/Dashboard.jspa\">Qt Bug Tracker</a>.</p>\n" \ - " <p><textarea id=\"feedbox\" name=\"feedText\" rows=\"5\" cols=\"40\"></textarea></p>\n" \ - " <p><input id=\"feedsubmit\" class=\"feedclose\" type=\"submit\" name=\"feedback\" /></p>\n" \ - " </form>\n" \ - " </div>\n" \ - " <div id=\"blurpage\">\n" \ - " </div>\n" - -# This stuff is used by the Qt 4.7 doc format. -scriptdirs = ../../../doc/src/template/scripts -styledirs = ../../../doc/src/template/style - -scripts.HTML = functions.js \ - narrow.js \ - superfish.js \ - jquery.js - -styles.HTML = style.css \ - narrow.css \ - superfish.css \ - superfish_skin.css \ - style_ie6.css \ - style_ie7.css \ - style_ie8.css - -# Files not referenced in any qdoc file (last four are needed by qtdemo) -# See also extraimages.HTML -qhp.Qt.extraFiles = scripts/functions.js \ - scripts/jquery.js \ - scripts/narrow.js \ - scripts/superfish.js \ - style/narrow.css \ - style/superfish.css \ - style/style_ie6.css \ - style/style_ie7.css \ - style/style_ie8.css \ - style/style.css - diff --git a/tools/qdoc3/helpprojectwriter.cpp b/tools/qdoc3/helpprojectwriter.cpp index f2e2f04..1c7fcbf 100644 --- a/tools/qdoc3/helpprojectwriter.cpp +++ b/tools/qdoc3/helpprojectwriter.cpp @@ -350,6 +350,14 @@ bool HelpProjectWriter::generateSection(HelpProject &project, } break; + case Node::Variable: + { + QString location = HtmlGenerator::fullDocumentLocation(node); + project.files.insert(location.left(location.lastIndexOf(QLatin1Char('#')))); + project.keywords.append(keywordDetails(node)); + } + break; + // Fake nodes (such as manual pages) contain subtypes, titles and other // attributes. case Node::Fake: { @@ -694,6 +702,8 @@ void HelpProjectWriter::generateProject(HelpProject &project) } } else { // Find a contents node and navigate from there, using the NextLink values. + QSet<QString> visited; + foreach (const Node *node, subproject.nodes) { QString nextTitle = node->links().value(Node::NextLink).first; if (!nextTitle.isEmpty() && @@ -707,9 +717,10 @@ void HelpProjectWriter::generateProject(HelpProject &project) while (nextPage) { writeNode(project, writer, nextPage); nextTitle = nextPage->links().value(Node::NextLink).first; - if(nextTitle.isEmpty()) + if (nextTitle.isEmpty() || visited.contains(nextTitle)) break; nextPage = const_cast<FakeNode *>(tree->findFakeNodeByTitle(nextTitle)); + visited.insert(nextTitle); } break; } diff --git a/tools/qdoc3/htmlgenerator.cpp b/tools/qdoc3/htmlgenerator.cpp index 0ff28af..2019e85 100644 --- a/tools/qdoc3/htmlgenerator.cpp +++ b/tools/qdoc3/htmlgenerator.cpp @@ -79,9 +79,9 @@ QString HtmlGenerator::sinceTitles[] = " New Properties", " New Variables", " New QML Elements", - " New Qml Properties", - " New Qml Signals", - " New Qml Methods", + " New QML Properties", + " New QML Signals", + " New QML Methods", "" }; @@ -401,6 +401,10 @@ int HtmlGenerator::generateAtom(const Atom *atom, switch (atom->type()) { case Atom::AbstractLeft: + if (relative) + relative->doc().location().warning(tr("\abstract is not implemented.")); + else + Location::information(tr("\abstract is not implemented.")); break; case Atom::AbstractRight: break; @@ -476,6 +480,17 @@ int HtmlGenerator::generateAtom(const Atom *atom, } out() << formattingRightMap()[ATOM_FORMATTING_TELETYPE]; break; + case Atom::CaptionLeft: + out() << "<p class=\"figCaption\">"; + in_para = true; + break; + case Atom::CaptionRight: + endLink(); + if (in_para) { + out() << "</p>\n"; + in_para = false; + } + break; case Atom::Code: out() << "<pre class=\"cpp\">" << trimmedTrailing(highlightedCode(indent(codeIndent,atom->string()), @@ -511,12 +526,14 @@ int HtmlGenerator::generateAtom(const Atom *atom, << trimmedTrailing(protectEnc(plainCode(indent(codeIndent,atom->string())))) << "</pre>\n"; break; - case Atom::Div: + case Atom::DivLeft: out() << "<div"; if (!atom->string().isEmpty()) - out() << " class=\"" << atom->string() << "\">"; - else - out() << ">"; + out() << " " << atom->string(); + out() << ">"; + break; + case Atom::DivRight: + out() << "</div>"; break; case Atom::FootnoteLeft: // ### For now @@ -535,7 +552,11 @@ int HtmlGenerator::generateAtom(const Atom *atom, case Atom::FormatIf: break; case Atom::FormattingLeft: - out() << formattingLeftMap()[atom->string()]; + if (atom->string().startsWith("span ")) { + out() << "<" + atom->string() << ">"; + } + else + out() << formattingLeftMap()[atom->string()]; if (atom->string() == ATOM_FORMATTING_PARAMETER) { if (atom->next() != 0 && atom->next()->type() == Atom::String) { QRegExp subscriptRegExp("([a-z]+)_([0-9n])"); @@ -551,6 +572,9 @@ int HtmlGenerator::generateAtom(const Atom *atom, if (atom->string() == ATOM_FORMATTING_LINK) { endLink(); } + else if (atom->string().startsWith("span ")) { + out() << "</span>"; + } else { out() << formattingRightMap()[atom->string()]; } @@ -891,9 +915,9 @@ int HtmlGenerator::generateAtom(const Atom *atom, if (threeColumnEnumValueTable) { out() << "<table class=\"valuelist\">"; if (++numTableRows % 2 == 1) - out() << "<tr class=\"odd\">"; + out() << "<tr valign=\"top\" class=\"odd\">"; else - out() << "<tr class=\"even\">"; + out() << "<tr valign=\"top\" class=\"even\">"; out() << "<th class=\"tblConst\">Constant</th>" << "<th class=\"tblval\">Value</th>" @@ -935,10 +959,10 @@ int HtmlGenerator::generateAtom(const Atom *atom, else { // (atom->string() == ATOM_LIST_VALUE) // ### Trenton - out() << "<tr><td class=\"topAlign\"><tt>" + out() << "<tr><td class=\"topAlign\"><tt>" << protectEnc(plainCode(marker->markedUpEnumValue(atom->next()->string(), relative))) - << "</tt></td><td class=\" topAlign\">"; + << "</tt></td><td class=\"topAlign\">"; QString itemValue; if (relative->type() == Node::Enum) { @@ -964,7 +988,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, } else if (atom->string() == ATOM_LIST_VALUE) { if (threeColumnEnumValueTable) { - out() << "</td><td class=\"topAlign\">"; + out() << "</td><td class=\"topAlign\">"; if (matchAhead(atom, Atom::ListItemRight)) out() << " "; } @@ -1056,8 +1080,10 @@ int HtmlGenerator::generateAtom(const Atom *atom, in_para = false; } if (!atom->string().isEmpty()) { - if (atom->string().contains("%")) - out() << "<table class=\"generic\">\n "; // width=\"" << atom->string() << "\">\n "; + if (atom->string().contains("%")) { + out() << "<table class=\"generic\" width=\"" + << atom->string() << "\">\n "; + } else { out() << "<table class=\"generic\">\n"; } @@ -1071,14 +1097,14 @@ int HtmlGenerator::generateAtom(const Atom *atom, out() << "</table>\n"; break; case Atom::TableHeaderLeft: - out() << "<thead><tr class=\"qt-style topAlign\">"; + out() << "<thead><tr class=\"qt-style\">"; inTableHeader = true; break; case Atom::TableHeaderRight: out() << "</tr>"; if (matchAhead(atom, Atom::TableHeaderLeft)) { skipAhead = 1; - out() << "\n<tr class=\"qt-style topAlign\">"; + out() << "\n<tr class=\"qt-style\">"; } else { out() << "</thead>\n"; @@ -1086,10 +1112,12 @@ int HtmlGenerator::generateAtom(const Atom *atom, } break; case Atom::TableRowLeft: - if (++numTableRows % 2 == 1) - out() << "<tr class=\"odd topAlign\">"; + if (!atom->string().isEmpty()) + out() << "<tr " << atom->string() << ">"; + else if (++numTableRows % 2 == 1) + out() << "<tr valign=\"top\" class=\"odd\">"; else - out() << "<tr class=\"even topAlign\">"; + out() << "<tr valign=\"top\" class=\"even\">"; break; case Atom::TableRowRight: out() << "</tr>\n"; @@ -1101,16 +1129,28 @@ int HtmlGenerator::generateAtom(const Atom *atom, else out() << "<td "; - QStringList spans = atom->string().split(","); - if (spans.size() == 2) { - if (spans.at(0) != "1") - out() << " colspan=\"" << spans.at(0) << "\""; - if (spans.at(1) != "1") - out() << " rowspan=\"" << spans.at(1) << "\""; + for (int i=0; i<atom->count(); ++i) { + if (i > 0) + out() << " "; + QString p = atom->string(i); + if (p.contains('=')) { + out() << p; + } + else { + QStringList spans = p.split(","); + if (spans.size() == 2) { + if (spans.at(0) != "1") + out() << " colspan=\"" << spans.at(0) << "\""; + if (spans.at(1) != "1") + out() << " rowspan=\"" << spans.at(1) << "\""; + } + } + } if (inTableHeader) out() << ">"; - else - out() << "><p>"; + else { + out() << ">"; + //out() << "><p>"; } if (matchAhead(atom, Atom::ParaLeft)) skipAhead = 1; @@ -1119,8 +1159,10 @@ int HtmlGenerator::generateAtom(const Atom *atom, case Atom::TableItemRight: if (inTableHeader) out() << "</th>"; - else - out() << "</p></td>"; + else { + out() << "</td>"; + //out() << "</p></td>"; + } if (matchAhead(atom, Atom::ParaLeft)) skipAhead = 1; break; @@ -1136,9 +1178,6 @@ int HtmlGenerator::generateAtom(const Atom *atom, out() << "<b class=\"redFont\"><code>\\" << protectEnc(atom->string()) << "</code></b>"; break; - case Atom::EndDiv: - out() << "</div>"; - break; #ifdef QDOC_QML case Atom::QmlText: case Atom::EndQmlText: @@ -2571,7 +2610,7 @@ void HtmlGenerator::generateSection(const NodeList& nl, else { if (twoColumn) out() << "<table class=\"propsummary\">\n" - << "<tr><td class=\"topAlign\">"; + << "<tr><td class=\"topAlign\">"; out() << "<ul>\n"; } @@ -2588,7 +2627,7 @@ void HtmlGenerator::generateSection(const NodeList& nl, } else { if (twoColumn && i == (int) (nl.count() + 1) / 2) - out() << "</ul></td><td class=\"topAlign\"><ul>\n"; + out() << "</ul></td><td class=\"topAlign\"><ul>\n"; out() << "<li class=\"fn\">"; } @@ -2632,7 +2671,7 @@ void HtmlGenerator::generateSectionList(const Section& section, else { if (twoColumn) out() << "<table class=\"propsummary\">\n" - << "<tr><td class=\"topAlign\">"; + << "<tr><td class=\"topAlign\">"; out() << "<ul>\n"; } @@ -3833,9 +3872,9 @@ void HtmlGenerator::generateDetailedQmlMember(const Node *node, if ((*p)->type() == Node::QmlProperty) { qpn = static_cast<const QmlPropertyNode*>(*p); if (++numTableRows % 2 == 1) - out() << "<tr class=\"odd\">"; + out() << "<tr valign=\"top\" class=\"odd\">"; else - out() << "<tr class=\"even\">"; + out() << "<tr valign=\"top\" class=\"even\">"; out() << "<td class=\"tblQmlPropNode\"><p>"; @@ -3860,9 +3899,9 @@ void HtmlGenerator::generateDetailedQmlMember(const Node *node, out() << "<table class=\"qmlname\">"; //out() << "<tr>"; if (++numTableRows % 2 == 1) - out() << "<tr class=\"odd\">"; + out() << "<tr valign=\"top\" class=\"odd\">"; else - out() << "<tr class=\"even\">"; + out() << "<tr valign=\"top\" class=\"even\">"; out() << "<td class=\"tblQmlFuncNode\"><p>"; out() << "<a name=\"" + refForNode(qsn) + "\"></a>"; generateSynopsis(qsn,relative,marker,CodeMarker::Detailed,false); @@ -3877,9 +3916,9 @@ void HtmlGenerator::generateDetailedQmlMember(const Node *node, out() << "<table class=\"qmlname\">"; //out() << "<tr>"; if (++numTableRows % 2 == 1) - out() << "<tr class=\"odd\">"; + out() << "<tr valign=\"top\" class=\"odd\">"; else - out() << "<tr class=\"even\">"; + out() << "<tr valign=\"top\" class=\"even\">"; out() << "<td class=\"tblQmlFuncNode\"><p>"; out() << "<a name=\"" + refForNode(qmn) + "\"></a>"; generateSynopsis(qmn,relative,marker,CodeMarker::Detailed,false); diff --git a/tools/qdoc3/node.cpp b/tools/qdoc3/node.cpp index 7195322..0f85d37 100644 --- a/tools/qdoc3/node.cpp +++ b/tools/qdoc3/node.cpp @@ -771,6 +771,30 @@ void InnerNode::removeChild(Node *child) } } +/*! \fn QString InnerNode::author() const + Returns the author. + */ + +/*! \fn void InnerNode::setAuthor(const QString& author) + Sets the \a author. + */ + +/*! \fn QString InnerNode::publisher() const + Returns the publisher. + */ + +/*! \fn void InnerNode::setPublisher(const QString& publisher) + Sets the \a publisher. + */ + +/*! \fn QString InnerNode::permissions() const + Returns the permissions. + */ + +/*! \fn void InnerNode::setPermissions(const QString& permissions) + Sets the \a permissions. + */ + /*! Find the module (QtCore, QtGui, etc.) to which the class belongs. We do this by obtaining the full path to the header file's location @@ -834,6 +858,21 @@ void InnerNode::removeRelated(Node *pseudoChild) related.removeAll(pseudoChild); } +/*! \fn bool InnerNode::hasOtherMetadata() const + Returns tru if the other metadata map is not empty. + */ + +/*! + Insert the pair \a name and \a content into the other metadata map. + */ +void insertOtherMetadata(const QString& name, const QString& content) +{ +} + +/*! \fn const QMap<QString, QString>& InnerNode::otherMetadata() cont + Returns the map containing pairs for output as \c {<othermetadata>}. + */ + /*! \class LeafNode */ @@ -947,10 +986,35 @@ void ClassNode::fixBaseClasses() Search the child list to find the property node with the specified \a name. */ -const PropertyNode* ClassNode::findPropertyNode(const QString& name) const +const PropertyNode *ClassNode::findPropertyNode(const QString &name) const { - const Node* n = findNode(name,Node::Property); - return (n ? static_cast<const PropertyNode*>(n) : 0); + const Node *n = findNode(name, Node::Property); + + if (n) + return static_cast<const PropertyNode*>(n); + + const PropertyNode *pn = 0; + + const QList<RelatedClass> &bases = baseClasses(); + if (!bases.isEmpty()) { + for (int i = 0; i < bases.size(); ++i) { + const ClassNode *cn = bases[i].node; + pn = cn->findPropertyNode(name); + if (pn) + break; + } + } + const QList<RelatedClass>& ignoredBases = ignoredBaseClasses(); + if (!ignoredBases.isEmpty()) { + for (int i = 0; i < ignoredBases.size(); ++i) { + const ClassNode *cn = ignoredBases[i].node; + pn = cn->findPropertyNode(name); + if (pn) + break; + } + } + + return pn; } /*! @@ -1406,6 +1470,7 @@ PropertyNode::PropertyNode(InnerNode *parent, const QString& name) usr(Trool_Default), cst(false), fnl(false), + rev(-1), overrides(0) { // nothing. @@ -1657,7 +1722,7 @@ bool QmlPropertyNode::fromTrool(Trool troolean, bool defaultValue) } } -static QString valueType(const QString& n) +static QString valueType(const QString &n) { if (n == "QPoint") return "QDeclarativePointValueType"; @@ -1700,6 +1765,19 @@ bool QmlPropertyNode::isWritable(const Tree* tree) const if (wri != Trool_Default) return fromTrool(wri, false); + const PropertyNode *pn = correspondingProperty(tree); + if (pn) + return pn->isWritable(); + else { + location().warning(tr("Can't determine read-only status of QML property %1; writable assumed.").arg(name())); + return true; + } +} + +const PropertyNode *QmlPropertyNode::correspondingProperty(const Tree *tree) const +{ + const PropertyNode *pn; + Node* n = parent(); while (n && n->subType() != Node::QmlClass) n = n->parent(); @@ -1708,93 +1786,35 @@ bool QmlPropertyNode::isWritable(const Tree* tree) const const ClassNode* cn = qcn->classNode(); if (cn) { QStringList dotSplit = name().split(QChar('.')); - const PropertyNode* pn = cn->findPropertyNode(dotSplit[0]); + pn = cn->findPropertyNode(dotSplit[0]); if (pn) { if (dotSplit.size() > 1) { + // Find the C++ property corresponding to the QML property in + // the property group, <group>.<property>. + QStringList path(extractClassName(pn->qualifiedDataType())); const Node* nn = tree->findNode(path,Class); if (nn) { const ClassNode* cn = static_cast<const ClassNode*>(nn); - pn = cn->findPropertyNode(dotSplit[1]); - if (pn) { - return pn->isWritable(); - } - else { - const QList<RelatedClass>& bases = cn->baseClasses(); - if (!bases.isEmpty()) { - for (int i=0; i<bases.size(); ++i) { - const ClassNode* cn = bases[i].node; - pn = cn->findPropertyNode(dotSplit[1]); - if (pn) { - return pn->isWritable(); - } - } - } - const QList<RelatedClass>& ignoredBases = cn->ignoredBaseClasses(); - if (!ignoredBases.isEmpty()) { - for (int i=0; i<ignoredBases.size(); ++i) { - const ClassNode* cn = ignoredBases[i].node; - pn = cn->findPropertyNode(dotSplit[1]); - if (pn) { - return pn->isWritable(); - } - } - } - QString vt = valueType(cn->name()); - if (!vt.isEmpty()) { - QStringList path(vt); - const Node* vtn = tree->findNode(path,Class); - if (vtn) { - const ClassNode* cn = static_cast<const ClassNode*>(vtn); - pn = cn->findPropertyNode(dotSplit[1]); - if (pn) { - return pn->isWritable(); - } - } - } - } + const PropertyNode *pn2 = cn->findPropertyNode(dotSplit[1]); + if (pn2) + return pn2; // Return the property for the QML property. + else + return pn; // Return the property for the QML group. } } - else { - return pn->isWritable(); - } + else + return pn; } else { - const QList<RelatedClass>& bases = cn->baseClasses(); - if (!bases.isEmpty()) { - for (int i=0; i<bases.size(); ++i) { - const ClassNode* cn = bases[i].node; - pn = cn->findPropertyNode(dotSplit[0]); - if (pn) { - return pn->isWritable(); - } - } - } - const QList<RelatedClass>& ignoredBases = cn->ignoredBaseClasses(); - if (!ignoredBases.isEmpty()) { - for (int i=0; i<ignoredBases.size(); ++i) { - const ClassNode* cn = ignoredBases[i].node; - pn = cn->findPropertyNode(dotSplit[0]); - if (pn) { - return pn->isWritable(); - } - } - } - if (isAttached()) { - QString classNameAttached = cn->name() + "Attached"; - QStringList path(classNameAttached); - const Node* nn = tree->findNode(path,Class); - const ClassNode* acn = static_cast<const ClassNode*>(nn); - pn = acn->findPropertyNode(dotSplit[0]); - if (pn) { - return pn->isWritable(); - } - } + pn = cn->findPropertyNode(dotSplit[0]); + if (pn) + return pn; } } } - location().warning(tr("Can't determine read-only status of QML property %1; writable assumed.").arg(name())); - return true; + + return 0; } #endif diff --git a/tools/qdoc3/node.h b/tools/qdoc3/node.h index aa7c78a..2de2b5a 100644 --- a/tools/qdoc3/node.h +++ b/tools/qdoc3/node.h @@ -262,12 +262,21 @@ class InnerNode : public Node NodeList overloads(const QString &funcName) const; const QStringList& includes() const { return inc; } + QString author() const { return author_; } + void setAuthor(const QString& author) { author_ = author; } + QString publisher() const { return publisher_; } + void setPublisher(const QString& publisher) { publisher_ = publisher; } + QString permissions() const { return permissions_; } + void setPermissions(const QString& permissions) { permissions_ = permissions; } QStringList primaryKeys(); QStringList secondaryKeys(); const QStringList& pageKeywords() const { return pageKeywds; } virtual void addPageKeywords(const QString& t) { pageKeywds << t; } virtual bool isAbstract() const { return false; } virtual void setAbstract(bool ) { } + bool hasOtherMetadata() const { return !otherMetadataMap.isEmpty(); } + void insertOtherMetadata(const QString& name, const QString& content); + const QMap<QString, QString>& otherMetadata() const { return otherMetadataMap; } protected: InnerNode(Type type, InnerNode* parent, const QString& name); @@ -280,6 +289,9 @@ class InnerNode : public Node void removeChild(Node* child); void removeRelated(Node* pseudoChild); + QString author_; + QString publisher_; + QString permissions_; QStringList pageKeywds; QStringList inc; NodeList children; @@ -288,6 +300,7 @@ class InnerNode : public Node QMap<QString, Node*> childMap; QMap<QString, Node*> primaryFunctionMap; QMap<QString, NodeList> secondaryFunctionMap; + QMap<QString, QString> otherMetadataMap; }; class LeafNode : public Node @@ -466,6 +479,8 @@ class QmlPropertyNode : public LeafNode bool isAttached() const { return att; } virtual bool isQmlNode() const { return true; } + const PropertyNode *correspondingProperty(const Tree *tree) const; + const QString& element() const { return static_cast<QmlPropGroupNode*>(parent())->element(); } private: @@ -689,6 +704,7 @@ class PropertyNode : public LeafNode void setRuntimeScrFunc(const QString& scrf) { runtimeScrFunc = scrf; } void setConstant() { cst = true; } void setFinal() { fnl = true; } + void setRevision(int revision) { rev = revision; } const QString &dataType() const { return dt; } QString qualifiedDataType() const; @@ -732,6 +748,7 @@ class PropertyNode : public LeafNode Trool usr; bool cst; bool fnl; + int rev; const PropertyNode* overrides; }; diff --git a/tools/qdoc3/qdoc3.pro b/tools/qdoc3/qdoc3.pro index 2fedc0f..5b4131f 100644 --- a/tools/qdoc3/qdoc3.pro +++ b/tools/qdoc3/qdoc3.pro @@ -93,10 +93,24 @@ include($$QT_SOURCE_TREE/src/declarative/qml/parser/parser.pri) ### Documentation for qdoc3 ### qtPrepareTool(QDOC, qdoc3) +qtPrepareTool(QHELPGENERATOR, qhelpgenerator) -html-docs.commands = cd \"$$PWD/doc\" && $$QDOC qdoc-manual.qdocconf +$$unixstyle { + QDOC = QT_BUILD_TREE=$$QT_BUILD_TREE QT_SOURCE_TREE=$$QT_SOURCE_TREE $$QDOC +} else { + QDOC = set QT_BUILD_TREE=$$QT_BUILD_TREE&& set QT_SOURCE_TREE=$$QT_SOURCE_TREE&& $$QDOC + QDOC = $$replace(QDOC, "/", "\\") +} + +html-docs.commands = cd \"$$QT_BUILD_TREE/doc\" && $$QDOC $$QT_SOURCE_TREE/tools/qdoc3/doc/config/qdoc.qdocconf +html-docs.files = $$QT_BUILD_TREE/doc/html + +qch-docs.commands = cd \"$$QT_BUILD_TREE/doc\" && $$QHELPGENERATOR $$QT_BUILD_TREE/tools/qdoc3/doc/html/qdoc.qhp -o $$QT_BUILD_TREE/tools/qdoc3/doc/qch/qdoc.qch +qch-docs.files = $$QT_BUILD_TREE/tools/qdoc3/doc/qch +qch-docs.path = $$[QT_INSTALL_DOCS] +qch-docs.CONFIG += no_check_exist directory -QMAKE_EXTRA_TARGETS += html-docs +QMAKE_EXTRA_TARGETS += html-docs qch-docs target.path = $$[QT_INSTALL_BINS] INSTALLS += target diff --git a/tools/qdoc3/qmlcodeparser.cpp b/tools/qdoc3/qmlcodeparser.cpp index 269a566..9652322 100644 --- a/tools/qdoc3/qmlcodeparser.cpp +++ b/tools/qdoc3/qmlcodeparser.cpp @@ -142,7 +142,7 @@ void QmlCodeParser::doneParsingSourceFiles(Tree *tree) } /*! - Returns the set of strings reopresenting the topic commands. + Returns the set of strings representing the topic commands. */ QSet<QString> QmlCodeParser::topicCommands() { diff --git a/tools/qdoc3/test/qt-html-templates-online.qdocconf b/tools/qdoc3/test/qt-html-templates-online.qdocconf index dc84e7d..77ab3c5 100644 --- a/tools/qdoc3/test/qt-html-templates-online.qdocconf +++ b/tools/qdoc3/test/qt-html-templates-online.qdocconf @@ -40,8 +40,7 @@ HTML.postheader = \ " <li><a href=\"qt-basic-concepts.html\">Programming with Qt</a></li> \n" \ " <li><a href=\"qtquick.html\">Device UIs & Qt Quick</a></li> \n" \ " <li><a href=\"qt-gui-concepts.html\">UI Design with Qt</a></li> \n" \ - " <li><a href=\"developing-with-qt.html\">Cross-platform and Platform-specific</a></li> \n" \ - " <li><a href=\"platform-specific.html\">Platform-specific info</a></li> \n" \ + " <li><a href=\"supported-platforms.html\">Supported Platforms</a></li> \n" \ " <li><a href=\"technology-apis.html\">Qt and Key Technologies</a></li> \n" \ " <li><a href=\"best-practices.html\">How-To's and Best Practices</a></li> \n" \ " </ul> \n" \ @@ -101,8 +100,7 @@ HTML.postheader = \ " <li class=\"defaultLink\"><a href=\"qt-basic-concepts.html\">Programming with Qt</a></li> \n" \ " <li class=\"defaultLink\"><a href=\"qtquick.html\">Device UIs & Qt Quick</a></li> \n" \ " <li class=\"defaultLink\"><a href=\"qt-gui-concepts.html\">UI Design with Qt</a></li> \n" \ - " <li class=\"defaultLink\"><a href=\"developing-with-qt.html\">Cross-platform and Platform-specific</a></li> \n" \ - " <li class=\"defaultLink\"><a href=\"platform-specific.html\">Platform-specific info</a></li> \n" \ + " <li class=\"defaultLink\"><a href=\"supported-platforms.html\">Supported Platforms</a></li> \n" \ " <li class=\"defaultLink\"><a href=\"technology-apis.html\">Qt and Key Technologies</a></li> \n" \ " <li class=\"defaultLink\"><a href=\"best-practices.html\">How-To's and Best Practices</a></li> \n" \ " </ul> \n" \ @@ -196,37 +194,3 @@ HTML.footer = \ " var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);\n" \ " })();\n" \ " </script>\n" - - -# Files not referenced in any qdoc file. -# See also extraimages.HTML -qhp.Qt.extraFiles = index.html \ - images/bg_l.png \ - images/bg_l_blank.png \ - images/bg_ll_blank.png \ - images/bg_ul_blank.png \ - images/header_bg.png \ - images/bg_r.png \ - images/box_bg.png \ - images/breadcrumb.png \ - images/bullet_gt.png \ - images/bullet_dn.png \ - images/bullet_sq.png \ - images/bullet_up.png \ - images/arrow_down.png \ - images/feedbackground.png \ - images/horBar.png \ - images/page.png \ - images/page_bg.png \ - images/sprites-combined.png \ - images/spinner.gif \ - scripts/functions.js \ - scripts/jquery.js \ - scripts/narrow.js \ - scripts/superfish.js \ - style/narrow.css \ - style/superfish.css \ - style/style_ie6.css \ - style/style_ie7.css \ - style/style_ie8.css \ - style/style.css |
