diff options
Diffstat (limited to 'doc')
153 files changed, 4861 insertions, 0 deletions
diff --git a/doc/src/animation.qdoc b/doc/src/animation.qdoc new file mode 100644 index 0000000..081660c --- /dev/null +++ b/doc/src/animation.qdoc @@ -0,0 +1,365 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page animation.html + \title The Animation Framework + \ingroup architecture + \ingroup animation + \brief An overview of the Animation Framework + + \keyword Animation + + The animation framework is part of the Kinetic project, and aims + to provide an easy way for creating animated and smooth GUI's. By + animating Qt properties, the framework provides great freedom for + animating widgets and other \l{QObject}s. The framework can also + be used with the Graphics View framework. + + In this overview, we explain the basics of its architecture. We + also show examples of the most common techniques that the + framework allows for animating QObjects and graphics items. + + \tableofcontents + + \section1 The Animation Architecture + + We will in this section take a high-level look at the animation + framework's architecture and how it is used to animate Qt + properties. + + The animation framework foundation consists of the base class + QAbstractAnimation, and its two subclasses QVariantAnimation and + QAnimationGroup. QAbstractAnimation is the ancestor of all + animations. It represents basic properties that are common for all + animations in the framework; notably, the ability to start, stop, + and pause an animation. It is also receives the time change + notifications. + + The animation framework further provides the QPropertyAnimation + class, which inherits QVariantAnimation and performs animation of + a Qt property, which is part of Qt's \l{Meta-Object + System}{meta-object system}. The class performs an interpolation + over the property using an easing curve. So when you want to + animate a value, you can declare it as a property and make your + class a QObject. Note that this gives us great freedom in + animating already existing widgets and other \l{QObject}s. + + Complex animations can be constructed by building a tree structure + of \l{QAbstractAnimation}s. The tree is built by using + \l{QAnimationGroup}s, which function as containers for other + animations. Note also that the groups are subclasses of + QAbstractAnimation, so groups can themselves contain other groups. + + The animation framework can be used on its own, but is also + designed to be part of the state machine framework (See the + \l{The State Machine Framework}{state machine framework} for an + introduction to the Qt state machine). The state machine provides + a special state that can play an animation. A QState can also set + properties when the state is entered or exited, and this special + animation state will interpolate between these values when given a + QPropertyAnimation. We will look more closely at this later. + + Behind the scenes, the animations are controlled by a global + timer, which sends \l{QAbstractAnimation::updateCurrentTime()}{updates} to + all animations that are playing. + + For detailed descriptions of the classes' function and roles in + the framework, please look up their class descriptions. + + \section1 Animating Qt Properties + + As mentioned in the previous section, the QPropertyAnimation class + can interpolate over Qt properties. It is this class that should + be used for animation of values; in fact, its superclass, + QVariantAnimation, is an abstract class, and cannot be used + directly. + + A major reason we chose to animate Qt properties is that it + presents us with freedom to animate already existing classes in + the Qt API. Notably, the QWidget class (which we can also embed in + a QGraphicsView) has properties for its bounds, colors, etc. + Let's look at a small example: + + \code + QPushButton button("Animated Button"); + button.show(); + + QPropertyAnimation animation(&button, "geometry"); + animation.setDuration(10000); + animation.setStartValue(QRect(0, 0, 100, 30)); + animation.setEndValue(QRect(250, 250, 100, 30)); + + animation.start(); + \endcode + + This code will move \c button from the top left corner of the + screen to the position (250, 250). + + The example above will do a linear interpolation between the + start and end value. It is also possible to set values + situated between the start and end value. The interpolation + will then go by these points. + + \code + QPushButton button("Animated Button"); + button.show(); + + QPropertyAnimation animation(&button, "geometry"); + animation.setDuration(10000); + + animation.setKeyValueAt(0, QRect(0, 0, 100, 30)); + animation.setKeyValueAt(0.8, QRect(250, 250, 100, 30)); + animation.setKeyValueAt(1, QRect(0, 0, 100, 30)); + + animation.start(); + \endcode + + In this example, the animation will take the button to (250, 250) + in 8 seconds, and then move it back to its original position in + the remaining 2 seconds. The movement will be linearly + interpolated between these points. + + You also have the possibility to animate values of a QObject + that is not declared as a Qt property. The only requirement is + that this value has a setter. You can then subclass the class + containing the value and declare a property that uses this setter. + Note that all Qt properties requires a getter, so you will need to + provide a getter yourself if this is not defined. + + \code + class MyGraphicsRectItem : public QObject, public QGraphicsRectItem + { + Q_OBJECT + Q_PROPERTY(QRectF geometry READ geometry WRITE setGeometry) + }; + \endcode + + In the above code example, we subclass QGraphicsRectItem and + define a geometry property. We can now animate the widgets + geometry even if QGraphicsRectItem does not provide the geometry + property. + + For a general introduction to the Qt property system, see its + \l{Qt's Property System}{overview}. + + \section1 Animations and the Graphics View Framework + + When you want to animate \l{QGraphicsItem}s, you also use + QPropertyAnimation. But, unfortunetly, QGraphicsItem does not + inherit QObject. A good solution is to subclass the graphics item + you wish to animate. This class will then also inherit QObject. + This way, QPropertyAnimation can be used for \l{QGraphicsItem}s. + The example below shows how this is done. Another possibility is + to inherit QGraphicsWidget, which already is a QObject. + + \code + class Pixmap : public QObject, public QGraphicsPixmapItem + { + Q_OBJECT + Q_PROPERTY(QPointF pos READ pos WRITE setPos) + ... + \endcode + + As described in the previous section, we need to define + properties that we wish to animate. + + Note that QObject must be the first class inherited as the + meta-object system demands this. + + \warning The QItemAnimation class, which was initially intended + for animating \l{QGraphicsItem}s may be deprecated or removed from + the animation framework. + + \omit (need something about the list of animations). \endomit + + \section1 Easing Curves + + As mentioned, QPropertyAnimation performs an interpolation between + the start and end property value. In addition to adding more key + values to the animation, you can also use an easing curve. Easing + curves describe a function that controls how the speed of the + interpolation between 0 and 1 should be, and are useful if you + want to control the speed of an animation without changing the + path of the interpolation. + + \code + QPushButton button("Animated Button"); + button.show(); + + QPropertyAnimation animation(&button, "geometry"); + animation.setDuration(3000); + animation.setStartValue(QRect(0, 0, 100, 30)); + animation.setEndValue(QRect(250, 250, 100, 30)); + + animation.setEasingCurve(QEasingCurve::OutBounce); + + animation.start(); + \endcode + + Here the animation will follow a curve that makes it bounce like a + ball as if it was dropped from the start to the end position. + QEasingCurve has a large collection of curves for you to choose + from. These are defined by the QEasingCurve::Type enum. If you are + in need of another curve, you can also implement one yourself, and + register it with QEasingCurve. + + \omit Drop this for the first Lab release + (Example of custom easing curve (without the actual impl of + the function I expect) + \endomit + + \section1 Putting Animations Together + + An application will often contain more than one animation. For + instance, you might want to move more than one graphics item + simultaneously or move them in sequence after each other. + + The subclasses of QAnimationGroup (QSequentialAnimationGroup and + QParallelAnimationGroup) are containers for other animations so + that these animations can be animated either in sequence or + parallel. The QAnimationGroup is an example of an animation that + does not animate properties, but it gets notified of time changes + periodically. This enables it to forward those time changes to its + contained animations, and thereby controlling when its animations + are played. + + Let's look at code examples that use both + QSequentialAnimationGroup and QParallelAnimationGroup, starting + off with the latter. + + \code + QPushButton *bonnie = new QPushButton("Bonnie"); + bonnie.show(); + + QPushButton *clyde = new QPushButton("Clyde"); + clyde.show(); + + QPropertyAnimation *anim1 = new QPropertyAnimation(bonnie, "geometry"); + // Set up anim1 + + QPropertyAnimation *anim2 = new QPropertyAnimation(clyde, "geometry"); + // Set up anim2 + + QParallelAnimationGroup *group = new QParallelAnimationGroup; + group->addAnimation(anim1); + group->addAnimation(anim2); + + group->start(); + \endcode + + A parallel group plays more than one animation at the same time. + Calling its \l{QAbstractAnimation::}{start()} function will start + all animations it governs. + + \code + QPushButton button("Animated Button"); + button.show(); + + QPropertyAnimation anim1(&button, "geometry"); + anim1.setDuration(3000); + anim1.setStartValue(QRect(0, 0, 100, 30)); + anim1.setEndValue(QRect(500, 500, 100, 30)); + + QPropertyAnimation anim2(&button, "geometry"); + anim2.setDuration(3000); + anim2.setStartValue(QRect(500, 500, 100, 30)); + anim2.setEndValue(QRect(1000, 500, 100, 30)); + + QSequentialAnimationGroup group; + + group.addAnimation(&anim1); + group.addAnimation(&anim2); + + group.start(); + \endcode + + As you no doubt have guessed, QSequentialAnimationGroup plays + its animations in sequence. It starts the next animation in + the list after the previous is finished. + + Since an animation group is an animation itself, you can add + it to another group. This way, you can build a tree structure + of animations which specifies when the animations are played + in relation to each other. + + \section1 Animations and States + + When using a \l{The State Machine Framework}{state machine}, we + have a special state, QAnimationState, that will play one or more + animations. + + The QState::addAnimatedTransition() convenience function lets you + associate an animation to a state transition. The function will + create the QAnimationState for you, and insert it into the state + machine. We also have the possibility to associate properties with + the states rather than setting the start and end values ourselves. + Below is a complete code example that animates the geometry of a + QPushButton. + + \code + QPushButton *button = new QPushButton("Animated Button"); + button->show(); + + QStateMachine *machine = new QStateMachine; + + QState *state1 = new QState(machine->rootState()); + state1->setPropertyOnEntry(button, "geometry", + QRect(0, 0, 100, 30)); + machine->setInitialState(state1); + + QState *state2 = new QState(machine->rootState()); + state2->setPropertyOnEntry(button, "geometry", + QRect(250, 250, 100, 30)); + + state1->addAnimatedTransition(button, SIGNAL(clicked()), state2, + new QPropertyAnimation(button, "geometry")); + state2->addAnimatedTransition(button, SIGNAL(clicked()), state1, + new QPropertyAnimation(button, "geometry")); + + machine->start(); + \endcode + + For a more comprehensive example of how to use the state machine + framework for animations, see the states example (it lives in the + \c{examples/animation/states} directory). +*/ + diff --git a/doc/src/declarative/anchor-layout.qdoc b/doc/src/declarative/anchor-layout.qdoc new file mode 100644 index 0000000..9647a72 --- /dev/null +++ b/doc/src/declarative/anchor-layout.qdoc @@ -0,0 +1,68 @@ +/*! +\page anchor-layout.html +\target anchor-layout +\title Anchor-based Layout + +In additional to the more traditional Fx layouts \l {xmlGridLayout}{GridLayout}, \l {xmlHorizontalLayout}{HorizontalLayout}, and \l {xmlVerticalLayout}{VerticalLayout}, QML also provides a way to layout items using the concept of anchors. Each visual Fx item can be thought of as having a set of 6 invisible "anchor lines": \e left, \e horizontalCenter, \e right, \e top, \e verticalCenter, and \e bottom. + +\image edges_qml.png + +The Fx anchoring system allows you to define relationships between the anchor lines of different items. For example, you can write: + +\code +<Rect id="rect1" .../> +<Rect id="rect2" anchors.left="{rect1.right}" .../> +\endcode + +In this case, the left edge of \e rect2 is bound to the right edge of rect1, producing the following: + +\image edge1.png + +The anchoring system also allows you to specify margins and offsets. Margins specify the amount of empty space to leave to the outside of an item, while offsets allow you to manipulate positioning using the center anchor lines. Note that margins specified using the anchor layout system only have meaning for anchors; they won't have any effect when using other layouts or absolute positioning. + +\image margins_qml.png + +The following example specifies a left margin: + +\code +<Rect id="rect1" .../> +<Rect id="rect2" anchors.left="{rect1.right}" anchors.leftMargin="5".../> +\endcode + +In this case, a margin of 5 pixels is reserved to the left of \e rect2, producing the following: + +\image edge2.png + +You can specify multiple anchors. For example: + +\code +<Rect id="rect1" .../> +<Rect id="rect2" anchors.left="{rect1.right}" anchors.top="{rect1.bottom}".../> +\endcode + +\image edge3.png + +By specifying multiple horizontal or vertical anchors you can control the size of an item. For example: + +\code +<Rect id="rect1" x="0" .../> +<Rect id="rect2" anchors.left="{rect1.right}" anchors.right="{rect3.left}".../> +<Rect id="rect3" x="150" .../> +\endcode + +\image edge4.png + +\section1 Limitations + +For performance reasons, you can only anchor an item to its siblings and direct parent. For example, the following anchor would be considered invalid and would produce a warning: + +\code +<Item id="group1"> + <Rect id="rect1" .../> +</Item> +<Item id="group2"> + <Rect id="rect2" anchors.left="{rect1.right}".../> <!-- invalid anchor! --> +</Item> +\endcode + +*/ diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc new file mode 100644 index 0000000..a1ab44b --- /dev/null +++ b/doc/src/declarative/animation.qdoc @@ -0,0 +1,130 @@ +/*! +\page animation.html +\target animation +\title QML Animation + +QML supports three different forms of animation - basic property animation, +states and transitions and property behaviors. + +\section1 Property Animation + +Animation in QML is done by animating properties of objects. + +Any property of a recognizable type can be animated. Currently those types include: +\list +\o qreal +\o int +\o Most of QVariant's built-in types +\endlist + +Animations can also involve numerous properties on numerous objects. + +Other Features: +\list +\o Support for a large set of parameterized easing curves. (based on the Penner easing equations) +\o Animation synchronization +\endlist + +The simplest form of animation is using \c <NumericAnimation/> + +The following example creates a bouncing effect: +\code +<Rect id="rect" width="120" height="200" color="white"> + <Image id="img" file="pics/qtlogo.png" + x="{60-img.width/2}" y="{200-img.height}"> + <y> + <SequentialAnimation running="true" repeat="true"> + <NumericAnimation to="{200-img.height}" + easing="easeOutBounce(amplitude:100)" + duration="2000" /> + <PauseAnimation duration="1000" /> + </SequentialAnimation> + </y> + </Image> +</Rect> +\endcode + +\image propanim.gif + +\target states-transitions +\section1 States and Transitions + +\section2 States + +QML states describe user interface configurations, including: +\list +\o What UI elements are present +\o The properties of those elements (including how they behave) +\o What actions are available +\endlist + +A state can also be thought of as a set of batched changes from a default configuration. + +Examples of states in modern UI: +\list +\o A Contacts application has a 'View Contact' state and an 'Edit Contact' State. In the first state the information presented is static (using labels), and in the second it is editable (using editors). +\o A button has a pressed and unpressed state. When pressed the text moves down and to the right, and the button has a slightly darker appearance. +\endlist + +In QML: +\list +\o Any object can use states. +\o There is a default state. The default state can be explicitly set. +\o A state can affect other the properties of other objects, not just the object owning the state (and not just that object's children). +\endlist + +The following example shows a simple use of states. In the default state \c myrect is positioned at 0,0. In the 'moved' state it is positioned at 50,50. + +\code +<Item> + <Rect id="myrect" width="100" height="100"/> + <states> + <State name="moved"> + <SetProperty target="{myrect}" property="x" value="50"/> + <SetProperty target="{myrect}" property="y" value="50"/> + </State> + </states> +</Item> +\endcode + +\section2 Transitions + +QML transitions describe animations to perform when state changes occur. + +For the previous example, a transition could describe how \c myrect moved from its initial position to its new position: + +\code +<transitions> + <Transition> + <NumericAnimation properties="x,y" easing="easeOutBounce" duration="200" /> + </Transition> +</transitions> +\endcode + +QML transitions can use selectors to determine which state changes a transition should apply to: + +\code +<Transition fromState="*" toState="Details"> +... +</Transition> +\endcode + +Transitions can happen in parallel, in sequence, or in any combination of the two:; + +\code +<Transition fromState="*" toState="MyState" reversible="true" > + <SequentialAnimation> + <ColorAnimation duration="1000" /> + <PauseAnimation duration="1000" /> + <ParallelAnimation> + <NumericAnimation duration="1000" easing="easeOutBounce" target="{box1}" properties="x,y" /> + <NumericAnimation duration="1000" target="{box2}" properties="x,y" /> + </ParallelAnimation> + </SequentialAnimation> +</Transition> +\endcode + +\section1 Property Behaviors + +\todo Document. Should we remove property behaviour altogether? +*/ diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc new file mode 100644 index 0000000..d6dae77 --- /dev/null +++ b/doc/src/declarative/basictypes.qdoc @@ -0,0 +1,387 @@ +/*! + \page basicxmltypes.html + \title Common QML Types + + QML uses a range of property types, which you will see + referenced throughout the element documentation. Almost all of them are + exactly what you would expect. + + \target basicxmlint + \raw HTML + <div class="memitem"> + <div class="memproto"> + <table class="memname"> + <tr><td>int</td></tr> + </table> + </div> + <div class="memdoc"> + \endraw + + ints are whole numbers - things like 0, 10 and -20. The possible int + values range from around -2000000000 to around 2000000000, although most + elements will only accept a reduced range (which they mention in their + documentation). + + int's must be specified using the plain old syntax you learned at school - + none of that scientific notation nonsense is supported. + + Setting ints looks like this: + \code + <Item width="100" height="200" /> + \endcode + + \raw HTML + </div> + </div> + \endraw + + \target basicxmlbool + \raw HTML + <br> + <div class="memitem"> + <div class="memproto"> + <table class="memname"> + <tr><td>bool</td></tr> + </table> + </div> + <div class="memdoc"> + \endraw + + bools are a binary true/false value, represented by the strings + "true" and "false" in XML. + + Setting bools looks like this: + \code + <Item focusable="true" clip="false" /> + \endcode + + \note Technically bool treats an empty string, "false" and "0" as false and + everything else as true. Seriously, though, use "true" and "false". + + \raw HTML + </div> + </div> + \endraw + + \target basicxmlreal + \raw HTML + <br> + <div class="memitem"> + <div class="memproto"> + <table class="memname"> + <tr><td>real</td></tr> + </table> + </div> + <div class="memdoc"> + \endraw + + reals are numbers - either whole numbers like ints, or fractional numbers + like 1.2 and -29.8. + + Setting reals looks like this: + \code + <Item x="-10" y="100.8" /> + \endcode + + \note In QML all reals are stored in single precision, \l {http://en.wikipedia.org/wiki/IEEE_754}{IEEE floating point} format. + + \raw HTML + </div> + </div> + \endraw + + \target basicxmlstring + \raw HTML + <br> + <div class="memitem"> + <div class="memproto"> + <table class="memname"> + <tr><td>string</td></tr> + </table> + </div> + <div class="memdoc"> + \endraw + + strings are free form text, like "hello world", "QML is cool" and + anything else you can think of. + + Setting a string looks like this: + \code + <Text text="Hello world!" /> + \endcode + + \raw HTML + </div> + </div> + \endraw + + \target basicxmlcolor + \raw HTML + <br> + <div class="memitem"> + <div class="memproto"> + <table class="memname"> + <tr><td>color</td></tr> + </table> + </div> + <div class="memdoc"> + \endraw + + Colors are most commonly specified as an \l {http://www.w3.org/TR/SVG/types.html#ColorKeywords}{SVG color name}. These names include colors like + "red", "green" and "lightsteelblue". + + If the color you want isn't part of this list, colors can also be specified + in hexidecimal triplets or quads that take the form \c "#RRGGBB" and + \c "#AARRGGBB" respectively. For example, the color red corresponds to a + triplet of \c "#FF0000" and a slightly transparent blue to a quad of + \c "#800000FF". + + Setting a color looks like this: + \code + <Rect color="steelblue" /> + <Rect color="#FF0000" /> + <Rect color="#800000FF" /> + \endcode + + \raw HTML + </div> + </div> + \endraw + + \target basicxmlpoint + \raw HTML + <br> + <div class="memitem"> + <div class="memproto"> + <table class="memname"> + <tr><td>point</td></tr> + </table> + </div> + <div class="memdoc"> + \endraw + + Points are specified in \c "x,y" format. + + Setting a point looks like this: + \code + <Widget pos="50,50"/> + \endcode + + \raw HTML + </div> + </div> + \endraw + + \target basicxmlsize + \raw HTML + <br> + <div class="memitem"> + <div class="memproto"> + <table class="memname"> + <tr><td>size</td></tr> + </table> + </div> + <div class="memdoc"> + \endraw + + Sizes are specified in \c "widthxheight" format. + + Setting a size looks like this: + \code + <Widget size="50x50"/> + \endcode + + \raw HTML + </div> + </div> + \endraw + + \target basicxmlrectangle + \raw HTML + <br> + <div class="memitem"> + <div class="memproto"> + <table class="memname"> + <tr><td>rectangle</td></tr> + </table> + </div> + <div class="memdoc"> + \endraw + + Rectangles are specified in \c "x,y,widthxheight" format. + + Setting a rectangle looks like this: + \code + <Widget geometry="50,50,100x100"/> + \endcode + + \raw HTML + </div> + </div> + \endraw + + \target basicxmldate + \raw HTML + <br> + <div class="memitem"> + <div class="memproto"> + <table class="memname"> + <tr><td>date</td></tr> + </table> + </div> + <div class="memdoc"> + \endraw + + Dates are specified in \c "YYYY-MM-DD" format. + + Setting a date looks like this: + \code + <DatePicker minDate="2000-01-01" maxDate="2020-12-31"/> + \endcode + + \raw HTML + </div> + </div> + \endraw + + \target basicxmltime + \raw HTML + <br> + <div class="memitem"> + <div class="memproto"> + <table class="memname"> + <tr><td>time</td></tr> + </table> + </div> + <div class="memdoc"> + \endraw + + Times are specified in \c "hh:mm:ss" format. + + Setting a time looks like this: + \code + <TimePicker time="14:22:15"/> + \endcode + + \raw HTML + </div> + </div> + \endraw + + \target basicxmlfont + \raw HTML + <br> + <div class="memitem"> + <div class="memproto"> + <table class="memname"> + <tr><td>font</td></tr> + </table> + </div> + <div class="memdoc"> + \endraw + + The font type has components: + \list + \o string font.family + \o bool font.bold + \o bool font.italic + \o real font.size + \endlist + + Setting a font looks like this: + \code + <Text font.family="Helvetica" font.size="13" font.bold="true"> + \endcode + + \raw HTML + </div> + </div> + \endraw + + \target basicxmlaction + \raw HTML + <br> + <div class="memitem"> + <div class="memproto"> + <table class="memname"> + <tr><td>action</td></tr> + </table> + </div> + <div class="memdoc"> + \endraw + + The action type has all the properties of QAction, in particular: + \list + \o slot action.trigger - invoke the action + \o bool action.enabled - true if the action is enabled + \o string action.text - the text associated with the action + \endlist + + Actions are used like this: + + \code + <MouseRegion onClick="{someitem.someaction.trigger()}"> + <State name="enabled" when="{someitem.someaction.enabled=='true'}"> + <Text text="{someitem.someaction.text}"> + \endcode + + \raw HTML + </div> + </div> + \endraw + + \target basicxmlany + \raw HTML + <br> + <div class="memitem"> + <div class="memproto"> + <table class="memname"> + <tr><td>any</td></tr> + </table> + </div> + <div class="memdoc"> + \endraw + + The any type can accept any basic type, object or list. Generally this + is only used in very special cases. The documentation for elements that + use the any type will explain the constraints in that particular case. + + \raw HTML + </div> + </div> + \endraw + + \target basicxmllist + \raw HTML + <br> + <div class="memitem"> + <div class="memproto"> + <table class="memname"> + <tr><td>Lists</td></tr> + </table> + </div> + <div class="memdoc"> + \endraw + + While not technically a basic type, QML also supports lists of object + types. When used from QML, the engine automatically appends each value to the + list. + + For example, the \l {xmlItem}{Item} class has a children list property + that can be used like this: + \code + <Item> + <children> + <Item id="child1" /> + <Rect id="child2" /> + <Text id="child3" /> + </children> + </Item> + \endcode + \c child1, \c child2 and \c child3 will all be added to the children list + in the order in which they appear. + \raw HTML + </div> + </div> + \endraw +*/ diff --git a/doc/src/declarative/binding.qdoc b/doc/src/declarative/binding.qdoc new file mode 100644 index 0000000..b711a08 --- /dev/null +++ b/doc/src/declarative/binding.qdoc @@ -0,0 +1,110 @@ +/*! +\page binding.html +\title Data Binding +\target binding + +Data binding provides a declarative way of specifying the data associated with objects, as well as the relationship between data of different objects. For example, you could bind the text of a label to the value of a slider: as the value of the slider changed, the label would be automatically updated with the new value. + +Bindings are indicated in Qml through the use of brackets: \c {}. For example, the following produces two Rects of equal size (\c rect2 is bound to the size of \c rect1): +\code +<Rect id="rect1" width="100" height="100"> +<Rect id="rect2" width="{rect1.width}" height="{rect1.height}"> +\endcode + +There is also a special \c <Bind> element, which is typically used to bind from the UI to the underlying UI model (see \l {Passing Data Between C++ and Qml} for an example of this). The bindings above could be expressed using the \c <Bind> element as: + +\code +<Bind target="{rect2}" property="width" value="{rect1.width}"/> +<Bind target="{rect2}" property="height" value="{rect1.height}"/> +\endcode + +In addition to binding directly to a property, you can also bind to the results of expressions involving properties. For example: +\code +<Text text="{contact.firstname + ' ' + contact.lastname}"> +<Image file="{if (contact.gender == 'female') {'pics/female.png'} else {'pics/male.png'}}"> +\endcode + +Relevant items can also be bound to the contents of a model - see \l ListView for an example of this. + +Data can be bound to C++ objects - see \l {C++ Data Binding}. +*/ + +/*! +\page qtbinding.html +\target qtbinding +\title C++ Data Binding + +The QML mechanisms of \l {Data Binding} can also be used to bind Qt C++ objects. + +The data binding framework is based on Qt's property system (see the Qt documentation for more details on this system). If a binding is meant to be dynamic (where changes in one object are reflected in another object), \c NOTIFY must be specified for the property being tracked. If \c NOTIFY is not specified, any binding to that property will be an 'intialization' binding (the tracking object will be updated only once with the initial value of the tracked object). + +Relevant items can also be bound to the contents of a Qt model. For example, ListView can make use of data from a QListModelInterface-derived model. (QListModelInterface is part of the next generation Model/View architecture being developed for Qt.) + + +\section1 Passing Data Between C++ and Qml + +Data binding provides one method of data transfer between C++ and Qml. + +For example, lets say you want to implement a slider in Qml that changes the screen brightness of the device it is running on. You would start by declaring a brightness property on your QObject-derived class: +\code +class MyScreen : public QObject +{ + Q_OBJECT +public: + MyScreen(QObject *parent=0); + + Q_PROPERTY(int brightness READ brightness WRITE setBrightness NOTIFY brightnessChanged); + int brightness() const; + void setBrightness(int b); + ... + +signals: + void brightnessChanged(); + +private: + int m_brightness; +}; + +int brightness() const +{ + return m_brightness; +} + +void setBrightness(int b) +{ + if (b != m_brightness) { + m_brightness = b; + emit brightnessChanged(); + + //set device brightness + ... + } +} +\endcode + +\note One important thing to keep in mind is that the changed signal should only be emitted when there is a real change ( \c b \c != \c m_brightness ), or you may get an infinite loop. + +Next, make an instance of this class visible to the Qml bind engine: +\code +QFxView *view = new QFxView; +view->setXml("MyUI.qml"); + +MyScreen *screen = new MyScreen; +QmlBindContext *ctxt = view->bindContext(); +ctxt->setProperty("screen", screen); + +view->execute(); +\endcode + +\note Bindings must be made after setXml() but before execute(). + +Finally, in Qml you can make the appropriate bindings, so in \c "MyUI.qml": + +\code +<Slider value="{screen.brightness}"/> +<Bind target="{screen}" property="brightness" value="{slider.value}" /> +\endcode + +The \l QBindableMap class provides a convenient way to make data visible to the bind engine. + +*/ diff --git a/doc/src/declarative/components.qdoc b/doc/src/declarative/components.qdoc new file mode 100644 index 0000000..b5c5ae7 --- /dev/null +++ b/doc/src/declarative/components.qdoc @@ -0,0 +1,74 @@ +/*! +\page components.html +\target components +\title Components + +A \b component is a reusable, encapsulated Qml element with a well-defined interface. + +Writing and using components allows you to: +\list +\o Reuse sections of Qml without copy-and-paste. +\o Have consistent Look and Feel between different parts of your UI. +\o Create new Qml elements without writing a new C++ class. (See \l {cppitem}{Creating Qml elements in C++}) +\endlist + +Components are placed in \e <Name>.qml files, allowing \e <Name> to then be used as a tag elsewhere. For example, if you have a Slider.qml file, you can then use \c <Slider> to place a slider. + +Components may be collected into \l {qmlmodules}{modules}. + +\section1 Example: Creating a MyButton Component + +This example describes how to create a component from an existing snippet of Qml. + +Assume you have an existing UI with a single 'Save' button, defined as follows: + +\code +<Image file="pics/button-background.png"> + <Text text="Save" anchors.horizontalCenter="{parent.horizontalCenter}" anchors.verticalCenter="{parent.verticalCenter}"/> + <MouseRegion anchors.fill="{parent}" onClick="saveData()"/> +</Image> +\endcode + +For the next release, you plan to add 'Cancel' and 'Reset' buttons. Rather than copying and pasting the above markup, you can create a component: + +\list 1 +\o Create a file called MyButton.qml, and copy the relevant Qml snippet into that file. +\o Make some minor changes to define the component's interface: + +\code +<Image file="pics/button-background.png"> + <properties><Property name="label"/></properties> + <signals><Signal name="click"/></signals> + <Text text="{parent.label}" anchors.horizontalCenter="{parent.horizontalCenter}" anchors.verticalCenter="{parent.verticalCenter}"/> + <MouseRegion anchors.fill="{parent}" onClick="parent.click.emit()"/> +</Image> +\endcode + +The \a label property and \a click signal that were added effectively become part of the 'public API' of the MyButton component. In a similar manner, the Text and MouseRegion elements become invisible to anyone using the component. Note that the Text element now binds in its data from \a label, and the MouseRegion emits a generic signal. + +\o The component can now be used elsewhere as MyButton: + +\code +<MyButton label="Save" onClick="saveData()"/> +... +<MyButton label="Cancel" onClick="cancelData()"/> +... +<MyButton label="Reset" onClick="resetData()"/> +\endcode + +\endlist + +\section1 Placing .qml Files + +Component files should be placed in specific locations in order to be found by the Qml engine: + +\list +\o the run directory +\o the run directory + "/qml" +\o the directory of the Qml you are running +\o the directory of the Qml you are running + "/qml" +\endlist + +In the future library-like directories will be defined (in the meantime the first two options above effectively serve this purpose). + +*/ diff --git a/doc/src/declarative/cppitem.qdoc b/doc/src/declarative/cppitem.qdoc new file mode 100644 index 0000000..959bc6d --- /dev/null +++ b/doc/src/declarative/cppitem.qdoc @@ -0,0 +1,127 @@ +/*! +\page cppitem.html +\target cppitem +\title C++ Components + +\section1 Making a C++ object available in QML + +In QML, XML tags and attributes correspond to Qt objects and properties. Thus, any Qt object +can potentially be used as an element in QML. More specifically, to make an object available in QML, +it should: +\list +\o Be a subclass of QObject. +\o Provide a default constructor. +\o Declare Q_PROPERTYs. +\o Be registered via the QML_DECLARE_TYPE and QML_DEFINE_TYPE macros. +\endlist + +\section2 Declaring Q_PROPERTYs +\target properties + +Properties of QObject subclasses are available as properties in QML. +Like any QObject, these properties are defined by the Q_PROPERTY +macro in the header file. + +Properties should have a NOTIFY function if they can change dynamically and +if any useful response could be made to them changing in another object. Almost +all properties will thus need a NOTIFY function. + +\code + Q_PROPERTY(qreal scale READ scale WRITE setScale NOTIFY scaleChanged); + qreal scale() const; + void setScale(qreal); + ... + signals: void scaleChanged(); +\endcode + +The property types currently supported by QML are: +\list +\o int +\o qreal +\o QString +\o QColor +\o QDate, QTime, and QDateTime +\o QSize and QSizeF +\o QPoint and QPointF +\o QRect and QRectF +\o QPixmap +\o QIcon +\o enums registered with Q_ENUMS +\o flags registered with Q_FLAGS +\o QVariant +\o QObject* (or subclass) +\endlist + +Custom property types that provide string-to-type conversion can be used as well, by: +\list +\o Registering them as a metatype (Q_DECLARE_METATYPE() and qRegisterMetaType()) +\o Registering a string-to-type convertor function (QML::addCustomStringConvertor()). +\endlist + +\section2 Registering your type +\target register + +In order for your type to be usable in QML, you must register it: + +\code +QML_DECLARE_TYPE(TypeName); +QML_DEFINE_TYPE(TypeName,QmlName); +\endcode + +These macros make the C++ \e TypeName available from the declarative markup language under the name \e QmlName. +Of course there's nothing stopping you using the same name for both the C++ and the QML name! + +For example: +\code +QML_DECLARE_TYPE(MyCircle); +QML_DEFINE_TYPE(MyCircle,Circle); +\endcode +would make the \e MyCircle class accessable though the \c <Circle/> tag in QML. + + +\section1 Creating a new 'Fx' item in C++ + +You can create a new type of 'Fx' item by: +\list 1 +\o Creating a subclass of QFxItem, +\o Adding Q_PROPERTYs appropriate for your item (see \l {properties}{Properties}), +\o Reimplementing the relevant paint functions, +\o Registering the type with the QML_DECLARE_TYPE and QML_DEFINE_TYPE macros (see \l {register}{Register}). +\endlist + +\section2 Creating a subclass of QFxItem + +To add a new type, you first must add a new C++ class derived from QFxItem. +You may of course extend existing QFxItem subclasses. + +One existing subclass is QFxPainted, which provides +a simple cached-image painting model. + +\section2 Reimplementing paint functions + +Two alternative painters are available, offering +different levels of performance and functionality: +QPainter, GLPainter. + +You can choose to subclass QFxPainted rather than QFxItem, +and then implement the virtual method: + +\code + void paint(QPainter *painter); +\endcode + +This paints into an offscreen pixmap which is then painted to the display (transformed, +etc. as needed). The cost of this offscreen pixmap should be carefully considered, as +should the specific performance of the painting done in the paint function. + +If you require more control, subclass QFxItem instead. +QFxItem subclasses must implement both simple software canvas painting +and GL painting: +\list +\o \c QFxItem::paintContents(QPainter &) for the simple software canvas, +\o \c QFxItem::paintGLContents(GLPainter &) for OpenGL. +\endlist + +See the documentation of those functions for detailed subclassing notes. + +*/ diff --git a/doc/src/declarative/effects.qdoc b/doc/src/declarative/effects.qdoc new file mode 100644 index 0000000..c7cd2f6 --- /dev/null +++ b/doc/src/declarative/effects.qdoc @@ -0,0 +1,31 @@ +/*! +\page effects.html +\target effects +\title Visual Effects + + +\section1 Basic Effects + +These effects are currently supported by all canvas backends. + +\list +\o Scaling (\l Item \bold scale property) +\o Opacity (\l Item \bold opacity property) +\o Z-Axis Rotation (\l Item \bold rotation property) +\endlist + +\section1 Advanced Effects + +These effects are currently only supported by the OpenGL canvas backend. Support for other +backends may be added if the performance can be made acceptable. + +\list +\o X/Y-Axis Rotation (see \l Transform) +\o \l Shadow +\o \l Blur +\o \l Reflection +\o \l Highlights +\o \l Particles +\endlist + +*/ diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc new file mode 100644 index 0000000..076ef13 --- /dev/null +++ b/doc/src/declarative/elements.qdoc @@ -0,0 +1,128 @@ +/*! +\page elements.html +\target elements +\title Qml Elements + +The following table lists the Qml elements provided by the Qt Declarative module. + +\bold {Standard Qt Declarative Elements} + +\table +\header +\o \bold {States} +\o \bold {Animation and Transitions} +\o \bold {Utility} +\row + +\o +\list +\o \l StateGroup +\o \l SetProperty +\o \l SetProperties +\o \l ParentChange +\o \l RunScript +\endlist + +\o +\list +\o \l NumericAnimation +\o \l ColorAnimation +\o \l VariantAnimation +\o \l PauseAnimation +\o \l SequentialAnimation +\o \l ParallelAnimation +\o \l SetPropertyAction +\o \l Transition +\o \l Behaviour +\o \l Follow +\endlist + +\o +\list +\o \l Script +\o \l Bind +\o \l Connection +\o \l ListModel +\o \l DateTimeFormatter +\endlist +\endtable + +\bold {Fluid UI Primitives} + +\table +\header +\o \bold {Basic Items} +\o \bold {Utility} +\o \bold {Widgets} + +\row +\o +\list +\o \l Item +\o \l Image +\o \l Text +\o \l TextEdit +\o \l Rect +\o \l MouseRegion +\o \l KeyActions +\o \l AnimatedImage +\endlist + +\o +\list +\o \l Repeater +\o \l Content +\o \l FocusPanel +\o \l FocusRealm +\o \l KeyProxy +\o \l ComponentInstance +\endlist + +\o +\list +\o \l Flickable +\o \l Flipable +\o \l WebView +\endlist + +\header +\o \bold {Views} +\o \bold {Layouts} +\o \bold {Effects} + +\row +\o + +\target xmlViews +\list +\o \l ListView +\o \l GridView +\o \l PathView + \list + \o \l Path + \endlist +\endlist + +\o +\list +\o \l VerticalLayout +\o \l HorizontalLayout +\o \l GridLayout +\endlist + +\o +\list +\o \l Shadow +\o \l Reflection +\o \l Blur +\o \l Highlight +\o \l Particles + \list + \o \l ParticleMotionLinear + \o \l ParticleMotionGravity + \o \l ParticleMotionWander + \endlist +\endlist +\endtable + +*/ diff --git a/doc/src/declarative/examples.qdoc b/doc/src/declarative/examples.qdoc new file mode 100644 index 0000000..17fda4d --- /dev/null +++ b/doc/src/declarative/examples.qdoc @@ -0,0 +1,32 @@ +/*! +\page qmlexamples.html +\target qmlexamples +\title QML Examples + +A viewer application is included that allows you to quickly explore many of the +examples. It has some useful options, revealed by: + +\code + bin/duiviewer -help +\endcode + +There are several illustrative XML examples available. From your build +directory, + +\code + bin/duiviewer $QT_SOURCE_DIR/examples/declarative/mediabrowser/mediabrowser.qml +\endcode + +Many other simple demos can be found under the \c examples/declarative sub +directory. Some can be run directly using the viewer like those above, and +others require you to build and run an executable. + +Finally, check out the \l {tutorial} to learn a little more about writing your +own QML-based applications. + +\note When running applications that only use the Fluid UI atoms under the +software rasterizer, a simple canvas backend is used by default. To use +Graphics View instead, set \c QML_USE_GRAPHICSVIEW=1. + + +*/ diff --git a/doc/src/declarative/focus.qdoc b/doc/src/declarative/focus.qdoc new file mode 100644 index 0000000..e0d4ca3 --- /dev/null +++ b/doc/src/declarative/focus.qdoc @@ -0,0 +1,248 @@ +/*! +\target qmlfocus +\page qmlfocus.html +\title Fluid UI Keyboard Focus + +When a key is pressed or released, a key event is generated and delivered to the +focused fluid UI \l Item. To facilitate the construction of reusable components +and to address some of the cases unique to fluid UIs, the fluid UI atoms add a +"realm" based extension to Qt's traditional keyboard focus model. + +\section1 Key Handling Overview + +When the user presses or releases a key, the following occurs: +\list 1 +\o Qt receives the key action and generates a key event. +\o If the Qt widget containing the fluid UI scene has focus, the key event is delivered to the fluid UI scene. Otherwise, regular Qt key handling continues. +\o The key event is delivered by the scene to the fluid UI \l Item with \e {active focus}. If no fluid UI \l Item has \e {active focus}, the key event is \l {QEvent::ignore()}{ignored} and regular Qt key handling continues. +\o If the fluid UI \l Item with \e {active focus} accepts the key event, propagation stops. Otherwise the event is "bubbled up", by recursively passing it to each \l Item's parent until either the event is accepted, or the root \l Item is reached. + +If the \c {<Rect/>} element in the following example has active focus and the \e A key is pressed, it will bubble up to the \c {<KeyActions/>}. However, pressing the \e B key will bubble up to the root item and thus subsequently be \l {QEvent::ignore()}{ignored}. + +\code +<Item> + <KeyActions keyA="print('Key A was pressed')"> + <Rect /> + </KeyActions> +</Item> +\endcode + +\o If the root \l Item is reached, the key event is \l {QEvent::ignore()}{ignored} and regular Qt key handling continues. + +\endlist + +\section1 Querying the Active Focus Item + +Whether or not an \l Item has \e {active focus} can be queried through the +read-only property \c {Item::activeFocus}. For example, here we have a \l Text +element whose text is determined by whether or not it has \e {active focus}. + +\code +<Text> + <text>{activeFocus?"I have active focus!":"I do not have active focus"}</text> +</Text> +\endcode + +\section1 Acquiring Focus and Focus Realms + +An \l Item requests focus by setting the \c {Item::focus} property to true. + +For very simple cases simply setting the \c {Item::focus} property is sometimes +sufficient. If we run the following example in the \c duiviewer, we see that +the \c {<KeyActions/>} element has \e {active focus} and pressing the +\e A, \e B, or \e C keys modifies the text appropriately. + +\table +\row +\o \code + <Rect color="lightsteelblue" width="240" height="25"> + <Text id="MyText" /> + <KeyActions focus="true"> + <keyA>MyText.text = "Key A was pressed"</keyA> + <keyB>MyText.text = "Key B was pressed"</keyB> + <keyC>MyText.text = "Key C was pressed"</keyC> + </KeyActions> + </Rect> +\endcode +\o \image declarative-qmlfocus1.png +\endtable + +However, were the above example to be used as a self-contained component, this +simple use of the \c {Item::focus} property is no longer sufficient. The left +hand side of the following table shows what we would like to be able to write. +Here we create two instances of our previously defined component, and set the +second one to have focus. The intention is that when the \e A, \e B, or \e C +keys are pressed, the second of the two components receives the event and +reponds accordingly. + +\table +\row +\o \code +<Rect color="red" width="240" height="55"> + <MyWidget /> + <MyWidget y="30" focus="true"/> +</Rect> +\endcode +\o \code +<Rect color="red" width="240" height="55"> + <Rect color="lightsteelblue" width="240" height="25"> + <Text id="MyText" /> + <KeyActions focus="true"> + <keyA>MyText.text = "Key A was pressed"</keyA> + <keyB>MyText.text = "Key B was pressed"</keyB> + <keyC>MyText.text = "Key C was pressed"</keyC> + </KeyActions> + </Rect> + <Rect y="30" focus="true" color="lightsteelblue" width="240" height="25"> + <Text id="MyText" /> + <KeyActions focus="true"> + <keyA>MyText.text = "Key A was pressed"</keyA> + <keyB>MyText.text = "Key B was pressed"</keyB> + <keyC>MyText.text = "Key C was pressed"</keyC> + </KeyActions> + </Rect> +\endcode +\endtable + +The right hand side of the example shows the expanded code - the equivalent QML +without the use of the component \c {<MyWidget/>}. From this, the problem is +evident - there are no less than three elements that have the \c {Item::focus} +property set to true. Ultimately only one element can have focus, and the +system has to decide which on. In this case the first appearance of the +\c {Item::focus} property being set to true on line 4 is selected, and the value +of \c {Item::focus} in the other two instances is reverted back to false. This +is exactly the opposite of what was wanted! + +This problem is fundamentally one of visibility. The \c {<MyWidget/>} +components each set their \c {<KeyActions/>} as focused as that is all they can +do - they don't know how they are going to be used, but they do know that when +they're in use their \c {<KeyActions/>} element is what needs focus. Likewise +the code that uses the \c {<MyWidget/>}'s sets the second \c {<MyWidget/>} as +focused because, while it doesn't know exactly how the \c {<MyWidget/>} is +implemented, it knows that it wants the second one to be focused. No one piece +of code knows everything about the other, which is exactly how it should be. + +To solve this problem - allowing components to care about what they know about +and ignore everything else - the fluid UI atoms introduce a concept known as a +\e {focus realm}. For existing Qt users, a \e {focus realm} is like an +automatic focus proxy. A \e {focus realm} is created using the \l FocusRealm +element. + +In the next example, a \l FocusRealm is added to the component, and the visual +result shown. + +\table +\row +\o \code +<FocusRealm width="240" height="25"> + <Rect color="lightsteelblue" width="240" height="25"> + <Text id="MyText" /> + <KeyActions focus="true"> + <keyA>MyText.text = "Key A was pressed"</keyA> + <keyB>MyText.text = "Key B was pressed"</keyB> + <keyC>MyText.text = "Key C was pressed"</keyC> + </KeyActions> + </Rect> +</FocusRealm> +\endcode +\o \image declarative-qmlfocus2.png +\endtable + +Conceptually \e {focus realms} are quite simple. +\list +\o Within each \e {focus realm} one element may have \c {Item::focus} set to true. If more than one \l Item has the \c {Item::focus} property set, the first is selected and the others are unset, just like when there are no \e {focus realms}. +\o When a \e {focus realm} receives \e {active focus}, the contained element with \c {Item::focus} set (if any) also gets \e {active focus}. If this element is +also a \l FocusRealm, the proxying behaviour continues. Both the +\e {focus realm} and the sub-focused item will have \c {Item::activeFocus} set. +\endlist + +So far the example has the second component statically selected. It is trivial +now to extend this component to make it clickable, and add it to the original +application. We still set a one of the widgets as focused by default, but from +then on clicking the either one gives it focus. + +\table +\row +\o \code +<Rect color="red" width="240" height="55"> + <MyClickableWidget /> + <MyClickableWidget y="30" focus="true"/> +</Rect> +\endcode +\o \code +<FocusRealm id="Page" width="240" height="25"> + <MyWidget focus="true" /> + <MouseRegion anchors.fill="{parent}" onClick="Page.focus = true" /> +</FocusRealm> +\endcode +\endtable + +\image declarative-qmlfocus3.png + +When a fluid UI atom explicitly relinquishes focus (by setting its +\c {Item::focus} property to false while it has \e {active focus}), the system +does not automatically select another element to receive focus. That is, it +is possible for there to be no currently \e {active focus}. + +\section1 Advanced uses of Focus Realms + +Focus realms allow focus to allocation to be easily partitioned. Several +fluid UI atoms use it to this effect. + +\l ListView, for example, is itself a focus realm. Generally this isn't +noticable as \l ListView doesn't usually have manually added visual children. +By being a focus realm, \l ListView can focus the current list item without +worrying about how that will effect the rest of the application. This allows +the current item delegate to react to key presses. + +This contrived example shows how this works. Pressing the \c Return key will +print the name of the current list item. + +\table +\row +\o \code +<Rect color="lightsteelblue" width="240" height="320"> + + <ListView id="MyView" anchors.fill="{parent}" focus="true"> + <model> + <ListModel> + <Row><name>Bob</name></Row> + <Row><name>John</name></Row> + <Row><name>Michael</name></Row> + </ListModel> + </model> + <delegate> + <FocusRealm width="{contents.width}" height="{contents.height}"> + <Text text="{name}" /> + <KeyActions return="print(name)" focus="true" /> + </FocusRealm> + </delegate> + </ListView> + +</Rect> +\endcode +\o \image declarative-qmlfocus4.png +\endtable + +While the example is simple, there's a lot going on behind the scenes. Whenever +the current item changes, the \l ListView sets the delegate's \c {Item::focus} +property. As the \l ListView is a \e {focus realm}, this doesn't effect the +rest of the application. However, if the \l ListView itself has +\e {active focus} this causes the delegate itself to receive \e {active focus}. +In this example, the root element of the delegate is also a \e {focus realm}, +which in turn gives \e {active focus} to the \c {<KeyActions/>} element that +actually performs the work of handling the \e {Return} key. + +All of the fluid UI view classes, such as \l PathView and \l GridView, behave +in a similar mannor to allow key handling in their respective delegates. + +\section1 Focus Panels + +Traditional UIs are composed of many top-level windows. Windows actually +perform two tasks - they act as the visual bounds for a widget, and they segment +focus. Each window has a separate focused widget, that becomes (to mix +terminologies) the \e {active focus} widget when the window is the active +window. + +### Focus panels do basically the same thing. +*/ diff --git a/doc/src/declarative/index.qdoc b/doc/src/declarative/index.qdoc new file mode 100644 index 0000000..22195ba --- /dev/null +++ b/doc/src/declarative/index.qdoc @@ -0,0 +1,51 @@ +/*! +\page qml.html +\title 'Qt Declarative' Documentation + +\target qtdeclarativemainpage + +The Qt Declarative module provides a user interface framework for building +highly dynamic and fluid applications. It is targetted at the sorts of user +interface and the sorts of hardware in embedded devices such as phones, media +players, and set-top boxes. It is also appropriate for highly custom desktop +user-interfaces, or special elements in more traditional desktop +user-interfaces. + +Building fluid applications is done declaratively, rather than procedurally. +That is, you specify \e what the UI should look like and how it should behave +in an XML-based format called QML instead of specifying step-by-step \e how to +build it in a language like C++ or JavaScript. Specifying a UI declaratively +does not just include the layout of the interface items, but also the way each +individual item looks and behaves and the overall flow of the application. + +Getting Started: +\list +\o \l {qmlexamples}{Examples} +\o \l {tutorial}{Tutorial} +\o \l {qmlforcpp}{Qt Declarative Markup Language For C++ Programmers} +\endlist + +Core Features: +\list +\o \l {binding}{Data Binding} +\o \l {anchor-layout}{Layout Anchors} +\o \l {animation}{Animation} +\o \l {effects}{Visual Effects} +\o \l {components}{Components} +\o \l {qmlmodules}{Modules} +\o \l {qmlfocus}{Keyboard Focus} +\endlist + +QML Reference: +\list +\o \l {elements}{Qml Elements} +\endlist + +C++ Reference: +\list +\o \l {qtprogrammers}{QML for Qt programmers} +\o \l {qtbinding}{C++ Data Binding} +\o \l {cppitem}{C++ Components} +\endlist + +*/ diff --git a/doc/src/declarative/measuring-performance.qdoc b/doc/src/declarative/measuring-performance.qdoc new file mode 100644 index 0000000..2387335 --- /dev/null +++ b/doc/src/declarative/measuring-performance.qdoc @@ -0,0 +1,81 @@ +/*! +\page optimizing-performance.html +\target optimizing-performance +\title Optimizing Performance + +The Qt Declarative module includes several tools to help measure performance. + +\section1 Performance Logging + +The declarative module uses the functionality provided by QPerformanceLog to log performance information. To see this information you can add the following to src.pro: + +\code +DEFINES += Q_ENABLE_PERFORMANCE_LOG +\endcode + +The performance information will be printed to screen on a QML application startup, or when running the viewer can be forced at anytime by pressing 'F3' on the keyboard. + +Additional logging can be enabled by adding the relevant categories to qfxperf.h and qfxperf.cpp. + +For example, to measure the cost of calculating the size of a text item, you would first define a TextSize category by adding the following: + +\code +//in qfxperf.h +Q_DECLARE_PERFORMANCE_METRIC(TextSize); + +//in qfxperf.cpp +Q_DEFINE_PERFORMANCE_METRIC(TextSize, "Text Size Calculation"); +\endcode + +You could then use this category in the code: + +\code +void QFxText::updateSize() +{ + QFxPerfTimer<QFxPerf::TextSize> perf; + ... +} +\endcode + +Because there is no cost for a QFxPerfTimer when Q_ENABLE_PERFORMANCE_LOG is not defined, this line can persist in the code and be used to help detect performance bottlenecks and regressions. See the QPerformanceLog documentation for more information on this performance framework. + +\section1 FPS Measurements + +When running the viewer, pressing 'F2' on the keyboard while a QML program is running will cause information on cost-per-frame and frames-per-second (FPS) to be printed to the console. + +The information printed includes: +\list +\o \e repaint(): the total time spent painting. +\o \e paint(): the time spent by Qt painting. +\o \e timeBetweenFrames: the total time spent per frame. This number minus repaint() gives a good idea of how much time is spent on things besides painting. A high number here with a low number for repaint() indicates expensive calculations happening each frame. +\endlist + +\section1 Improving Performance + +The following tips can help decrease startup time for QML-based appications. + +\section2 Images + +\list +\o Use jpg instead of png for photo-like images. On the N810, this can save 150ms for a large (320x480) image. + +\o If you are configuring Qt, configure out any image plugins you don't plan to support (mng and svg are the most expensive). On the N810, this can save 75-100ms startup time. For example: + +\code +configure -no-libmng -no-svg -no-libtiff +\endcode + +\o In some cases running pngcrush, optipng, gifsicle or other similar tools can give some improvement. + +We are also investigating support for the loading of uncompressed images. This will provide opportunites to decrease startup time at the cost of increased storage space. +\endlist + +\section2 Fonts + +\list +\o Use qpf instead of ttf. When using multiple font sizes and weights on the N810, this can save 125ms startup time compared to a ttf 'clean' run, and 40-50ms on subsequent runs (ttfs are shared by open applications). +\endlist + +*/ + +*/ diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc new file mode 100644 index 0000000..a97b5d7 --- /dev/null +++ b/doc/src/declarative/modules.qdoc @@ -0,0 +1,135 @@ +/*! +\page qmlmodules.html +\target qmlmodules +\title Modules of Components + +A \bold module is a collection of \l Components, in an XML namespace. + +Named component in QML may include a namespace qualification, +and standard XML namespace scoping is allowed. This allows +components to be provided by different modules (even if they otherwise +have the same name). + +To use a module: + +\code +<Item xmlns:Clock="http://nokia.com/qml/Clock"> + <Clock:AnalogClock> + ... + </Clock:AnalogClock> +</Item> +\endcode + +To create a modules: + +Create the components, with appropriate exported properties, signals, and slots (slots not currently supported), +in a single directory: + +\c Clock/Face.qml: ... + +\c Clock/Hand.qml: ... + +\c Clock/AnalogClock.qml: +\code +<Item xmlns:Clock="http://nokia.com/qml/Clock"> + <Clock:Face .../> + <Clock:Hand .../> + <Clock:Hand .../> + <Clock:Hand .../> + ... +</Item> +\endcode + +Associate the directory with the namespace: + +\code + Qml::addNameSpacePath("http://nokia.com/qml/Clock", "/usr/lib/qml/Clock"); +\endcode + +Whole blocks of directories can be set: + +\code + Qml::addNameSpacePath("http://nokia.com/qml", "/usr/lib/qml"); +\endcode + +Associations can also be declared in the QML itself as a processing directive: + +\code + <?qtfx namespacepath:http://nokia.com/qml=/usr/lib/qml ?> +\endcode + +*/ + +/* + +A kludgey way to do unexported components: + +Clock/AnalogClock.qml: +<Item> + <properties> + <Property name="time" ... /> + </properties> + + <Component name="Hand"> ... </Component> <!-- invisible compoent --> + + <ComponentInstance component="Hand" size="100"/> + <ComponentInstance component="Hand" size="200"/> + <ComponentInstance component="Hand" size="300"/> +</Item> + +Another kludgey way (if _ handled specially)): + +Clock/_Hand.qml: ... + +A non-XML extension to improve syntax (XMLNS blows): + +<qml> + <using ns="http://nokia.com/qml/Clock"/> + <Face .../> + ... +</qml> + +*/ + +/* + IMPLEMENTATION + + Fully Qualifying names. CHOICE + IF QmlXmlParser qualifies names: + QmlXmlParser processes <qml> and <using> tags to create a list of QmlModuleDependency. + It uses talks with the same creators as QmlCompiler::compileTypes to qualify the names. + Each of QmlMetaType, QmlCustomParser, and the QmlCompiledComponent::classFactory(ies) + must know fully-qualified names. + Pro: simpler + Con: may be harder to regenerate original XML if unqualified name is lost + Con: should QmlXmlParser "know" about the type creators? + ELSE + QmlXmlParser processes <qml> and <using> tags to create a list of QmlModuleDependency, + which get stored in the QCompiledComponent. + When QmlCompiler::compileTypes creates components, module dependencies are used + to find the correct component - turning a name into a fully-qualified name + at "ref.className = type" before passing it to the creators. QmlMetaType::typeFunc must allow + qualified names even for builtin types, for example, QFxText might be + declared with the name Qt:Text. The QML::customParser must also understand + the concept, for example ListModel might be declared with the name Qt:ListModel. + QmlXmlParser::Object::typeName should be removed (used by DOM?), as redundant. + QmlXmlParser::Object::type will not define a fully qualified typename, just a name, + so types that are actually the same may have different type id because they + were named differently ("Qt:Text" vs "Text"). Need to check if this is a problem, + or whether QmlCompiler::output->types should be compressed. + + XML Namespaces. CHOICE CHOSEN + The advantage is that the namespaces could be fixed (per version), allowing proper DTDs, etc. + + Attached properties. PROBLEM + Type references in JavaScript can be either unqualified, in which case QmlMetaProperty + would have to FQ the type, which seems impossible, or qualified, the syntax + of which would be odd, like Qt.GridLayout.row or property["Qt:GridLayout.row"]. + + Access restrictions. PROBLEM + All use of the bind context must prevent direct access between objects that + are in different modules (i.e. between types with different module prefixes). + Maybe this is accomplishable just from having the right context tree. + Components in the same module can refer to their containing components (they + need to be careful if they're allowed to be used outside). +*/ diff --git a/doc/src/declarative/pics/ListViewHighlight.png b/doc/src/declarative/pics/ListViewHighlight.png Binary files differnew file mode 100644 index 0000000..02bf51d --- /dev/null +++ b/doc/src/declarative/pics/ListViewHighlight.png diff --git a/doc/src/declarative/pics/ListViewHorizontal.png b/doc/src/declarative/pics/ListViewHorizontal.png Binary files differnew file mode 100644 index 0000000..63c7c86 --- /dev/null +++ b/doc/src/declarative/pics/ListViewHorizontal.png diff --git a/doc/src/declarative/pics/ListViewVertical.png b/doc/src/declarative/pics/ListViewVertical.png Binary files differnew file mode 100644 index 0000000..e0b23d9 --- /dev/null +++ b/doc/src/declarative/pics/ListViewVertical.png diff --git a/doc/src/declarative/pics/anchors.svg b/doc/src/declarative/pics/anchors.svg new file mode 100644 index 0000000..08b00ed --- /dev/null +++ b/doc/src/declarative/pics/anchors.svg @@ -0,0 +1,92 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://web.resource.org/cc/" + 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" + width="744.09448819" + height="1052.3622047" + id="svg1910" + sodipodi:version="0.32" + inkscape:version="0.44.1" + inkscape:export-filename="/home/mbrasser/work/Kinetic/ngui/doc/src/pics/anchors_example2.png" + inkscape:export-xdpi="189.65207" + inkscape:export-ydpi="189.65207" + sodipodi:docbase="/home/mbrasser/work/Kinetic/ngui/doc/src/pics" + sodipodi:docname="anchors.svg"> + <defs + id="defs1912" /> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.979899" + inkscape:cx="431.57095" + inkscape:cy="413.38853" + inkscape:document-units="px" + inkscape:current-layer="layer1" + inkscape:window-width="1386" + inkscape:window-height="971" + inkscape:window-x="0" + inkscape:window-y="0" /> + <metadata + id="metadata1915"> + <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> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1"> + <rect + style="opacity:1;fill:none;fill-opacity:1;stroke:black;stroke-width:0.52033526;stroke-miterlimit:4;stroke-dasharray:1.04067054, 0.52033527;stroke-dashoffset:0;stroke-opacity:1" + id="rect2807" + width="36.245155" + height="32.204544" + x="390.23157" + y="574.62024" /> + <rect + style="opacity:1;fill:none;fill-opacity:1;stroke:black;stroke-width:0.44547796;stroke-miterlimit:4;stroke-dasharray:0.89095592, 0.44547796;stroke-dashoffset:0;stroke-opacity:1" + id="rect2809" + width="59.048447" + height="14.601732" + x="430.82993" + y="574.9483" /> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="399.40982" + y="594.76312" + id="text3696"><tspan + sodipodi:role="line" + id="tspan3698" + x="399.40982" + y="594.76312">pic</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="445.84048" + y="586.5423" + id="text3700"><tspan + sodipodi:role="line" + id="tspan3702" + x="445.84048" + y="586.5423">label</tspan></text> + </g> +</svg> diff --git a/doc/src/declarative/pics/animatedimageitem.gif b/doc/src/declarative/pics/animatedimageitem.gif Binary files differnew file mode 100644 index 0000000..85c3cb5 --- /dev/null +++ b/doc/src/declarative/pics/animatedimageitem.gif diff --git a/doc/src/declarative/pics/blur_example.png b/doc/src/declarative/pics/blur_example.png Binary files differnew file mode 100644 index 0000000..763b112 --- /dev/null +++ b/doc/src/declarative/pics/blur_example.png diff --git a/doc/src/declarative/pics/declarative-qmlfocus1.png b/doc/src/declarative/pics/declarative-qmlfocus1.png Binary files differnew file mode 100644 index 0000000..fd05146 --- /dev/null +++ b/doc/src/declarative/pics/declarative-qmlfocus1.png diff --git a/doc/src/declarative/pics/declarative-qmlfocus2.png b/doc/src/declarative/pics/declarative-qmlfocus2.png Binary files differnew file mode 100644 index 0000000..a946e2c --- /dev/null +++ b/doc/src/declarative/pics/declarative-qmlfocus2.png diff --git a/doc/src/declarative/pics/declarative-qmlfocus3.png b/doc/src/declarative/pics/declarative-qmlfocus3.png Binary files differnew file mode 100644 index 0000000..ba55f76 --- /dev/null +++ b/doc/src/declarative/pics/declarative-qmlfocus3.png diff --git a/doc/src/declarative/pics/declarative-qmlfocus4.png b/doc/src/declarative/pics/declarative-qmlfocus4.png Binary files differnew file mode 100644 index 0000000..e21f2a6 --- /dev/null +++ b/doc/src/declarative/pics/declarative-qmlfocus4.png diff --git a/doc/src/declarative/pics/edge1.png b/doc/src/declarative/pics/edge1.png Binary files differnew file mode 100644 index 0000000..f4bc16d --- /dev/null +++ b/doc/src/declarative/pics/edge1.png diff --git a/doc/src/declarative/pics/edge2.png b/doc/src/declarative/pics/edge2.png Binary files differnew file mode 100644 index 0000000..71bda8e --- /dev/null +++ b/doc/src/declarative/pics/edge2.png diff --git a/doc/src/declarative/pics/edge3.png b/doc/src/declarative/pics/edge3.png Binary files differnew file mode 100644 index 0000000..51bb894 --- /dev/null +++ b/doc/src/declarative/pics/edge3.png diff --git a/doc/src/declarative/pics/edge4.png b/doc/src/declarative/pics/edge4.png Binary files differnew file mode 100644 index 0000000..aee3bd1 --- /dev/null +++ b/doc/src/declarative/pics/edge4.png diff --git a/doc/src/declarative/pics/edges.png b/doc/src/declarative/pics/edges.png Binary files differnew file mode 100644 index 0000000..211b101 --- /dev/null +++ b/doc/src/declarative/pics/edges.png diff --git a/doc/src/declarative/pics/edges.svg b/doc/src/declarative/pics/edges.svg new file mode 100644 index 0000000..25698ca --- /dev/null +++ b/doc/src/declarative/pics/edges.svg @@ -0,0 +1,185 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://web.resource.org/cc/" + 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" + width="744.09448819" + height="1052.3622047" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.44.1" + sodipodi:docbase="/home/mbrasser" + sodipodi:docname="edges.svg"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow1Mstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Mstart" + style="overflow:visible"> + <path + id="path3850" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.4) translate(10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Lstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Lstart" + style="overflow:visible"> + <path + id="path3856" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.8) translate(12.5,0)" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="2.8583315" + inkscape:cx="372.04724" + inkscape:cy="596.15198" + inkscape:document-units="px" + inkscape:current-layer="layer1" + inkscape:window-width="1279" + inkscape:window-height="969" + inkscape:window-x="0" + inkscape:window-y="0" /> + <metadata + id="metadata7"> + <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> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1"> + <rect + style="opacity:1;fill:#0ca9fa;fill-opacity:1;stroke:black;stroke-width:0.04639034;stroke-miterlimit:4;stroke-dasharray:0.09278069, 0.04639034;stroke-dashoffset:0;stroke-opacity:1" + id="rect1872" + width="33.656742" + height="39.808346" + x="208.86543" + y="390.22763" + rx="5" + ry="5" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 225.51888,380.99149 C 225.51888,439.06733 225.86873,439.06733 225.86873,439.06733" + id="path2760" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 242.97392,380.99149 C 242.97392,439.06733 243.32377,439.06733 243.32377,439.06733" + id="path3647" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 208.33832,380.99149 C 208.33832,439.06733 208.68817,439.06733 208.68817,439.06733" + id="path3649" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 195.91848,409.67956 C 256.44329,409.67956 256.09344,409.67956 256.09344,409.67956" + id="path3651" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 195.91848,429.97112 C 256.44329,429.97112 256.09344,429.97112 256.09344,429.97112" + id="path3653" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 195.91848,390.78742 C 256.44329,390.78742 256.09344,390.78742 256.09344,390.78742" + id="path3655" /> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="258.54242" + y="393.58627" + id="text3657"><tspan + sodipodi:role="line" + id="tspan3659" + x="258.54242" + y="393.58627" + style="font-size:10px">Top</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="258.78955" + y="412.28455" + id="text3661"><tspan + sodipodi:role="line" + id="tspan3663" + x="258.78955" + y="412.28455" + style="font-size:10px">VerticalCenter</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="260.18896" + y="433.27582" + id="text3665"><tspan + sodipodi:role="line" + id="tspan3667" + x="260.18896" + y="433.27582" + style="font-size:10px">Bottom</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="198.96443" + y="376.24954" + id="text3669"><tspan + sodipodi:role="line" + id="tspan3671" + x="198.96443" + y="376.24954" + style="font-size:10px">Left</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="230.55408" + y="375.39383" + id="text3673"><tspan + sodipodi:role="line" + id="tspan3675" + x="230.55408" + y="375.39383" + style="font-size:10px">Right</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="186.71951" + y="355.25827" + id="text3677"><tspan + sodipodi:role="line" + id="tspan3679" + x="186.71951" + y="355.25827" + style="font-size:10px">HorizontalCenter</tspan></text> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow1Mstart)" + d="M 224.2567,375.39382 C 227.40539,356.85154 227.75525,357.20139 227.75525,357.20139" + id="path3681" /> + </g> +</svg> diff --git a/doc/src/declarative/pics/edges_examples.svg b/doc/src/declarative/pics/edges_examples.svg new file mode 100644 index 0000000..31e9901 --- /dev/null +++ b/doc/src/declarative/pics/edges_examples.svg @@ -0,0 +1,109 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://web.resource.org/cc/" + 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" + width="744.09448819" + height="1052.3622047" + id="svg3885" + sodipodi:version="0.32" + inkscape:version="0.44.1" + inkscape:export-filename="/home/mbrasser/edge4.png" + inkscape:export-xdpi="189.65207" + inkscape:export-ydpi="189.65207" + sodipodi:docbase="/home/mbrasser/work/Kinetic/ngui/doc/src/pics" + sodipodi:docname="edges_examples.svg"> + <defs + id="defs3887" /> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="2" + inkscape:cx="162.62912" + inkscape:cy="591.92069" + inkscape:document-units="px" + inkscape:current-layer="layer1" + inkscape:window-width="928" + inkscape:window-height="624" + inkscape:window-x="0" + inkscape:window-y="495" /> + <metadata + id="metadata3890"> + <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> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1"> + <rect + style="opacity:1;fill:#0ca9fa;fill-opacity:1;stroke:none;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect3893" + width="50" + height="50" + x="100" + y="414.36218" /> + <rect + style="opacity:1;fill:#fa0c2a;fill-opacity:1;stroke:none;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect3895" + width="104" + height="50" + x="150" + y="414.36218" /> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="109" + y="443.65125" + id="text3897"><tspan + sodipodi:role="line" + id="tspan3899" + x="109" + y="443.65125">rect1</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="186.54297" + y="443.65125" + id="text3901"><tspan + sodipodi:role="line" + id="tspan3903" + x="186.54297" + y="443.65125">rect2</tspan></text> + <rect + style="opacity:1;fill:#0ca9fa;fill-opacity:1;stroke:none;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect3905" + width="50" + height="50" + x="254" + y="414.36218" /> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="263" + y="443.65125" + id="text3907"><tspan + sodipodi:role="line" + id="tspan3909" + x="263" + y="443.65125">rect3</tspan></text> + </g> +</svg> diff --git a/doc/src/declarative/pics/edges_qml.png b/doc/src/declarative/pics/edges_qml.png Binary files differnew file mode 100644 index 0000000..73f22f9 --- /dev/null +++ b/doc/src/declarative/pics/edges_qml.png diff --git a/doc/src/declarative/pics/edges_qml.svg b/doc/src/declarative/pics/edges_qml.svg new file mode 100644 index 0000000..1814ec6 --- /dev/null +++ b/doc/src/declarative/pics/edges_qml.svg @@ -0,0 +1,188 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://web.resource.org/cc/" + 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" + width="744.09448819" + height="1052.3622047" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.44.1" + sodipodi:docbase="/home/mbrasser/work/Kinetic/ngui/doc/src/pics" + sodipodi:docname="edges_qml.svg" + inkscape:export-filename="/home/mbrasser/edges_qml.png" + inkscape:export-xdpi="284.45999" + inkscape:export-ydpi="284.45999"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow1Mstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Mstart" + style="overflow:visible"> + <path + id="path3850" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.4) translate(10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Lstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Lstart" + style="overflow:visible"> + <path + id="path3856" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.8) translate(12.5,0)" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="2.8583315" + inkscape:cx="372.04724" + inkscape:cy="596.15198" + inkscape:document-units="px" + inkscape:current-layer="layer1" + inkscape:window-width="1279" + inkscape:window-height="969" + inkscape:window-x="0" + inkscape:window-y="0" /> + <metadata + id="metadata7"> + <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> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1"> + <rect + style="opacity:1;fill:#0ca9fa;fill-opacity:1;stroke:black;stroke-width:0.04639034;stroke-miterlimit:4;stroke-dasharray:0.09278069, 0.04639034;stroke-dashoffset:0;stroke-opacity:1" + id="rect1872" + width="33.656742" + height="39.808346" + x="208.86543" + y="390.22763" + rx="5" + ry="5" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 225.51888,380.99149 C 225.51888,439.06733 225.86873,439.06733 225.86873,439.06733" + id="path2760" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 242.97392,380.99149 C 242.97392,439.06733 243.32377,439.06733 243.32377,439.06733" + id="path3647" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 208.33832,380.99149 C 208.33832,439.06733 208.68817,439.06733 208.68817,439.06733" + id="path3649" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 195.91848,409.67956 C 256.44329,409.67956 256.09344,409.67956 256.09344,409.67956" + id="path3651" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 195.91848,429.97112 C 256.44329,429.97112 256.09344,429.97112 256.09344,429.97112" + id="path3653" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 1;stroke-dashoffset:0;stroke-opacity:1" + d="M 195.91848,390.78742 C 256.44329,390.78742 256.09344,390.78742 256.09344,390.78742" + id="path3655" /> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="258.54242" + y="393.58627" + id="text3657"><tspan + sodipodi:role="line" + id="tspan3659" + x="258.54242" + y="393.58627" + style="font-size:10px">top</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="258.78955" + y="412.28455" + id="text3661"><tspan + sodipodi:role="line" + id="tspan3663" + x="258.78955" + y="412.28455" + style="font-size:10px">verticalCenter</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="260.18896" + y="433.27582" + id="text3665"><tspan + sodipodi:role="line" + id="tspan3667" + x="260.18896" + y="433.27582" + style="font-size:10px">bottom</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="200.96443" + y="376.24954" + id="text3669"><tspan + sodipodi:role="line" + id="tspan3671" + x="200.96443" + y="376.24954" + style="font-size:10px">left</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="232.55408" + y="375.39383" + id="text3673"><tspan + sodipodi:role="line" + id="tspan3675" + x="232.55408" + y="375.39383" + style="font-size:10px">right</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="190.71951" + y="355.25827" + id="text3677"><tspan + sodipodi:role="line" + id="tspan3679" + x="190.71951" + y="355.25827" + style="font-size:10px">horizontalCenter</tspan></text> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Mstart);stroke-opacity:1" + d="M 226.2567,375.39382 C 229.40539,356.85154 229.75525,357.20139 229.75525,357.20139" + id="path3681" /> + </g> +</svg> diff --git a/doc/src/declarative/pics/flickable.gif b/doc/src/declarative/pics/flickable.gif Binary files differnew file mode 100644 index 0000000..f7a3319 --- /dev/null +++ b/doc/src/declarative/pics/flickable.gif diff --git a/doc/src/declarative/pics/flipable.gif b/doc/src/declarative/pics/flipable.gif Binary files differnew file mode 100644 index 0000000..6386f06 --- /dev/null +++ b/doc/src/declarative/pics/flipable.gif diff --git a/doc/src/declarative/pics/gridLayout_example.png b/doc/src/declarative/pics/gridLayout_example.png Binary files differnew file mode 100644 index 0000000..6b120e9 --- /dev/null +++ b/doc/src/declarative/pics/gridLayout_example.png diff --git a/doc/src/declarative/pics/gridview.png b/doc/src/declarative/pics/gridview.png Binary files differnew file mode 100644 index 0000000..d5c8b4b --- /dev/null +++ b/doc/src/declarative/pics/gridview.png diff --git a/doc/src/declarative/pics/highlight.gif b/doc/src/declarative/pics/highlight.gif Binary files differnew file mode 100644 index 0000000..fbef256 --- /dev/null +++ b/doc/src/declarative/pics/highlight.gif diff --git a/doc/src/declarative/pics/horizontalLayout_example.png b/doc/src/declarative/pics/horizontalLayout_example.png Binary files differnew file mode 100644 index 0000000..42f90ec --- /dev/null +++ b/doc/src/declarative/pics/horizontalLayout_example.png diff --git a/doc/src/declarative/pics/layout-add.gif b/doc/src/declarative/pics/layout-add.gif Binary files differnew file mode 100644 index 0000000..86e9247 --- /dev/null +++ b/doc/src/declarative/pics/layout-add.gif diff --git a/doc/src/declarative/pics/layout-move.gif b/doc/src/declarative/pics/layout-move.gif Binary files differnew file mode 100644 index 0000000..1825c22 --- /dev/null +++ b/doc/src/declarative/pics/layout-move.gif diff --git a/doc/src/declarative/pics/layout-remove.gif b/doc/src/declarative/pics/layout-remove.gif Binary files differnew file mode 100644 index 0000000..7086511 --- /dev/null +++ b/doc/src/declarative/pics/layout-remove.gif diff --git a/doc/src/declarative/pics/margins_qml.png b/doc/src/declarative/pics/margins_qml.png Binary files differnew file mode 100644 index 0000000..d7d73a3 --- /dev/null +++ b/doc/src/declarative/pics/margins_qml.png diff --git a/doc/src/declarative/pics/margins_qml.svg b/doc/src/declarative/pics/margins_qml.svg new file mode 100644 index 0000000..1f0ff02 --- /dev/null +++ b/doc/src/declarative/pics/margins_qml.svg @@ -0,0 +1,196 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://web.resource.org/cc/" + 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" + width="744.09448819" + height="1052.3622047" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.44.1" + sodipodi:docbase="/home/mbrasser/work/Kinetic/ngui/doc/src/pics" + sodipodi:docname="margins_qml.svg" + inkscape:export-filename="/home/mbrasser/edges_qml.png" + inkscape:export-xdpi="284.45999" + inkscape:export-ydpi="284.45999"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow1Send" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Send" + style="overflow:visible;"> + <path + id="path2976" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none;" + transform="scale(0.2) rotate(180) translate(6,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Sstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Sstart" + style="overflow:visible"> + <path + id="path2979" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.2) translate(6,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Mstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Mstart" + style="overflow:visible"> + <path + id="path3850" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.4) translate(10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Lstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Lstart" + style="overflow:visible"> + <path + id="path3856" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.8) translate(12.5,0)" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="2.8583315" + inkscape:cx="372.04724" + inkscape:cy="596.15198" + inkscape:document-units="px" + inkscape:current-layer="layer1" + inkscape:window-width="1279" + inkscape:window-height="969" + inkscape:window-x="0" + inkscape:window-y="0" /> + <metadata + id="metadata7"> + <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> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1"> + <rect + style="opacity:1;fill:#0ca9fa;fill-opacity:1;stroke:black;stroke-width:0.04639034;stroke-miterlimit:4;stroke-dasharray:0.09278069, 0.04639034;stroke-dashoffset:0;stroke-opacity:1" + id="rect1872" + width="33.656742" + height="39.808346" + x="208.86543" + y="390.22763" + rx="5" + ry="5" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1.02602077;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.02602088, 1.02602088;stroke-dashoffset:0;stroke-opacity:1" + d="M 252.98692,377.00435 C 252.98692,443.05433 253.31077,443.05433 253.31077,443.05433" + id="path3647" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1.02601969;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.02602007, 1.02602007;stroke-dashoffset:0;stroke-opacity:1" + d="M 198.35134,377.00433 C 198.35134,443.05431 198.67515,443.05431 198.67515,443.05431" + id="path3649" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1.02421367;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.02421381, 1.02421381;stroke-dashoffset:0;stroke-opacity:1" + d="M 193.94282,437.97112 C 257.43421,437.97112 257.06721,437.97112 257.06721,437.97112" + id="path3653" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1.02421367;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.02421381, 1.02421381;stroke-dashoffset:0;stroke-opacity:1" + d="M 193.94282,380.78742 C 257.43421,380.78742 257.06721,380.78742 257.06721,380.78742" + id="path3655" /> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="260.29169" + y="388.78741" + id="text1911"><tspan + sodipodi:role="line" + id="tspan1913" + x="260.29169" + y="388.78741" + style="font-size:10px">topMargin</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="259.65204" + y="437.27798" + id="text1915"><tspan + sodipodi:role="line" + id="tspan1917" + x="259.65204" + y="437.27798" + style="font-size:10px">bottomMargin</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="170.07939" + y="454.4209" + id="text1919"><tspan + sodipodi:role="line" + id="tspan1921" + x="170.07939" + y="454.4209" + style="font-size:10px">leftMargin</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="228.47504" + y="454.4209" + id="text1923"><tspan + sodipodi:role="line" + id="tspan1925" + x="228.47504" + y="454.4209" + style="font-size:10px">rightMargin</tspan></text> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.92020172px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Sstart);marker-end:url(#Arrow1Send);stroke-opacity:1" + d="M 225.6938,382.51213 C 225.6938,388.91693 225.6938,388.91693 225.6938,388.91693" + id="path1929" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.92007709px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Sstart);marker-end:url(#Arrow1Send);stroke-opacity:1" + d="M 225.6938,430.56703 C 225.6938,436.97192 225.6938,436.97192 225.6938,436.97192" + id="path3000" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Sstart);marker-mid:none;marker-end:url(#Arrow1Send);stroke-opacity:1" + d="M 201.16631,410.1318 C 207.81355,410.1318 207.81355,410.1318 207.81355,410.1318" + id="path3002" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Sstart);marker-mid:none;marker-end:url(#Arrow1Send);stroke-opacity:1" + d="M 244.02348,410.1318 C 250.67072,410.1318 250.67072,410.1318 250.67072,410.1318" + id="path3889" /> + </g> +</svg> diff --git a/doc/src/declarative/pics/particles.gif b/doc/src/declarative/pics/particles.gif Binary files differnew file mode 100644 index 0000000..763a8a8 --- /dev/null +++ b/doc/src/declarative/pics/particles.gif diff --git a/doc/src/declarative/pics/pathview.gif b/doc/src/declarative/pics/pathview.gif Binary files differnew file mode 100644 index 0000000..4052eb2 --- /dev/null +++ b/doc/src/declarative/pics/pathview.gif diff --git a/doc/src/declarative/pics/propanim.gif b/doc/src/declarative/pics/propanim.gif Binary files differnew file mode 100644 index 0000000..f86406e --- /dev/null +++ b/doc/src/declarative/pics/propanim.gif diff --git a/doc/src/declarative/pics/qtlogo.png b/doc/src/declarative/pics/qtlogo.png Binary files differnew file mode 100644 index 0000000..399bd0b --- /dev/null +++ b/doc/src/declarative/pics/qtlogo.png diff --git a/doc/src/declarative/pics/reflection_example.png b/doc/src/declarative/pics/reflection_example.png Binary files differnew file mode 100644 index 0000000..fd9bb48 --- /dev/null +++ b/doc/src/declarative/pics/reflection_example.png diff --git a/doc/src/declarative/pics/scalegrid.svg b/doc/src/declarative/pics/scalegrid.svg new file mode 100644 index 0000000..e386f3d --- /dev/null +++ b/doc/src/declarative/pics/scalegrid.svg @@ -0,0 +1,183 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://web.resource.org/cc/" + 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" + width="744.09448819" + height="1052.3622047" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.44.1" + sodipodi:docbase="/home/mbrasser/work/Kinetic/ngui/doc/src/pics" + sodipodi:docname="scalegrid.svg" + inkscape:export-filename="/home/mbrasser/work/Kinetic/ngui/doc/src/pics/scalegrid.png" + inkscape:export-xdpi="189.65207" + inkscape:export-ydpi="189.65207"> + <defs + id="defs4" /> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="50" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="3.2163554" + inkscape:cx="173.89302" + inkscape:cy="703.69531" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="true" + inkscape:grid-bbox="false" + inkscape:guide-bbox="false" + inkscape:window-width="1409" + inkscape:window-height="1016" + inkscape:window-x="0" + inkscape:window-y="0" /> + <metadata + id="metadata7"> + <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> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1"> + <rect + style="opacity:1;fill:red;fill-opacity:1;stroke:none;stroke-width:3;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + id="rect1876" + width="45.104" + height="45.137001" + x="119.16868" + y="301.00308" + rx="5" + ry="5" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.3965202;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.79304035, 0.39652018;stroke-dashoffset:0;stroke-opacity:1" + d="M 157.02483,295.52571 C 157.02483,352.04784 157.02483,352.04784 157.02483,352.04784" + id="path2766" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.39652267;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.79304534, 0.39652268;stroke-dashoffset:0;stroke-opacity:1" + d="M 126.2,295.64284 C 126.2,352.16567 126.2,352.16567 126.2,352.16567" + id="path2768" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.39652267;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.79304534, 0.39652268;stroke-dashoffset:0;stroke-opacity:1" + d="M 169.05321,308.25967 C 112.53038,308.25967 112.53038,308.25967 112.53038,308.25967" + id="path2770" /> + <path + style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:black;stroke-width:0.39652267;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.79304534, 0.39652268;stroke-dashoffset:0;stroke-opacity:1" + d="M 169.08024,339.77238 C 112.55741,339.77238 112.55741,339.77238 112.55741,339.77238" + id="path2772" /> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Arial Black" + x="115.2857" + y="303.60583" + id="text2774"><tspan + sodipodi:role="line" + id="tspan2776" + x="115.2857" + y="303.60583">1</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="137.19142" + y="303.60583" + id="text2782"><tspan + sodipodi:role="line" + id="tspan2784" + x="137.19142" + y="303.60583" + style="font-family:Arial Black">2</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Arial Black" + x="161.56842" + y="303.45935" + id="text2786"><tspan + sodipodi:role="line" + id="tspan2788" + x="161.56842" + y="303.45935">3</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="114.72613" + y="327.00702" + id="text2790"><tspan + sodipodi:role="line" + id="tspan2792" + x="114.72613" + y="327.00702" + style="font-family:Arial Black">4</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="137.12404" + y="326.86053" + id="text2794"><tspan + sodipodi:role="line" + id="tspan2796" + x="137.12404" + y="326.86053" + style="font-family:Arial Black">5</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="161.49518" + y="326.86053" + id="text2798"><tspan + sodipodi:role="line" + id="tspan2800" + x="161.49518" + y="326.86053" + style="font-family:Arial Black">6</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="114.70855" + y="351.25809" + id="text2802"><tspan + sodipodi:role="line" + id="tspan2804" + x="114.70855" + y="351.25809" + style="font-family:Arial Black">7</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="137.08595" + y="351.1116" + id="text2806"><tspan + sodipodi:role="line" + id="tspan2808" + x="137.08595" + y="351.1116" + style="font-family:Arial Black">8</tspan></text> + <text + xml:space="preserve" + style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + x="161.58307" + y="351.1116" + id="text2810"><tspan + sodipodi:role="line" + id="tspan2812" + x="161.58307" + y="351.1116" + style="font-family:Arial Black">9</tspan></text> + </g> +</svg> diff --git a/doc/src/declarative/pics/shadow_example.png b/doc/src/declarative/pics/shadow_example.png Binary files differnew file mode 100644 index 0000000..6214620 --- /dev/null +++ b/doc/src/declarative/pics/shadow_example.png diff --git a/doc/src/declarative/pics/spacing_a.png b/doc/src/declarative/pics/spacing_a.png Binary files differnew file mode 100644 index 0000000..ff07e2e --- /dev/null +++ b/doc/src/declarative/pics/spacing_a.png diff --git a/doc/src/declarative/pics/spacing_b.png b/doc/src/declarative/pics/spacing_b.png Binary files differnew file mode 100644 index 0000000..94304ee --- /dev/null +++ b/doc/src/declarative/pics/spacing_b.png diff --git a/doc/src/declarative/pics/trivialListView.png b/doc/src/declarative/pics/trivialListView.png Binary files differnew file mode 100644 index 0000000..175e455 --- /dev/null +++ b/doc/src/declarative/pics/trivialListView.png diff --git a/doc/src/declarative/pics/verticalLayout_example.png b/doc/src/declarative/pics/verticalLayout_example.png Binary files differnew file mode 100644 index 0000000..458dc7f --- /dev/null +++ b/doc/src/declarative/pics/verticalLayout_example.png diff --git a/doc/src/declarative/pics/verticalLayout_transition.gif b/doc/src/declarative/pics/verticalLayout_transition.gif Binary files differnew file mode 100644 index 0000000..ed61adb --- /dev/null +++ b/doc/src/declarative/pics/verticalLayout_transition.gif diff --git a/doc/src/declarative/pics/webview.png b/doc/src/declarative/pics/webview.png Binary files differnew file mode 100644 index 0000000..0d24586 --- /dev/null +++ b/doc/src/declarative/pics/webview.png diff --git a/doc/src/declarative/qmlforcpp.qdoc b/doc/src/declarative/qmlforcpp.qdoc new file mode 100644 index 0000000..7aa2560 --- /dev/null +++ b/doc/src/declarative/qmlforcpp.qdoc @@ -0,0 +1,999 @@ +/*! + \page qmlforcpp.html + \target qmlforcpp + \title Qt Declarative Markup Language For C++ Programmers + + This page describes the QML format and how to use and extend it from C++. + + The QML syntax declaratively describes in XML how to construct an in memory + object tree. QML is usually used to describe a visual scene graph - using + \l {graphicsview}{GraphicsView} or the \l {fxprimitives}{Fx Primitives} - but it is not conceptually + limited to this: the QML format is an abstract XML description of \b any + object tree. + + QML also includes property bindings. Bindings are ECMAScript expressions + of a properties value. Whenever the value of the expression changes - + either for the first time at startup or subsequently thereafter - the + property is automatically updated with the new value. + + \section1 Loading and using QML Files + + QmlComponent is used to load a QML file and to create object instances. + + In QML a component is the unit of instantiation, and the most basic unit + of scope. A component is like a template for how to construct an object + tree. One component can create multiple instances of this tree, but the + template remains constant. + + The following code uses the C++ interface to create 100 red rectangles + based on a simple declarative component description. + \raw html + <table border="0"> + <tr> + <td> + \endraw + \code + QmlComponent redRectangle("<Rect color=\"red\" width=\"100\" height=\"100\" />"); + for (int ii = 0; ii < 100; ++ii) { + QObject *rectangle = redRectangle.create(); + // ... do something with the rectangle ... + } + \endcode + \raw html + </td> + </tr> + </table> + \endraw + + Each independent XML file describes a QML component, but it is + also possible to create sub-components within a QML file as will be + shown later. + + \section1 QML Format 101 + + This is some sample QML code. + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + <Image id="myRect" x="10" y="10" width="100" height="100" src="background.png"> + <Text width="100"> + <height>50</height> + <color>white</color> + <font.fontSize>16</font.fontSize> + Hello world! + </Text> + </Image> + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + In QML, XML tags and attributes correspond to Qt objects and properties. + The general rule of thumb is any tag or attribute name that starts with a + capital letter refers to a class, and names that start with a lower case + letter to properties. It is not possible to access a property that starts + with a capital letter from QML. + + The QML snippet shown above instantiates one \c Image instance and one + \c Text instance and sets properties on both. \b Everything in QML + ultimately comes down to either instantiating an object instance, or + assigning a property a value. QML relies heavily on Qt's meta object system + and can only instantiate classes that derive from QObject. + + Setting properties can be done in two ways: as an XML attribute directly on + the class tag that created the the object, or as sub-tags. + Although syntactically different, their behaviour is identical. The two QML + snippets below behave exactly the same. +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + <Rect x="10" y="10" /> + \endcode +\raw HTML + </td> + <td> +\endraw + \code + <Rect> + <x>10</x> + <y>10</y> + </Rect> + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + Arbitrary mixing and matching between the two is allowed. + + QML can set properties that are more complex than just simple types like + integers and strings. Properties can be object pointers or Qt interface pointers + or even lists of object or Qt interface pointers! QML is typesafe, and will + ensure that only the valid types are assigned to properties. + + Assigning an object to a property is as simple as assigning a basic + integer. Attempting to assign an object to a property when type coercian + fails will produce an error. The following shows an example of valid and of + invalid QML and the corresponding C++ classes. + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + class Image : public QObject + { + ... + Q_PROPERTY(ImageFilter *filter READ filter WRITE setFilter) + }; + + class ImageFilter : public QObject + { + ... + }; + \endcode +\raw HTML + </td> + <td> +\endraw + \code + <!-- OK --> + <Image> + <filter> + <ImageFilter /> + </filter> + </Image> + + <!-- NOT OK: Image cannot be cast into ImageFilter --> + <Image> + <filter> + <Image /> + </filter> + </Image> + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + Classes can also define an optional default property. The default property + is used for assignment if no explicit property has been specified. + In the example below, the string "Hello World!" will be assigned to + the \c Text element's default property - which happens to be the \c text + property. Both lines do the same thing, one explicitly and one implicitly. + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + <Text text="Hello World!" /> + <Text>Hello World!</Text> + \endcode +\raw HTML + </td> + <td> +\endraw + \code + class Text : public QObject + { + ... + Q_PROPERTY(QString text READ text WRITE setText) + Q_CLASSINFO("DefaultProperty", "text") + }; + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + Any object property can be the default, even complex properties like lists + of objects. The default property of the \c Rect class is the \c children + property, a list of \c Item's. In the following example, as both \c Image + and \c Text inherit from \c Item the \c Image and \c Text instances are + added to the parent's \c children property. + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + <Rect> + <Image /> + <Text /> + </Rect> + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + Properties that return read-only object pointers can be used recursively. + This can be used, for example, to group properties together. The + \c Text element has a \c font property that returns an object with a number + of sub-properties such as \c family, \c bold, \c italic and \c size. + QML makes it easy to interact with these grouped properties, as the + following shows - everything you would expect to work, just does. + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + class Text : public ... + { + ... + Q_PROPERTY(Font *font READ font); + }; + class Font : public QObject + { + ... + Q_PROPERTY(QString family READ family WRITE setFamily); + Q_PROPERTY(bool bold READ bold WRITE setBold); + Q_PROPERTY(bool italic READ italic WRITE setItalic); + Q_PROPERTY(int size READ size WRITE setSize); + }; + \endcode +\raw HTML + </td> + <td> +\endraw + \code + <Text font.family="helvetica"> + <font> + <bold>true</bold> + <italic>true</italic> + </font> + <font.size>12</font.size> + </Text> + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + \section1 Defining QML Types + + The QML engine has no intrinsic knowledge of any class types. Instead + the programmer must define the C++ types, and their corresponding QML + name. There are three ways of adding known types to the QML engine: + \list + \o + \code + #define QML_DECLARE_TYPE(T) + #define QML_DEFINE_TYPE(T,QmlName) + \endcode + Adding these macros to your library or executable automatically makes the + C++ type \a T available from the declarative markup language under the + name \a QmlName. Of course there's nothing stopping you using the same + name for both the C++ and the QML name!<br> + Most types are added to the QML engine using these macros. The only + requirement is that \a T inherits QObject and has a default constructor. + \o + \code + #define QML_DEFINE_CUSTOM_PARSER(QmlName, CustomParserClass) + \endcode + Custom parsers define a way to translate between declarative XML and an + object instance in the case the default object model lets you down. Free + form lists (\c {<ListModel>} are an example of a custom parser. + Custom parsers implement the \l QmlCustomParser interface. + + Custom parsers give a developer very fine grain control over how a type is + instantiated from the XML that describes it. During the + compilation phase, the custom parser is presented with the XML via a + QXmlStreamReader and must + compile this down into an opaque blob that is returned to the compiler. + When, at runtime, the type is instantiated, the opaque blob is passed into + the custom parser, which must return a QObject derived type. + + \o QML::ClassFactory + + The QML engine calls the class factory as a last resort when trying to + create a type. The class factory returns a \l QmlComponent instance for + the type if it can create it. This allows "on the fly" types to be created. + For example, a class factory is used to support automatic instantiation of + .qml template files. + \endlist + + \section1 Property Binding + + Assigning constant values and trees to properties will only get you so + far. Property binding allows a property's value to be dependant on the + value of other properties and data. Whenever these dependencies change, + the property's value is automatically updated. + + Property bindings are ECMAScript expressions and can be applied to any + object property. C++ classes don't have to do anything special to get + binding support other than define appropriate properties. Property binding + expressions are differentiated from regular constant literals by surrounding + them in braces. + + Here's a simple example that stacks a red, blue and green rectangle. + Bindings are used to ensure that the height of each is kept equal to it's + parent's. Were the root rectangle's height property to change, the child + rectangles height would be updated automatically. +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + <Rect color="red" width="100"> + <Rect color="blue" width="50" height="{parent.height}"> + <Rect color="green" width="25" height="{parent.height}"> + </Rect> + </Rect> + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + Binding expressions execute in a context. A context behaves as a scope and + defines how the expression resolves property and variable names. Although + the two expressions in the last example are the same, the value of \c parent + resolves differently because each executes in a different context. Although + QML generally takes care of everything for the programmer, a thorough + understanding of bind contexts is important in some of the more complex QML + structures. + + Every expression is executed in a bind context, encapsulated by the + QmlBindContext C++ class. As covered in the class documentation, a + bind context contains a map of names to values, and a list of default + objects. When resolving a name, the name to value map is searched first. + If the name cannot be found, the default object's are iterated in turn and + the context attempts to resolve the name as a property of one of the default + objects. + + There are generally two contexts involved in the execution of a binding. + The first is the "object context" - a bind context associated with the + closest instantiated object and containing just one default object, and + that's instantiated object itself. The effect of the object + context is pretty simple - names in the binding expression resolve to + properties on the object first. It is important to note - particularly in + the case of grouped properties - the object context is that of the + instantiated object, the consequences of which are shown below. + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + <!-- OK --> <!-- NOT OK: Text has no italic property --> + <Text> <Text> + <font> <font> + <bold>{font.italic}</bold> <bold>{italic}</bold> + </font> </font> + </Text> </Text> + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + The second context is the "component context". Each QML component (and + consequently each QML file) is created in its own unique binding context. + Like the object context, the component context contains just one default + object - but in this case it is the component's root object. An example + will illustrate best - the resultant text will read "background.png". + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + <Image src="background.png"> + <Text text="{src}" /> + </Image> + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + If the name is not found in either of these contexts, the context heirarchy + is searched parent-by-parent until the name is either found, or the + heirarchy is exhausted. + + The first property binding example shown involved fixing the height of three + rectangles. It did this by fixing the height of each rectangle to its + parent, rather than fixing them all to a single common point. Here's the + example rewritten to do just that. + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + <Rect color="red" width="100"> + <Rect color="blue" width="50" height="{parent.height}"> + <Rect color="green" width="25" height="{parent.parent.height}"> + </Rect> + </Rect> + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + Clearly this sort of fragile relationship is undesirable and unmanageable - + moving the green rectangle to be a sibling of the blue or introducing a + further rectangle between the two would break the example. + + To address this problem, QML includes a way to directly reference any object + within a component (or parent component for that matter), called "ids". + Developers assign an object an id, and can then reference it directly by + name. Developers assign an object an id by setting the special \c id + property. Every object automatically has this magical property (if the + object also has an actual property called \c id, that gets set too). As + an id allows an object to be referenced directly, it must be unique within + a component. Any number of id's can exist, but they must all begin with + a capital letter. An id of "Root" is valid, while an id of "root" is not. + \note This is not technically true - lowercase id names do work, but are + slower. Support will probably be removed for them eventually. + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + <Rect id="Root" color="red" width="{GreenRect.width + 75}"> + <Rect color="blue" width="{GreenRect.width + 25}" height="{Root.height}"> + <Rect id="GreenRect" color="green" width="25" height="{Root.height}"> + </Rect> + </Rect> + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + To relate id's back to QmlBindContext, id's exist as properties on the + component context. + + Bind expressions can reference any object property. The QML bind engine + relies on the presence of the NOTIFY signal in the Q_PROPERTY declaration + on a class to alert it that a property's value has changed. If this is + omitted, the bind expression can still access the property's value, but + the expression will not be updated if the value changes. The following is + an example of a QML friendly property declaration. + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + class Example : public QObject + { + Q_OBJECT + Q_PROPERTY(int sample READ sample WRITE setSample NOTIFY sampleChanged) + public: + int sample() const; + void setSample(int); + signals: + void sampleChanged(int); + }; + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + While generally no changes are needed to a C++ class to use property + binding, sometimes more advanced interaction between the binding engine and + an object is desirable. To facilitate this, there is a special exception + in the bind engine for allowing an object to access the binding directly. + + If a binding is assigned to a property with a type of QmlBindableValue + pointer (ie. QmlBindableValue *), each time the binding value changes, + a QmlBindableValue instance is assigned to that property. The + QmlBindableValue instance allows the object to read the binding and to + evaluate the binding's current value. + + \section1 Signal Properties + + In addition to reading and writing regular properties, QML allows you to + easily associate ECMAScript with signals. Consider the following example, + in which Button is a made-up type with a clicked() signal. + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + <Button text="Hello world!" onClicked="print(text)" /> + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + Clicking on the button causes "Hello world!" to be printed to the console + (or lost forever if you're running Windows). + + Like properties, signals automatically become available in QML without + any additional work. As illustrated signals are mapped into QML as special + "signal properties", using the name "on<Signal Name>" where the first + character of the signal's name is uppercased. If more than one signal of + the same name is exist on a class, only the first is available (see the + \l {xmlConnection}{<Connection>} element for more general signal connections). + + An important observation to make here is the lack of braces. While both + property bindings and signal properties involve executing ECMAScript code, + property bindings dynamically update the property value (hence the braces), + whereas with signal properties the constant script "value" is actually + assigned to the signal property. Trying to bind a value to a signal + property will not work! + + Signal parameters are also available to the executing script, as shown + below, as long as you remember to name the parameters of your signal + in C++ (see QMetaMethod::parameterNames()). + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + <Example> + <onDoSomething> + for(var ii = 0; ii < count; ++ii) + print(message) + </onDoSomething> + </Example> + \endcode +\raw HTML + </td> + <td> +\endraw + \code + class Example : public QObject + { + Q_OBJECT + signals: + void doSomething(int count, const QString &message); + }; + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + Just like property bindings, signal scripts are executed in a context. The + signal script context is identical in scope to the "object context" under + property binding, with the exception that it has the signal parameters + bound in. + + In addition to scripts, it is possible to assign objects to signal properties. + This automatically connects the signal to the object's default method. A + default method is defined just like a default property, though the special + "DefaultMethod" class info. + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + Q_CLASSINFO("DefaultMethod", "myMethod(int)"); + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + This is useful in achieving several use cases, like that below which moves + the button when it is clicked. + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + <Button id="MyButton"> + <onClicked> + <NumericAnimation target="{MyButton}" property="x" to="100" /> + </onClicked> + </Button> + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + + If the class itself actually defines a property called "on<Name>", this will + be assigned the string value and the signal handling behaviour will be + disabled. + + \section1 Attached Properties + + Attached properties allow unrelated types to annotate another type with some + additional properties. Some APIs or operations are inherintly imperative, + and attached properties help out when translating these APIs into the + declarative QML language. + + Qt's QGridLayout is one such example. + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + <QGridLayout> + <QLabel QGridLayout.row="0" QGridLayout.column="0" text="Name:"/> + <QLineEdit QGridLayout.row="0" QGridLayout.column="1" /> + + <QLabel QGridLayout.row="1" QGridLayout.column="0" text="Occupation:"/> + <QLineEdit QGridLayout.row="1" QGridLayout.column="1" /> + </QGridLayout> + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + Attached properties are identified by the use of a class name, in the + case shown \c QGridLayout, as a grouped property specifier. To prevent + ambiguity with actual class instantiations, attached properties must + always be specified to include a period but can otherwise be used just like + regular properties. + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + <!-- OK --> <!-- NOT OK: Creates a QGridLayout, rather than assigning attached property --> + <QLabel> <QLabel> + <QGridLayout.row>0</QGridLayout.row> <QGridLayout> + </QLabel> <row>0</row> + </QGridLayout> + </QLabel> + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + C++ types provide attached properties by declaring the public function \c qmlAttachedProperties like this example. + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + static QObject *Type::qmlAttachedProperties(QObject *); + \endcode +\raw HTML + </td> + <td> +\endraw + \code + class Example : public QObject + { + Q_OBJECT + public: + static QObject *qmlAttachedProperties(QObject *); + }; + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + When an attached property is accessed, the QML engine will call this method + to create an attachment object, passing in the object instance that the + attached property applies to. The attachment object should define all + the attached properties, and is generally parented to the provided object + instance to avoid memory leaks. The QML engine does not save this object, + so it is necessary for the attached property function to ensure that + multiple calls for the same instance object return the same attached object. + + While conceptually simple, implementing an attachment object is not quite + so easy. The \c qmlAttachedProperties function is static - attachment + objects are not associated with any particular instance. How the values + of the attached properties apply to the behaviour they are controlling is + entirely implementation dependent. An additional consequence of this is + that \b any object can attach \b any attached property. The following is + perfectly valid, although the attached property has no actual effect: + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + <FancyGridLayout> + <Item> + <Button QGridLayout.row="1" /> + </Item> + </FancyGridLayout> + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + The property has no effect because the (made-up) FancyGridLayout type defines the meaning + of the \c row attached property only to apply to its direct children. It + is possible that other types may have attached properties that affect + objects that aren't their direct children. + + Attached properties are an advanced feature that should be used with + caution. + + \note We may implement a convenience wrapper that makes using attached + properties easier for the common "attach to children" case. + + \section1 Property Value Sources + + Intrinsically, the QML engine can assign a property either a static value, + such as a number of object tree, or a property binding. It is possible for + advanced users to extend the engine to assign other "types" of values to + properties. These "types" are known as property value sources. + + Consider the following \l {fxprimitives}{Fx Primitives} example. + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + <Rect width="100" height="100" color="red"> + <x> + <NumericAnimation running="true" repeat="true" from="0" to="100" /> + </x> + </Rect> + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + Here the \c x property of the rectangle will be animated from 0 to 100. + To support this, the NumericAnimation class inherits the + QmlPropertyValueSource class. If a type inherits this class and is assigned + to a property for which type assignment would otherwise fail (ie. the + property itself doesn't have a type of QmlPropertyValueSource *), the QML + engine will automatically set the property as the target of the value + source. + + \section1 Extending types in QML + + QML is designed to allow you to build fully working types without writing + a line of C++ code. This is, for example, used extensively when designing + applications using the \l {fxprimitives}{Fx Primitives}. To create new types, it is + necessary to be able to define new signals, slots and properties in QML. + + \note slots are not yet supported + + Any object is extensible in this way under QML, using the special + \c properties and \c signals properties. Like \c id, these two properties + are automatically available on all types under QML and accessible from + other QML files or directly from C++. + + In this example, a Button is extended to have an additional + "text2" property (which always returns "Hello world!") and an additional + signal "clicked2" that is also emitted when the button is clicked. Not + a very useful extension, but an extension nonetheless. + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + QmlComponent component(xmlData); + QObject *object = component.create(); + // Will print "Hello world!" + qDebug() << object->property("text2"); + // Will be emitted whenever the button is clicked + QObject::connect(object, SIGNAL(clicked2()), this, SLOT(...)); + \endcode +\raw HTML + </td> + <td> +\endraw + \code + <Button text="Hello!"> + <properties> + <Property name="text2" type="string" /> + </properties> + <signals> + <Signal name="clicked2" /> + </signals> + <text2>Hello world!</text2> + <onClicked>clicked2.emit()</onClicked> + </Button> + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + Any number of properties and signals can be added to an existing type. The + \c Property and \c Signal elements have the following properties that can + be set: + \table + \header \o Tag \o Property \o Description + \row \o Property \o name \o The name of the property + \row \o Property \o type \o The type of the property. The available types are: \list \o int \o bool \o double \o real \o string \o color \o date \o variant \endlist The default is variant. + \row \o Property \o value \o The initial value of the property. Setting this is just a shortcut for setting the property normally, as shown in the example above. + \row \o Property \o onValueChanged \o A special signal property that is emitted each time the property value changes. + \row \o Property \o default \o Set this as the object's default property + \row \o Signal \o name \o The name of the signal. + \endtable + + If the type itself actually defines a property called \c properties or + \c signals, the respective extension will be disabled for that type and + the types own properties will be set. + + \section1 Parser Status + + Generally using QML is a breeze - you implement your classes in C++, add + the appropriate properties, signals and slots and off you go. The QML + engine takes care of instantiating your classes and setting the properties + and everything works fine. + + However, sometimes it is helpful to know a little more about the status of + the QML parser. For example, it might be beneficial from a performance + standpoint to delay initializing some data structures until all the + properties have been set. + + To assist with this, the QML engine defines an interface class called + QmlParserStatus. The interface defines a number of virtual methods that are + invoked at various stages of the component instantiation. To receive + these notifications, all a class has to do is to inherit the interface, and + notify the Qt meta system using the Q_INTERFACES() macro. For example, + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + class Example : public QObject, public QmlParserStatus + { + Q_OBJECT + Q_INTERFACES(QmlParserStatus) + public: + virtual void componentComplete() + { + qDebug() << "Woohoo! Now to do my costly initialization"; + } + }; + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + \section1 Extended Type Definitions + + QML requires that types have the appropriate properties and signals to + work well within the declarative environment. In the case of existing + types, it is sometimes necessary to add signals, properties or slots to a + target class to make it more QML friendly but the original type cannot be + modified. For these cases, the QML engine supports extended type + definitions. + + An extended type definition allows the programmer to supply an additional + type - known as the extension type - when registering the target class + whose properties, signals and slots are transparently merged with the + original target class when used from within QML. + + An extension class is a regular QObject, with a constructor that takes a + QObject pointer. When needed (extension classes are delay created + until the first extension attribute is accessed) the extension + class is created and the target object is passed in as the parent. When + an extension attribute on the original is accessed, the appropriate signal, + property or slots on the extension object is used instead. + + When an extended type is installed, the +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + #define QML_DEFINE_EXTENDED_TYPE(T,QmlName,ExtendedTypeName) + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + macro should be used instead of the regular \c QML_DEFINE_TYPE. + + This example shows the addition of a read-only \c textLength property to + QLabel being implemented as an extension. + +\raw HTML + <table border="0"> + <tr> + <td> +\endraw + \code + class QLabelExtension : public QObject + { + Q_OBJECT + Q_PROPERTY(int textLength READ textLength) + public: + QWidgetExtension(QObject *parent) : QObject(parent) {} + int textLength() const { + return static_cast<QLabel *>(parent())->text().count(); + } + }; + QML_DEFINE_EXTENDED_TYPE(QLabel,QLabel,QLabelExtension); + \endcode +\raw HTML + </td> + <td> +\endraw + \code + <QLabel id="Label1" text="Hello World!" /> + <QLabel text="{'Label1 text length:' + Label1.textLength}" /> + \endcode +\raw HTML + </td> + </tr> + </table> +\endraw + + Attributes defined through extensions are inherited, just like attributes + defined on a normal class. Any types that inherit from \c QLabel, will + also have the \c textLength property. Derived types can include additional + extensions which are merged together, but only a single extension can be + specified for each single C++ class. + + Extended type definitions can even be used to add an attached properties + function to a type - just declare the \c qmlAttachedProperties function on + the extension object. + +*/ + diff --git a/doc/src/declarative/qtprogrammers.qdoc b/doc/src/declarative/qtprogrammers.qdoc new file mode 100644 index 0000000..92caa3f --- /dev/null +++ b/doc/src/declarative/qtprogrammers.qdoc @@ -0,0 +1,121 @@ +/*! +\page qtprogrammers.html +\target qtprogrammers +\title QML for Qt programmers + +\section1 Overview + +While QML does not require Qt knowledge to use, if you \e are already familar 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. + +\section1 Familiar Concepts + +QML provides direct access to the following concepts from Qt: + +\list + \o QAction - the \l {basicxmlaction}{action} type + \o QObject signals and slots - available as functions to call in JavaScript + \o QObject properties - available as variables in JavaScript + \o QWidget - QFxView is a QML-displaying widget + \o Qt models - used directly in data binding (currently only next generation QListModelInterface) +\endlist + +Qt knowledge is \e required for \l {cppitem}{writing elements in C++}. + + +\section1 QML Items compared with QWidgets + +QML Items are very similar to QWidgets: they define the look and feel of the user interface. (Note that while QWidgets +haven't traditionally been used to define the look and feel of view delegates, QML Items can be used for this as well.) + +There are three structurally different types of QWidget: + +\list + \o Simple widgets that are not used as parents (QLabel, QCheckBox, QToolButton, etc.) + \o Parent widgets that are normally used as parents to other widgets (QGroupBox, QStackedWidget, QTabWidget, etc.) + \o Compound widgets that are internally composed of child widgets (QComboBox, QSpinBox, QFileDialog, QTabWidget, etc.) +\endlist + +QML Items also serve these purposes. Each is considered separately below. + +\section2 Simple Widgets + +The most important rule to remember while implementing a new QFxItem in C++ +is that it should not contain any look and feel policies - leave that to the +QML usage of the item. + +As an example, imagine you wanted a reusable Button item. If you therefore +decided to write a QFxItem subclass to implement a button, +just as QToolButton subclasses QWidget for this purpose, following the rule above, your +"QFxButton" would not have any appearance - just the notions of enabled, triggering, etc. + +But there is already an object in Qt that does this: QAction. + +QAction is the UI-agnostic essence of QPushButton, QCheckBox, QMenu items, QToolButton, +and other visual widgets that are commonly bound to a QAction. + +So, the job of implementing a checkbox abstraction for QML is already done - it's QAction. +The look and feel of an action - the appearance of the button, the transition between states, +and exactly how it respond to mouse, key, or touch input, should all be left for definition +in QML. + +It is illustrative to note that QFxTextEdit is built upon QTextControl, +QFxWebView is built upon QWebPage, and ListView uses QListModelInterface, +just as QTextEdit, QWebView, and QListView are built upon +those same UI-agnostic components. + +The encapsulation of the look and feel that QWidgets gives is important, and for this +the QML concept of \l components serves the same purpose. If you are building a complete +suite of applications which should have a consistent look and feel, you should build +a set of reusable components with the look and feel you desire. + +So, to implement your reusable button, you would simply build a QML component. + + +\section2 Parent Widgets + +Parent widgets each provide a generic way to interface to one or more arbitrary other widgets. +A QTabWidget provides an interface to multiple "pages", one of which is visible at any time, +and a mechnism for selecting among them (the QTabBar). A QScollArea provides scrollbars around +a widget that is otherwise too large to fit in available space. + +Nearly all such components can be created directly in QML. Only a few cases +which require very particular event handling, such as Flickable, require C++ implementations. + +As an example, imagine you decided to make a generic tab widget item to be used +through your application suite wherever information is in such quantity that it +needs to be divided up into pages. + +To do this in QML, ... \todo example of container definition. + +A significant difference in the parenting concept with QML compare to QWidgets +is that while child items are positioned relative to their parents, +there is no requirement that they be wholy contained ("clipped") to +the parent (although the clipped property of the child Item does allow +this where it is needed). +This difference has rather far-reaching consequences, for example: + +\list + \o A shadow or highlight around a widget could be a child of that widget. + \o Particle effects can flow outside the object where they originate. + \o Transitioning animations can "hide" items by visibly moving them beyond the screen bounds. +\endlist + + +\section2 Compound Widgets + +Some widgets provide functionality by composing other widgets as an "implementation detail", +providing a higher level API to the composition. QSpinBox for example is a line edit and some +buttons to increase/decrease the edited value. QFileDialog uses a whole host of widgets to +give the user a way of finding and selecting a file name. + +When developing reusable QML Items, you may choose to do the same: build an item composed +of other items you have already defined. + +The only caveat when doing this is to consider the possible animations and transitions that +users of the compound item might wish to employ. For example, a spinbox might need to smoothly +transition from an arbitrary Text item, or characters within a Text item, so your spinbox +item would need to be sufficiently flexible to allow such animation. + +*/ diff --git a/doc/src/declarative/scenegraph.qdoc b/doc/src/declarative/scenegraph.qdoc new file mode 100644 index 0000000..2340324 --- /dev/null +++ b/doc/src/declarative/scenegraph.qdoc @@ -0,0 +1,13 @@ +/*! + \page graphicsview.html + \target graphicsview + \title GraphicsView + +*/ + +/*! + \page fxprimitives.html + \target fxprimitives + \title FX Primitives + +*/ diff --git a/doc/src/declarative/tutorial.qdoc b/doc/src/declarative/tutorial.qdoc new file mode 100644 index 0000000..6fe3929 --- /dev/null +++ b/doc/src/declarative/tutorial.qdoc @@ -0,0 +1,19 @@ +/*! +\page tutorial.html +\title Tutorial + +This tutorial gives an introduction to QML and the Fluid UI atoms. It doesn't cover everything; the emphasis is on teaching the key principles, and features are introduced as needed. + +Chapter one starts with a minimal "Hello world" program and the following chapters introduce new concepts. + +The tutorial's source code is located in the $QTDIR/examples/declarative/tutorials directory. + +Tutorial chapters: + +\list +\o \l {tutorial1}{Tutorial 1} +\o \l {tutorial2}{Tutorial 2} +\o \l {tutorial3}{Tutorial 3} +\endlist + +*/ diff --git a/doc/src/declarative/tutorial1.qdoc b/doc/src/declarative/tutorial1.qdoc new file mode 100644 index 0000000..15edaff --- /dev/null +++ b/doc/src/declarative/tutorial1.qdoc @@ -0,0 +1,55 @@ +/*! +\page tutorial1.html +\title Tutorial 1 - Hello World! +\target tutorial1 + +This first program is a simple "Hello world" example. The picture below is a screenshot of this program. + +\image declarative-tutorial1.png + +Here is the QML code for the application: + +\code +<Rect id="Page" width="480" height="200" color="white"> + <Text id="HelloText" text="Hello world!" font.size="24" font.bold="true" y="30" anchors.horizontalCenter="{Page.horizontalCenter}"/> +</Rect> +\endcode + +\section1 Walkthrough + +\section2 Rect element + +\code +<Rect id="Page" width="480" height="200" color="white"> +\endcode + +First, we declare a root element of type \l {xmlRect}{Rect}. It is one of the basic building blocks you can use to create an application in QML. +We give it an id to be able to refer to it later. In this case, we call it \e Page. We also set the \c width, \c height and \c color properties. +The \l {xmlRect}{Rect} element contains many other properties (such as \c x and \c y), but these are left at their default values. + +\section2 Text element + +\code +<Text id="HelloText" text="Hello world!" y="30" font.size="24" font.bold="true" anchors.horizontalCenter="{Page.horizontalCenter}"/> +\endcode + +We add a text element as a child of our root element to display the text 'Hello world!'. + +The \c y property is used to position the text vertically at 30 pixels from the top of its parent. + +The \c font.size and \c font.bold properties are related to fonts and use the 'dot' notation (see \l {declarative}{Declarative UI} ). + +The \c anchors.horizontalCenter property refers to the horizontal center of an element. In this case, we bind the center of our text element to the center of the \e Page element. We use braces to indicate that \c Page.horizontalCenter is a bound ECMAScript expression that needs to be evaluated. It also means that if the center of \e Page changes (for example if it is resized) our text will be re-centered automatically (see \l binding). + +\section2 Viewing the example + +To view what you have created, run the duiviewer (located in the \c bin directory) with your filename as the first argument. For example, to run the provided completed Tutorial 1 example from the install location, you would type: + +\code +bin/duiviewer examples/tutorials/t1/tutorial1.qml +\endcode + +[\l tutorial] [Next: \l tutorial2] + +*/ + diff --git a/doc/src/declarative/tutorial2.qdoc b/doc/src/declarative/tutorial2.qdoc new file mode 100644 index 0000000..8898e68 --- /dev/null +++ b/doc/src/declarative/tutorial2.qdoc @@ -0,0 +1,94 @@ +/*! +\page tutorial2.html +\title Tutorial 2 - Some colors +\target tutorial2 + +This chapter adds a color picker to change the color of the text. + +\image declarative-tutorial2.png + +Our color picker is made of many cells with different colors. To avoid writing the same code many times, we first create a new \c Cell component with a color property (see \l components). + +Here is the QML code for \c Cell.qml: + +\code +<Item id="CellContainer" width="40" height="25"> + <properties> + <Property name="color"/> + </properties> + <Rect anchors.fill="{parent}" color="{CellContainer.color}"/> + <MouseRegion anchors.fill="{parent}" onClick="HelloText.color = CellContainer.color" /> +</Item> +\endcode + +Then, we use our \c Cell component to create the color picker in the QML code for the application: + +\code +<Rect id="Page" width="480" height="200" color="white"> + <Text id="HelloText" text="Hello world!" font.size="24" font.bold="true" y="30" anchors.horizontalCenter="{Page.horizontalCenter}"/> + <GridLayout id="ColorPicker" x="0" anchors.bottom="{Page.bottom}" width="120" height="50" columns="3" rows="2"> + <Cell color="#ff0000"/> + <Cell color="#00ff00"/> + <Cell color="#0000ff"/> + <Cell color="#ffff00"/> + <Cell color="#00ffff"/> + <Cell color="#ff00ff"/> + </GridLayout> +</Rect> +\endcode + +\section1 Walkthrough + +\section2 The Cell Component + +\code +<Item id="CellContainer" width="40" height="25"> +\endcode + +The root element of our component is an \c Item. It is the most basic 'Fx' element in Qml and is often used as a container for other elements. + +\code +<properties> + <Property name="color"/> +</properties> +\endcode + +We declare a \c color property. This property is accessible from \i outside our component, this allows us to instantiate the cells with different colors. + +\code +<Rect anchors.fill="{parent}" color="{CellContainer.color}"/> +\endcode + +Our cell component is basically a colored rectangle. + +The \c anchors.fill property is a convenient way to set the size of an element. In this case the \c Rect will have the same size as its parent. + +We bind the \c color property of this \c Rect to the color property of our component. + +\code +<MouseRegion anchors.fill="{parent}" onClick="HelloText.color = CellContainer.color" /> +\endcode + +In order to change the color of the text when clicking on a cell, we create a \c MouseRegion element with the same size as its parent. + +The \c onClick property sets the \c color property of the element named \i HelloText to our cell color. + +\section2 The main QML file + +\code +<GridLayout id="ColorPicker" x="0" anchors.bottom="{Page.bottom}" width="120" height="50" columns="3" rows="2"> + <Cell color="#ff0000"/> + <Cell color="#00ff00"/> + <Cell color="#0000ff"/> + <Cell color="#ffff00"/> + <Cell color="#00ffff"/> + <Cell color="#ff00ff"/> +</GridLayout> +\endcode + +In the main QML file, the only thing we have to do is to create a color picker by putting 6 cells with different colors in a grid layout. + +[Previous: \l tutorial1] [Next: \l tutorial3] + +*/ + diff --git a/doc/src/declarative/tutorial3.qdoc b/doc/src/declarative/tutorial3.qdoc new file mode 100644 index 0000000..91ab9f0 --- /dev/null +++ b/doc/src/declarative/tutorial3.qdoc @@ -0,0 +1,83 @@ +/*! +\page tutorial3.html +\title Tutorial 3 - States +\target tutorial3 + +In this chapter, we make this example a little bit more dynamic by introducing states. + +We want our text to jump at the bottom of the screen and become red when clicked. + +\image declarative-tutorial3_animation.gif + +Here is the QML code: + +\code +<Rect id="Page" width="480" height="200" color="white"> + <Text id="HelloText" text="Hello world!" font.size="24" font.bold="true" y="30" anchors.horizontalCenter="{Page.horizontalCenter}"> + <states> + <State name="down" when="{MouseRegion.pressed == true}"> + <SetProperty target="{HelloText}" property="y" value="160"/> + <SetProperty target="{HelloText}" property="color" value="red"/> + </State> + </states> + <transitions> + <Transition fromState="*" toState="down" reversible="true"> + <ParallelAnimation> + <NumericAnimation properties="y" duration="500" easing="easeOutBounce"/> + <ColorAnimation duration="500"/> + </ParallelAnimation> + </Transition> + </transitions> + </Text> + <MouseRegion id="MouseRegion" anchors.fill="{HelloText}"/> + <GridLayout id="ColorPicker" x="0" anchors.bottom="{Page.bottom}" width="120" height="50" columns="3" rows="2"> + <Cell color="#ff0000"/> + <Cell color="#00ff00"/> + <Cell color="#0000ff"/> + <Cell color="#ffff00"/> + <Cell color="#00ffff"/> + <Cell color="#ff00ff"/> + </GridLayout> +</Rect> +\endcode + +\section1 Walkthrough + +\code +<states> + <State name="down" when="{MouseRegion.pressed == true}"> + <SetProperty target="{HelloText}" property="y" value="160"/> + <SetProperty target="{HelloText}" property="color" value="red"/> + </State> +</states> +\endcode + +First, we create a new state \e down for our text element. This state will be activated when \l {xmlMouseRegion}{MouseRegion} is pressed, and deactivated when it is released. + +The \e down state includes a set of property changes from our implicit \e {default state} (the items as they were initially defined in the QML). Specifically, we set the \c y property of the text to 160 and the \c color to red. + +\code +<Transition fromState="*" toState="down" reversible="true"> +\endcode + +Because we don't want the text to appear at the bottom instantly but rather move smoothly, we add a transition between our two states. + +\c fromState and \c toState define the states between which the transition will run. In this case, we want a transition from any state to our \e down state. + +Because we want the same transition to be run in reverse when changing back from the \e down state to the default state, we set \c reversible to \c true. This is equivalent to writing the two transitions separately. + +\code +<ParallelAnimation> + <NumericAnimation properties="y" duration="500" easing="easeOutBounce"/> + <ColorAnimation duration="500"/> +</ParallelAnimation> +\endcode + +The \c ParallelAnimation element makes sure that the two animations (color and position) will start at the same time. We could also run them one after the other by using \c SequentialAnimation instead. + +For more details on states and transitions, see \l {states-transitions}{States and Transitions}. + +[Previous: \l tutorial2] [\l tutorial] + +*/ + diff --git a/doc/src/diagrams/programs/easingcurve/easingcurve.pro b/doc/src/diagrams/programs/easingcurve/easingcurve.pro new file mode 100644 index 0000000..0b80127 --- /dev/null +++ b/doc/src/diagrams/programs/easingcurve/easingcurve.pro @@ -0,0 +1,13 @@ +###################################################################### +# Automatically generated by qmake (2.01a) fr 13. feb 13:26:38 2009 +###################################################################### + +TEMPLATE = app +TARGET = +DEPENDPATH += . +INCLUDEPATH += . + +# Input +SOURCES += main.cpp + +CONFIG += console
\ No newline at end of file diff --git a/doc/src/diagrams/programs/easingcurve/main.cpp b/doc/src/diagrams/programs/easingcurve/main.cpp new file mode 100644 index 0000000..98e9d37 --- /dev/null +++ b/doc/src/diagrams/programs/easingcurve/main.cpp @@ -0,0 +1,90 @@ +/**************************************************************************** +** +** Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the $MODULE$ of the Qt Toolkit. +** +** $TROLLTECH_DUAL_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +void createCurveIcons(); + +int main(int argc, char **argv) +{ + QApplication app(argc, argv); + createCurveIcons(); + return app.exit(); +} + +void createCurveIcons() +{ + QDir dir(QDir::current()); + if (dir.dirName() == QLatin1String("debug") || dir.dirName() == QLatin1String("release")) { + dir.cdUp(); + } + dir.cdUp(); + dir.cdUp(); + dir.cdUp(); + QSize iconSize(128, 128); + QPixmap pix(iconSize); + QPainter painter(&pix); + QLinearGradient gradient(0,0, 0, iconSize.height()); + gradient.setColorAt(0.0, QColor(240, 240, 240)); + gradient.setColorAt(1.0, QColor(224, 224, 224)); + QBrush brush(gradient); + const QMetaObject &mo = QEasingCurve::staticMetaObject; + QMetaEnum metaEnum = mo.enumerator(mo.indexOfEnumerator("Type")); + QFont oldFont = painter.font(); + // Skip QEasingCurve::Custom + QString output(QString::fromAscii("%1/images").arg(dir.absolutePath())); + printf("Generating images to %s\n", qPrintable(output)); + for (int i = 0; i < QEasingCurve::NCurveTypes - 1; ++i) { + painter.setFont(oldFont); + QString name(QLatin1String(metaEnum.key(i))); + painter.fillRect(QRect(QPoint(0, 0), iconSize), brush); + QEasingCurve curve((QEasingCurve::Type)i); + painter.setPen(QColor(0, 0, 255, 64)); + qreal xAxis = iconSize.height()/1.5; + qreal yAxis = iconSize.width()/3; + painter.drawLine(0, xAxis, iconSize.width(), xAxis); // hor + painter.drawLine(yAxis, 0, yAxis, iconSize.height()); // ver + + qreal curveScale = iconSize.height()/2; + + painter.drawLine(yAxis - 2, xAxis - curveScale, yAxis + 2, xAxis - curveScale); // hor + painter.drawLine(yAxis + curveScale, xAxis + 2, yAxis + curveScale, xAxis - 2); // ver + painter.drawText(yAxis + curveScale - 8, xAxis - curveScale - 4, QLatin1String("(1,1)")); + + painter.drawText(yAxis + 42, xAxis + 10, QLatin1String("progress")); + painter.drawText(15, xAxis - curveScale - 10, QLatin1String("ease")); + + painter.setPen(QPen(Qt::red, 1, Qt::DotLine)); + painter.drawLine(yAxis, xAxis - curveScale, yAxis + curveScale, xAxis - curveScale); // hor + painter.drawLine(yAxis + curveScale, xAxis, yAxis + curveScale, xAxis - curveScale); // ver + + QPoint currentPos(yAxis, xAxis); + + painter.setPen(Qt::black); + QFont font = oldFont; + font.setPixelSize(oldFont.pixelSize() + 15); + painter.setFont(font); + painter.drawText(0, iconSize.height() - 20, iconSize.width(), 20, Qt::AlignHCenter, name); + + for (qreal t = 0; t < 1.0; t+=1.0/curveScale) { + QPoint to; + to.setX(yAxis + curveScale * t); + to.setY(xAxis - curveScale * curve.valueForProgress(t)); + painter.drawLine(currentPos, to); + currentPos = to; + } + QString fileName(QString::fromAscii("qeasingcurve-%1.png").arg(name.toLower())); + printf("%s\n", qPrintable(fileName)); + pix.save(QString::fromAscii("%1/%2").arg(output).arg(fileName), "PNG"); + } +} + + diff --git a/doc/src/duiviewer.qdoc b/doc/src/duiviewer.qdoc new file mode 100644 index 0000000..f967f87 --- /dev/null +++ b/doc/src/duiviewer.qdoc @@ -0,0 +1,80 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page duiviewer.html + \title Declarative UI Viewer (duiviewer) + \ingroup qttools + \keyword duiviewer + + This page documents the \e{Declarative UI Viewer} for the Qt GUI + toolkit. The \c duiviewer reads an XML format declarative user interface definition + (\c .qml) file + and displays the user interface it describes. + + \section1 Options + + When run with the \c -help option, duiviewer shows available options. + + \section1 Dummy Data + + One use of duiviewer is to allow QML files to be viewed stand-alone, + rather than being loaded from within a Qt program. Qt applications will + usually bind objects and properties into the execution context before + running the QML. To stand-in for such bindings, you can provide dummy + data: create a directory called "dummydata" in the same directory as + the target QML file and create files there with the "qml" extension. + All such files will be loaded as QML objects and bound to the root + context as a property with the name of the file (without ".qml"). + + For example, if the Qt application has a "clock.time" property + that is a qreal from 0 to 86400 representing the number of seconds since + midnight, dummy data for this could be provided by \c dummydata/clock.qml: + \code + <Object> + <properties> + <Property name="time" value="12345"/> + </properties> + </Object> + \endcode + Any QML can be used in the dummy data files. You could even animate the + fictional data! +*/ diff --git a/doc/src/examples.qdoc b/doc/src/examples.qdoc index e3c2291..b750aa0 100644 --- a/doc/src/examples.qdoc +++ b/doc/src/examples.qdoc @@ -307,6 +307,12 @@ \o \l{sql/sqlwidgetmapper}{SQL Widget Mapper}\raisedaster \endlist + \section1 State Machine + + \list + \o \l{statemachine/trafficlight}{Traffic Light}\raisedaster + \endlist + \section1 Threads \list diff --git a/doc/src/examples/trafficlight.qdoc b/doc/src/examples/trafficlight.qdoc new file mode 100644 index 0000000..16ee8ad --- /dev/null +++ b/doc/src/examples/trafficlight.qdoc @@ -0,0 +1,58 @@ +/**************************************************************************** +** +** Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the $MODULE$ of the Qt Toolkit. +** +** $TROLLTECH_DUAL_LICENSE$ +** +****************************************************************************/ + +/*! + \example statemachine/trafficlight + \title Traffic Light Example + + The Traffic Light example shows how to use \l{The State Machine Framework} + to implement the control flow of a traffic light. + + \image trafficlight-example.png + + In this example we write a TrafficLightWidget class. The traffic light has + three lights: Red, yellow and green. The traffic light transitions from + one light to another (red to yellow to green to yellow to red again) at + certain intervals. + + \snippet examples/statemachine/trafficlight/main.cpp 0 + + The LightWidget class represents a single light of the traffic light. It + provides a setOn() function to turn the light on or off. It paints itself + in the color that's passed to the constructor. + + \snippet examples/statemachine/trafficlight/main.cpp 2 + + The TrafficLightWidget class represents the visual part of the traffic + light; it's a widget that contains three lights, and provides accessor + functions for these. + + \snippet examples/statemachine/trafficlight/main.cpp 1 + + The LightState class represents a state that turns a light on when the + state is entered, and off when the state is exited. The class is a timer, + and as we shall see the timeout is used to transition from one LightState + to another. + + \snippet examples/statemachine/trafficlight/main.cpp 3 + + The TrafficLight class combines the TrafficLightWidget with control flow + based on the LightState class. The state graph has four states: + red-to-yellow, yellow-to-green, green-to-yellow and yellow-to-red. The + initial state is red-to-yellow; when the state's timer times out, the + state machine transitions to yellow-to-green. The same process repeats + through the other states. + + \snippet examples/statemachine/trafficlight/main.cpp 4 + + The main() function constructs a TrafficLight and shows it. + +*/ diff --git a/doc/src/external-resources.qdoc b/doc/src/external-resources.qdoc index f48c3d7..3bfb5af 100644 --- a/doc/src/external-resources.qdoc +++ b/doc/src/external-resources.qdoc @@ -334,6 +334,16 @@ */ /*! + \externalpage http://www.w3.org/TR/scxml/ + \title State Chart XML: State Machine Notation for Control Abstraction +*/ + +/*! + \externalpage http://www.wisdom.weizmann.ac.il/~dharel/SCANNED.PAPERS/Statecharts.pdf + \title Statecharts: A visual formalism for complex systems +*/ + +/*! \externalpage http://www.gnu.org/licenses/gpl.html \title GNU General Public License */ diff --git a/doc/src/groups.qdoc b/doc/src/groups.qdoc index c9cedc4..0411c3a 100644 --- a/doc/src/groups.qdoc +++ b/doc/src/groups.qdoc @@ -69,6 +69,18 @@ */ /*! + \group animations + \ingroup groups + + \title Animation Framework + \brief Classes for animations, states and transitions. + + These classes provide a framework for creating both simple and complex + animations. The Animation Framework also provides states and animated + transitions, making it easy to create animated stateful forms. +*/ + +/*! \group abstractwidgets \title Abstract Widget Classes \ingroup groups @@ -597,3 +609,14 @@ These classes are relevant to developers who are working with Qt Script's debugging features. */ + +/*! + \group statemachine + \ingroup groups + + \title State Machine Classes + \brief Classes for constructing and executing state graphs. + + These classes are provided by \l{The State Machine Framework} for creating + event-driven state machines. +*/ diff --git a/doc/src/images/declarative-anchors_example.png b/doc/src/images/declarative-anchors_example.png Binary files differnew file mode 100644 index 0000000..293cd4b --- /dev/null +++ b/doc/src/images/declarative-anchors_example.png diff --git a/doc/src/images/declarative-anchors_example2.png b/doc/src/images/declarative-anchors_example2.png Binary files differnew file mode 100644 index 0000000..6d3be7d --- /dev/null +++ b/doc/src/images/declarative-anchors_example2.png diff --git a/doc/src/images/declarative-image_tile.png b/doc/src/images/declarative-image_tile.png Binary files differnew file mode 100644 index 0000000..b946a6d --- /dev/null +++ b/doc/src/images/declarative-image_tile.png diff --git a/doc/src/images/declarative-item_opacity1.png b/doc/src/images/declarative-item_opacity1.png Binary files differnew file mode 100644 index 0000000..cde973b --- /dev/null +++ b/doc/src/images/declarative-item_opacity1.png diff --git a/doc/src/images/declarative-item_opacity2.png b/doc/src/images/declarative-item_opacity2.png Binary files differnew file mode 100644 index 0000000..8627360 --- /dev/null +++ b/doc/src/images/declarative-item_opacity2.png diff --git a/doc/src/images/declarative-item_stacking1.png b/doc/src/images/declarative-item_stacking1.png Binary files differnew file mode 100644 index 0000000..18f4148 --- /dev/null +++ b/doc/src/images/declarative-item_stacking1.png diff --git a/doc/src/images/declarative-item_stacking2.png b/doc/src/images/declarative-item_stacking2.png Binary files differnew file mode 100644 index 0000000..7a71bcd --- /dev/null +++ b/doc/src/images/declarative-item_stacking2.png diff --git a/doc/src/images/declarative-item_stacking3.png b/doc/src/images/declarative-item_stacking3.png Binary files differnew file mode 100644 index 0000000..cde973b --- /dev/null +++ b/doc/src/images/declarative-item_stacking3.png diff --git a/doc/src/images/declarative-item_stacking4.png b/doc/src/images/declarative-item_stacking4.png Binary files differnew file mode 100644 index 0000000..3fdf627 --- /dev/null +++ b/doc/src/images/declarative-item_stacking4.png diff --git a/doc/src/images/declarative-qtlogo1.png b/doc/src/images/declarative-qtlogo1.png Binary files differnew file mode 100644 index 0000000..940d159 --- /dev/null +++ b/doc/src/images/declarative-qtlogo1.png diff --git a/doc/src/images/declarative-qtlogo2.png b/doc/src/images/declarative-qtlogo2.png Binary files differnew file mode 100644 index 0000000..b1d128a --- /dev/null +++ b/doc/src/images/declarative-qtlogo2.png diff --git a/doc/src/images/declarative-qtlogo3.png b/doc/src/images/declarative-qtlogo3.png Binary files differnew file mode 100644 index 0000000..3f2f93f --- /dev/null +++ b/doc/src/images/declarative-qtlogo3.png diff --git a/doc/src/images/declarative-qtlogo4.png b/doc/src/images/declarative-qtlogo4.png Binary files differnew file mode 100644 index 0000000..7c8aa64 --- /dev/null +++ b/doc/src/images/declarative-qtlogo4.png diff --git a/doc/src/images/declarative-rect.png b/doc/src/images/declarative-rect.png Binary files differnew file mode 100644 index 0000000..173759a --- /dev/null +++ b/doc/src/images/declarative-rect.png diff --git a/doc/src/images/declarative-rect_gradient.png b/doc/src/images/declarative-rect_gradient.png Binary files differnew file mode 100644 index 0000000..f79d579 --- /dev/null +++ b/doc/src/images/declarative-rect_gradient.png diff --git a/doc/src/images/declarative-rect_tint.png b/doc/src/images/declarative-rect_tint.png Binary files differnew file mode 100644 index 0000000..3a44013 --- /dev/null +++ b/doc/src/images/declarative-rect_tint.png diff --git a/doc/src/images/declarative-rotation.png b/doc/src/images/declarative-rotation.png Binary files differnew file mode 100644 index 0000000..994011b --- /dev/null +++ b/doc/src/images/declarative-rotation.png diff --git a/doc/src/images/declarative-scale.png b/doc/src/images/declarative-scale.png Binary files differnew file mode 100644 index 0000000..bab729e --- /dev/null +++ b/doc/src/images/declarative-scale.png diff --git a/doc/src/images/declarative-scalegrid.png b/doc/src/images/declarative-scalegrid.png Binary files differnew file mode 100644 index 0000000..32d87125 --- /dev/null +++ b/doc/src/images/declarative-scalegrid.png diff --git a/doc/src/images/declarative-text.png b/doc/src/images/declarative-text.png Binary files differnew file mode 100644 index 0000000..c1a4112 --- /dev/null +++ b/doc/src/images/declarative-text.png diff --git a/doc/src/images/declarative-textedit.gif b/doc/src/images/declarative-textedit.gif Binary files differnew file mode 100644 index 0000000..7186eb9 --- /dev/null +++ b/doc/src/images/declarative-textedit.gif diff --git a/doc/src/images/declarative-textformat.png b/doc/src/images/declarative-textformat.png Binary files differnew file mode 100644 index 0000000..ade1b45 --- /dev/null +++ b/doc/src/images/declarative-textformat.png diff --git a/doc/src/images/declarative-textstyle.png b/doc/src/images/declarative-textstyle.png Binary files differnew file mode 100644 index 0000000..858c1bc --- /dev/null +++ b/doc/src/images/declarative-textstyle.png diff --git a/doc/src/images/declarative-transformorigin.png b/doc/src/images/declarative-transformorigin.png Binary files differnew file mode 100644 index 0000000..fbb3b9b --- /dev/null +++ b/doc/src/images/declarative-transformorigin.png diff --git a/doc/src/images/declarative-tutorial1.png b/doc/src/images/declarative-tutorial1.png Binary files differnew file mode 100644 index 0000000..a936054 --- /dev/null +++ b/doc/src/images/declarative-tutorial1.png diff --git a/doc/src/images/declarative-tutorial2.png b/doc/src/images/declarative-tutorial2.png Binary files differnew file mode 100644 index 0000000..7871589 --- /dev/null +++ b/doc/src/images/declarative-tutorial2.png diff --git a/doc/src/images/declarative-tutorial3_animation.gif b/doc/src/images/declarative-tutorial3_animation.gif Binary files differnew file mode 100644 index 0000000..0465e61 --- /dev/null +++ b/doc/src/images/declarative-tutorial3_animation.gif diff --git a/doc/src/images/qeasingcurve-cosinecurve.png b/doc/src/images/qeasingcurve-cosinecurve.png Binary files differnew file mode 100644 index 0000000..b27e763 --- /dev/null +++ b/doc/src/images/qeasingcurve-cosinecurve.png diff --git a/doc/src/images/qeasingcurve-inback.png b/doc/src/images/qeasingcurve-inback.png Binary files differnew file mode 100644 index 0000000..8506c0f --- /dev/null +++ b/doc/src/images/qeasingcurve-inback.png diff --git a/doc/src/images/qeasingcurve-inbounce.png b/doc/src/images/qeasingcurve-inbounce.png Binary files differnew file mode 100644 index 0000000..275b38c --- /dev/null +++ b/doc/src/images/qeasingcurve-inbounce.png diff --git a/doc/src/images/qeasingcurve-incirc.png b/doc/src/images/qeasingcurve-incirc.png Binary files differnew file mode 100644 index 0000000..b985e9c --- /dev/null +++ b/doc/src/images/qeasingcurve-incirc.png diff --git a/doc/src/images/qeasingcurve-incubic.png b/doc/src/images/qeasingcurve-incubic.png Binary files differnew file mode 100644 index 0000000..e417ee1 --- /dev/null +++ b/doc/src/images/qeasingcurve-incubic.png diff --git a/doc/src/images/qeasingcurve-incurve.png b/doc/src/images/qeasingcurve-incurve.png Binary files differnew file mode 100644 index 0000000..d9a9340 --- /dev/null +++ b/doc/src/images/qeasingcurve-incurve.png diff --git a/doc/src/images/qeasingcurve-inelastic.png b/doc/src/images/qeasingcurve-inelastic.png Binary files differnew file mode 100644 index 0000000..b242fd3 --- /dev/null +++ b/doc/src/images/qeasingcurve-inelastic.png diff --git a/doc/src/images/qeasingcurve-inexpo.png b/doc/src/images/qeasingcurve-inexpo.png Binary files differnew file mode 100644 index 0000000..f06316c --- /dev/null +++ b/doc/src/images/qeasingcurve-inexpo.png diff --git a/doc/src/images/qeasingcurve-inoutback.png b/doc/src/images/qeasingcurve-inoutback.png Binary files differnew file mode 100644 index 0000000..9fd1446 --- /dev/null +++ b/doc/src/images/qeasingcurve-inoutback.png diff --git a/doc/src/images/qeasingcurve-inoutbounce.png b/doc/src/images/qeasingcurve-inoutbounce.png Binary files differnew file mode 100644 index 0000000..fb65f31 --- /dev/null +++ b/doc/src/images/qeasingcurve-inoutbounce.png diff --git a/doc/src/images/qeasingcurve-inoutcirc.png b/doc/src/images/qeasingcurve-inoutcirc.png Binary files differnew file mode 100644 index 0000000..123cc54 --- /dev/null +++ b/doc/src/images/qeasingcurve-inoutcirc.png diff --git a/doc/src/images/qeasingcurve-inoutcubic.png b/doc/src/images/qeasingcurve-inoutcubic.png Binary files differnew file mode 100644 index 0000000..b07695c --- /dev/null +++ b/doc/src/images/qeasingcurve-inoutcubic.png diff --git a/doc/src/images/qeasingcurve-inoutelastic.png b/doc/src/images/qeasingcurve-inoutelastic.png Binary files differnew file mode 100644 index 0000000..65851e1 --- /dev/null +++ b/doc/src/images/qeasingcurve-inoutelastic.png diff --git a/doc/src/images/qeasingcurve-inoutexpo.png b/doc/src/images/qeasingcurve-inoutexpo.png Binary files differnew file mode 100644 index 0000000..7cbfb13 --- /dev/null +++ b/doc/src/images/qeasingcurve-inoutexpo.png diff --git a/doc/src/images/qeasingcurve-inoutquad.png b/doc/src/images/qeasingcurve-inoutquad.png Binary files differnew file mode 100644 index 0000000..c5eed06 --- /dev/null +++ b/doc/src/images/qeasingcurve-inoutquad.png diff --git a/doc/src/images/qeasingcurve-inoutquart.png b/doc/src/images/qeasingcurve-inoutquart.png Binary files differnew file mode 100644 index 0000000..3b66c0d --- /dev/null +++ b/doc/src/images/qeasingcurve-inoutquart.png diff --git a/doc/src/images/qeasingcurve-inoutquint.png b/doc/src/images/qeasingcurve-inoutquint.png Binary files differnew file mode 100644 index 0000000..c74efe9 --- /dev/null +++ b/doc/src/images/qeasingcurve-inoutquint.png diff --git a/doc/src/images/qeasingcurve-inoutsine.png b/doc/src/images/qeasingcurve-inoutsine.png Binary files differnew file mode 100644 index 0000000..5964f31 --- /dev/null +++ b/doc/src/images/qeasingcurve-inoutsine.png diff --git a/doc/src/images/qeasingcurve-inquad.png b/doc/src/images/qeasingcurve-inquad.png Binary files differnew file mode 100644 index 0000000..3373310 --- /dev/null +++ b/doc/src/images/qeasingcurve-inquad.png diff --git a/doc/src/images/qeasingcurve-inquart.png b/doc/src/images/qeasingcurve-inquart.png Binary files differnew file mode 100644 index 0000000..28086d8 --- /dev/null +++ b/doc/src/images/qeasingcurve-inquart.png diff --git a/doc/src/images/qeasingcurve-inquint.png b/doc/src/images/qeasingcurve-inquint.png Binary files differnew file mode 100644 index 0000000..330aa85 --- /dev/null +++ b/doc/src/images/qeasingcurve-inquint.png diff --git a/doc/src/images/qeasingcurve-insine.png b/doc/src/images/qeasingcurve-insine.png Binary files differnew file mode 100644 index 0000000..63d9238 --- /dev/null +++ b/doc/src/images/qeasingcurve-insine.png diff --git a/doc/src/images/qeasingcurve-linear.png b/doc/src/images/qeasingcurve-linear.png Binary files differnew file mode 100644 index 0000000..2a05885 --- /dev/null +++ b/doc/src/images/qeasingcurve-linear.png diff --git a/doc/src/images/qeasingcurve-outback.png b/doc/src/images/qeasingcurve-outback.png Binary files differnew file mode 100644 index 0000000..7cb34c6 --- /dev/null +++ b/doc/src/images/qeasingcurve-outback.png diff --git a/doc/src/images/qeasingcurve-outbounce.png b/doc/src/images/qeasingcurve-outbounce.png Binary files differnew file mode 100644 index 0000000..932fc16 --- /dev/null +++ b/doc/src/images/qeasingcurve-outbounce.png diff --git a/doc/src/images/qeasingcurve-outcirc.png b/doc/src/images/qeasingcurve-outcirc.png Binary files differnew file mode 100644 index 0000000..a1a6cb6 --- /dev/null +++ b/doc/src/images/qeasingcurve-outcirc.png diff --git a/doc/src/images/qeasingcurve-outcubic.png b/doc/src/images/qeasingcurve-outcubic.png Binary files differnew file mode 100644 index 0000000..aa1d604 --- /dev/null +++ b/doc/src/images/qeasingcurve-outcubic.png diff --git a/doc/src/images/qeasingcurve-outcurve.png b/doc/src/images/qeasingcurve-outcurve.png Binary files differnew file mode 100644 index 0000000..a949ae4 --- /dev/null +++ b/doc/src/images/qeasingcurve-outcurve.png diff --git a/doc/src/images/qeasingcurve-outelastic.png b/doc/src/images/qeasingcurve-outelastic.png Binary files differnew file mode 100644 index 0000000..2a9ba39 --- /dev/null +++ b/doc/src/images/qeasingcurve-outelastic.png diff --git a/doc/src/images/qeasingcurve-outexpo.png b/doc/src/images/qeasingcurve-outexpo.png Binary files differnew file mode 100644 index 0000000..e771c2e --- /dev/null +++ b/doc/src/images/qeasingcurve-outexpo.png diff --git a/doc/src/images/qeasingcurve-outinback.png b/doc/src/images/qeasingcurve-outinback.png Binary files differnew file mode 100644 index 0000000..7523727 --- /dev/null +++ b/doc/src/images/qeasingcurve-outinback.png diff --git a/doc/src/images/qeasingcurve-outinbounce.png b/doc/src/images/qeasingcurve-outinbounce.png Binary files differnew file mode 100644 index 0000000..ab73d02 --- /dev/null +++ b/doc/src/images/qeasingcurve-outinbounce.png diff --git a/doc/src/images/qeasingcurve-outincirc.png b/doc/src/images/qeasingcurve-outincirc.png Binary files differnew file mode 100644 index 0000000..ec4b8d3 --- /dev/null +++ b/doc/src/images/qeasingcurve-outincirc.png diff --git a/doc/src/images/qeasingcurve-outincubic.png b/doc/src/images/qeasingcurve-outincubic.png Binary files differnew file mode 100644 index 0000000..8b8ae68 --- /dev/null +++ b/doc/src/images/qeasingcurve-outincubic.png diff --git a/doc/src/images/qeasingcurve-outinelastic.png b/doc/src/images/qeasingcurve-outinelastic.png Binary files differnew file mode 100644 index 0000000..89dde2c --- /dev/null +++ b/doc/src/images/qeasingcurve-outinelastic.png diff --git a/doc/src/images/qeasingcurve-outinexpo.png b/doc/src/images/qeasingcurve-outinexpo.png Binary files differnew file mode 100644 index 0000000..5909901 --- /dev/null +++ b/doc/src/images/qeasingcurve-outinexpo.png diff --git a/doc/src/images/qeasingcurve-outinquad.png b/doc/src/images/qeasingcurve-outinquad.png Binary files differnew file mode 100644 index 0000000..7ddefee --- /dev/null +++ b/doc/src/images/qeasingcurve-outinquad.png diff --git a/doc/src/images/qeasingcurve-outinquart.png b/doc/src/images/qeasingcurve-outinquart.png Binary files differnew file mode 100644 index 0000000..00ef597 --- /dev/null +++ b/doc/src/images/qeasingcurve-outinquart.png diff --git a/doc/src/images/qeasingcurve-outinquint.png b/doc/src/images/qeasingcurve-outinquint.png Binary files differnew file mode 100644 index 0000000..361bfaa4 --- /dev/null +++ b/doc/src/images/qeasingcurve-outinquint.png diff --git a/doc/src/images/qeasingcurve-outinsine.png b/doc/src/images/qeasingcurve-outinsine.png Binary files differnew file mode 100644 index 0000000..1737041 --- /dev/null +++ b/doc/src/images/qeasingcurve-outinsine.png diff --git a/doc/src/images/qeasingcurve-outquad.png b/doc/src/images/qeasingcurve-outquad.png Binary files differnew file mode 100644 index 0000000..6f27cbd --- /dev/null +++ b/doc/src/images/qeasingcurve-outquad.png diff --git a/doc/src/images/qeasingcurve-outquart.png b/doc/src/images/qeasingcurve-outquart.png Binary files differnew file mode 100644 index 0000000..d45a0b8 --- /dev/null +++ b/doc/src/images/qeasingcurve-outquart.png diff --git a/doc/src/images/qeasingcurve-outquint.png b/doc/src/images/qeasingcurve-outquint.png Binary files differnew file mode 100644 index 0000000..6e7df0e --- /dev/null +++ b/doc/src/images/qeasingcurve-outquint.png diff --git a/doc/src/images/qeasingcurve-outsine.png b/doc/src/images/qeasingcurve-outsine.png Binary files differnew file mode 100644 index 0000000..7546a0d --- /dev/null +++ b/doc/src/images/qeasingcurve-outsine.png diff --git a/doc/src/images/qeasingcurve-sinecurve.png b/doc/src/images/qeasingcurve-sinecurve.png Binary files differnew file mode 100644 index 0000000..ca67d44 --- /dev/null +++ b/doc/src/images/qeasingcurve-sinecurve.png diff --git a/doc/src/images/statemachine-button-history.png b/doc/src/images/statemachine-button-history.png Binary files differnew file mode 100644 index 0000000..cd66478 --- /dev/null +++ b/doc/src/images/statemachine-button-history.png diff --git a/doc/src/images/statemachine-button-nested.png b/doc/src/images/statemachine-button-nested.png Binary files differnew file mode 100644 index 0000000..60360d1 --- /dev/null +++ b/doc/src/images/statemachine-button-nested.png diff --git a/doc/src/images/statemachine-button.png b/doc/src/images/statemachine-button.png Binary files differnew file mode 100644 index 0000000..75d9e53 --- /dev/null +++ b/doc/src/images/statemachine-button.png diff --git a/doc/src/images/statemachine-finished.png b/doc/src/images/statemachine-finished.png Binary files differnew file mode 100644 index 0000000..802621e --- /dev/null +++ b/doc/src/images/statemachine-finished.png diff --git a/doc/src/images/statemachine-nonparallel.png b/doc/src/images/statemachine-nonparallel.png Binary files differnew file mode 100644 index 0000000..1fe60d8 --- /dev/null +++ b/doc/src/images/statemachine-nonparallel.png diff --git a/doc/src/images/statemachine-parallel.png b/doc/src/images/statemachine-parallel.png Binary files differnew file mode 100644 index 0000000..1868792 --- /dev/null +++ b/doc/src/images/statemachine-parallel.png diff --git a/doc/src/images/trafficlight-example.png b/doc/src/images/trafficlight-example.png Binary files differnew file mode 100644 index 0000000..3431542 --- /dev/null +++ b/doc/src/images/trafficlight-example.png diff --git a/doc/src/index.qdoc b/doc/src/index.qdoc index 49dfafd..cf75381 100644 --- a/doc/src/index.qdoc +++ b/doc/src/index.qdoc @@ -194,6 +194,7 @@ <li><a href="qtxmlpatterns.html">XML Patterns: XQuery & XPath</a></li> <li><a href="phonon-module.html">Phonon Multimedia Framework</a></li> <li><a href="qtscripttools.html">Script Tools Module</a></li> + <li><a href="qml.html">Qt Markup Language</a></li> <li><a href="activeqt.html">ActiveQt Framework</a></li> </ul> </td> diff --git a/doc/src/snippets/code/src_corelib_tools_qeasingcurve.cpp b/doc/src/snippets/code/src_corelib_tools_qeasingcurve.cpp new file mode 100644 index 0000000..65358ea --- /dev/null +++ b/doc/src/snippets/code/src_corelib_tools_qeasingcurve.cpp @@ -0,0 +1,4 @@ +//! [0] +qreal myEasingFunction(qreal progress); +//! [0] + diff --git a/doc/src/statemachine.qdoc b/doc/src/statemachine.qdoc new file mode 100644 index 0000000..c79839f --- /dev/null +++ b/doc/src/statemachine.qdoc @@ -0,0 +1,272 @@ +/**************************************************************************** +** +** Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the $MODULE$ of the Qt Toolkit. +** +** $TROLLTECH_DUAL_LICENSE$ +** +****************************************************************************/ + +/*! + \page statemachine-api.html + \title The State Machine Framework + \brief An overview of the State Machine framework for constructing and executing state graphs. + + \tableofcontents + + The State Machine framework provides classes for creating and executing + state graphs. The concepts and notation are based on those from Harel's + \l{Statecharts: A visual formalism for complex systems}{Statecharts}, which + is also the basis of UML state diagrams. The semantics of state machine + execution are based on \l{State Chart XML: State Machine Notation for + Control Abstraction}{State Chart XML (SCXML)}. + + Statecharts provide a graphical way of modeling how a system reacts to + stimuli. This is done by defining the possible \e states that the system can + be in, and how the system can move from one state to another (\e transitions + between states). A key characteristic of event-driven systems (such as Qt + applications) is that behavior often depends not only on the last or current + event, but also the events that preceded it. With statecharts, this + information is easy to express. + + The State Machine framework provides an API and execution model that can be + used to effectively embed the elements and semantics of statecharts in Qt + applications. The framework integrates tightly with Qt's existing event + system and meta-object system; for example, transitions between states can + be triggered by signals, and states can be configured to set properties and + invoke methods on QObjects. + + \section1 A Simple State Machine + + To demonstrate the core functionality of the State Machine API, let's look + at a small example: A state machine with three states, \c s1, \c s2 and \c + s3. The state machine is controlled by a single QPushButton; when the button + is clicked, the machine transitions to another state. Initially, the state + machine is in state \c s1. The statechart for this machine is as follows: + + \img statemachine-button.png + \omit + \caption This is a caption + \endomit + + The following snippet shows the code needed to create such a state machine. + + \code + QStateMachine machine; + QState *s1 = new QState(); + QState *s2 = new QState(); + QState *s3 = new QState(); + + s1->addTransition(button, SIGNAL(clicked()), s2); + s2->addTransition(button, SIGNAL(clicked()), s3); + s3->addTransition(button, SIGNAL(clicked()), s1); + + machine.addState(s1); + machine.addState(s2); + machine.addState(s3); + machine.setInitialState(s1); + + machine.start(); + \endcode + + Once the state machine has been set up, you need to start it by calling + QStateMachine::start(). The state machine executes asynchronously, i.e. it + becomes part of your application's event loop. + + The above state machine is perfectly fine, but it doesn't \e do anything; it + merely transitions from one state to another. The + QState::setPropertyOnEntry() function can be used to have a state set a + property of a QObject when the state is entered. In the following snippet, + the value that should be assigned to a QLabel's text property is specified + for each state: + + \code + s1->setPropertyOnEntry(label, "text", "In state s1"); + s2->setPropertyOnEntry(label, "text", "In state s2"); + s3->setPropertyOnEntry(label, "text", "In state s3"); + \endcode + + When any of the states is entered, the label's text will be changed + accordingly. + + The QState::invokeMethodOnEntry() function can be used to have a state + invoke a method (a slot) of a QObject when the state is entered. In the + following snippet, the button's showMaximized() slot will be called when + state \c s3 is entered: + + \code + s2->invokeMethodOnEntry(button, "showMaximized"); + \endcode + + \section1 Sharing Transitions By Grouping States + + The state machine defined in the previous section never finishes. In order + for a state machine to be able to finish, it needs to have a top-level \e + final state. When the state machine enters a top-level final state, the + machine will emit the finished() signal and halt. + + Assume we wanted the user to be able to quit the application at any time by + clicking a Quit button. In order to achieve this, we need to create a final + state and make it the target of a transition associated with the Quit + button's clicked() signal. We could add a transition from each of \c s1, \c + s2 and \c s3; however, this seems redundant, and one would also have to + remember to add such a transition from every new state that is added in the + future. + + We can achieve the same behavior (namely that clicking the Quit button quits + the state machine, regardless of which state the state machine is in) by + grouping states \c s1, \c s2 and \c s3. This is done by creating a new + top-level state and making the three original states children of the new + state. The following diagram shows the new state machine. + + \img statemachine-button-nested.png + \omit + \caption This is a caption + \endomit + + The three original states have been renamed \c s11, \c s12 and \c s13 to + reflect that they are now children of the new top-level state, \c s1. Child + states implicitly inherit the transitions of their parent state. This means + it is now sufficient to add a single transition from \c s1 to the final + state \c s2. New states added to \c s1 will also automatically inherit this + transition. + + All that's needed to group states is to specify the proper parent when the + state is created. You also need to specify which of the child states is the + initial one (i.e. which child state the state machine should enter when the + parent state is the target of a transition). + + \code + QState *s1 = new QState(); + QState *s11 = new QState(s1); + QState *s12 = new QState(s1); + QState *s13 = new QState(s1); + s1->setInitialState(s11); + machine.addState(s1); + \endcode + + \code + QFinalState *s2 = new QFinalState(); + s1->addTransition(quitButton, SIGNAL(clicked()), s2); + machine.addState(s2); + + QObject::connect(&machine, SIGNAL(finished()), QApplication::instance(), SLOT(quit())); + \endcode + + In this case we want the application to quit when the state machine is + finished, so the machine's finished() signal is connected to the + application's quit() slot. + + A child state can override an inherited transition. For example, the + following code adds a transition that effectively causes the Quit button to + be ignored when the state machine is in state \c s12. + + \code + s12>addTransition(quitButton, SIGNAL(clicked()), s12); + \endcode + + \section1 Using History States to Save and Restore the Current State + + Imagine that we wanted to add an "interrupt" mechanism to the example + discussed in the previous section; the user should be able to click a button + to have the state machine perform some non-related task, after which the + state machine should resume whatever it was doing before (i.e. return to the + old state, which is one of \c s11, \c s12 and \c s13 in this case). + + Such behavior can easily be modeled using \e{history states}. A history + state (QHistoryState object) is a pseudo-state that represents the child + state that the parent state was in the last time the parent state was + exited. + + A history state is created as a child of the state for which we wish to + record the current child state; when the state machine detects the presence + of such a state at runtime, it automatically records the current (real) + child state when the parent state is exited. A transition to the history + state is in fact a transition to the child state that the state machine had + previously saved; the state machine automatically "forwards" the transition + to the real child state. + + The following diagram shows the state machine after the interrupt mechanism + has been added. + + \img statemachine-button-history.png + \omit + \caption This is a caption + \endomit + + The following code shows how it can be implemented; in this example we + simply display a message box when \c s3 is entered, then immediately return + to the previous child state of \c s1 via the history state. + + \code + QHistoryState *s1h = s1->addHistoryState(); + + QState *s3 = new QState(); + s3->setPropertyOnEntry(label, "text", "In s3"); + QMessageBox mbox; + mbox.addButton(QMessageBox::Ok); + mbox.setText("Interrupted!"); + mbox.setIcon(QMessageBox::Information); + s3->invokeMethodOnEntry(&mbox, "exec"); + s3->addTransition(s1h); + machine.addState(s3); + + s1->addTransition(interruptButton, SIGNAL(clicked()), s3); + \endcode + + \section1 Using Parallel States to Avoid a Combinatorial Explosion of States + + Assume that you wanted to model a set of mutually exclusive properties of a + car in a single state machine. Let's say the properties we are interested in + are Clean vs Dirty, and Moving vs Not moving. It would take four mutually + exclusive states and eight transitions to be able to represent and freely + move between all possible combinations. + + \img statemachine-nonparallel.png + \omit + \caption This is a caption + \endomit + + If we added a third property (say, Red vs Blue), the total number of states + would double, to eight; and if we added a fourth property (say, Enclosed vs + Convertible), the total number of states would double again, to 16. + + Using parallel states, the total number of states and transitions grows + linearly as we add more properties, instead of exponentially. Furthermore, + states can be added to or removed from the parallel state without affecting + any of their sibling states. + + \img statemachine-parallel.png + \omit + \caption This is a caption + \endomit + + To create a parallel state group, pass QState::ParallelStateGroup to the + QState constructor. + + \code + QState *s1 = new QState(QState::ParallelStateGroup); + // s11 and s12 will be entered in parallel + QState *s11 = new QState(s1); + QState *s12 = new QState(s1); + \endcode + + \section1 Detecting that a Composite State has Finished + + A child state can be final; when a final child state is entered, a + QStateFinishedEvent is generated for the parent state. You can use the + QStateFinishedTransition class to trigger a transition based on this event. + + \img statemachine-finished.png + \omit + \caption This is a caption + \endomit + + This is useful when you want to hide the internal details of a state; + i.e. the only thing the outside world should be able to do is enter the + state, and get a notification when the state has finished (i.e. when a final + child state has been entered). + + */ |
