From 97ec205d5732cb6e028fccc8b2423a6c0f15734b Mon Sep 17 00:00:00 2001 From: Ian Walters Date: Thu, 23 Apr 2009 13:44:53 +1000 Subject: First draft chapter 1 of tutorial: complete. --- doc/src/images/declarative-removebutton-close.png | Bin 0 -> 3973 bytes doc/src/images/declarative-removebutton-open.png | Bin 0 -> 5413 bytes doc/src/images/declarative-removebutton.png | Bin 0 -> 6725 bytes doc/src/images/declarative-roundrect.png | Bin 0 -> 3058 bytes doc/src/tutorials/declarative.qdoc | 470 +++++++++++++++++++++ doc/src/tutorials/kinetic.qdoc | 446 ------------------- .../1_Drawing_and_animation.qml | 34 +- 7 files changed, 483 insertions(+), 467 deletions(-) create mode 100644 doc/src/images/declarative-removebutton-close.png create mode 100644 doc/src/images/declarative-removebutton-open.png create mode 100644 doc/src/images/declarative-removebutton.png create mode 100644 doc/src/images/declarative-roundrect.png create mode 100644 doc/src/tutorials/declarative.qdoc delete mode 100644 doc/src/tutorials/kinetic.qdoc diff --git a/doc/src/images/declarative-removebutton-close.png b/doc/src/images/declarative-removebutton-close.png new file mode 100644 index 0000000..d73f8e1 Binary files /dev/null and b/doc/src/images/declarative-removebutton-close.png differ diff --git a/doc/src/images/declarative-removebutton-open.png b/doc/src/images/declarative-removebutton-open.png new file mode 100644 index 0000000..b54d797 Binary files /dev/null and b/doc/src/images/declarative-removebutton-open.png differ diff --git a/doc/src/images/declarative-removebutton.png b/doc/src/images/declarative-removebutton.png new file mode 100644 index 0000000..f783e6a Binary files /dev/null and b/doc/src/images/declarative-removebutton.png differ diff --git a/doc/src/images/declarative-roundrect.png b/doc/src/images/declarative-roundrect.png new file mode 100644 index 0000000..607da81 Binary files /dev/null and b/doc/src/images/declarative-roundrect.png differ diff --git a/doc/src/tutorials/declarative.qdoc b/doc/src/tutorials/declarative.qdoc new file mode 100644 index 0000000..be8fad9 --- /dev/null +++ b/doc/src/tutorials/declarative.qdoc @@ -0,0 +1,470 @@ +/**************************************************************************** +** +** 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 tutorials-declarative-contacts.html + \startpage {index.html}{Qt Reference Documentation} + \nextpage {tutorials/declarative/contacts/part1}{Chapter 1} + + \title Declarative UI Tutorial + \ingroup howto + \ingroup tutorials + \brief An introduction to using Qt Declarative UI to put together a + simple animated application. + + \omit + At the time of writing the tutorial Declarative UI was still under + development. It is extremely likely that an update will be required + prior to 4.6 release. + \endomit + + This tutorial gives an introduction to using the Qt Declarative UI + animation framework. + + In this process we will learn about some of the basics of using + Declarative UI, such as + + \list + \o Basic drawing + \o States and Transitions + \o Reuse of components + \o Models and Views + \endlist + + An existing knowledge of Qt is not required. + + The tutorial's source code is located in Qt's + \c examples/declarative/tutorials/contacts directory. + It is split up into a number of sub directories, and within each + sub directory the files are numbered in an order of increasing features. + + The code in this example is not compiled, but interpreted at run time. + This means you should use the duiviewer application provided with + Qt to run the examples. + + \list 1 + \o \l{tutorials/declarative/contacts/part1}{Drawing and Animation} + \o \l{tutorials/declarative/contacts/part2}{Reuse of QML components} + \o \l{tutorials/declarative/contacts/part3}{Models, Views and Delegates} + \o \l{tutorials/declarative/contacts/part4}{Other Tricks} + \endlist +*/ + +/*! + \page tutorials-declarative-contacts-part1.html + \contentspage {Declarative UI Tutorial}{Contents} + \nextpage {tutorials/declarative/contacts/part2}{Chapter 2} + \example tutorials/declarative/contacts/part1 + \title Drawing and Animation + \tableofcontents + + The first part of this tutorial covers basic drawing of elements on the + screen and causing them to animate. The file 1_Drawing_and_Animation.qml + loads and displays each of the five stages of this tutorial in a single + window. For now you don't need to worry about the contents of + 1_Drawing_and_Animation.qml. + + \section1 Drawing + + In this first chapter we will build a button that indicates something + can be removed and asks for confirmation. When clicked it will expand + from a small button with a trash can icon, to a wide button with a + confirm icon on the left, the text "Remove" in the middle, and a + cancel icon on the right. + + \image declarative-removebutton.png + + Because Declarative UI is declarative, you don't pass instructions on + what to paint in a sequential manner as you may be used to. Instead + elements and how they appear on the screen are declared in much the + same was as elements on a web page are declared. + + We will start by drawing a simple red rectangle with rounded corners. + + \image declarative-roundrect.png + + \code + + \endcode + + This is the simplest of QML components. It describes a rectangle with + some simple properties. In QML all components start with a capital + letter, and their properties with lower case letters. Properties + can either be declared as XML attributes or as children of the + component element. The above rectangle could equally be written + + \code + + 30 + 30 + 5 + + \endcode + + The rectangle component is one of the more simple QML components. Apart + from the properties all QML components share, it has the properties + + \list + \o color - The background color of the rectangle + \o tintColor - The overlay color of the rectangle + \o gradientColor - The color at the base of the rectangle to blend upwards + \o pen - The description of how to draw the border of the rectangle + \o radius - The corner radius used to draw rounded rectangles. + \endlist + + \omit + For more information on the Rect element, see: TODO + \endomit + + There are also a number of properties all QML components share. To see + a full description of the base QML item, see {QFxItem}. The rectangle + drawn in the above code uses the properties; + + \list + \o id - An identifier of the component + \o width - the width of the component when drawn + \o height - the height of the component when drawn + \endlist + + All items have properties to handle their position on the screen, size, + clipping, rotation, scale and layout in regards to other elements. In + the current example width and height refer to how large to draw the + rectangle. The identifier allows other components to refer to the + identified component. + + Another important property of a component is its children. All components + have a list of children. When drawing, first any components earlier + siblings are drawn, then the component, then any of the components children. + + \section1 Layout + + The next step of the tutorial adds an image over the rectangle. + + \image declarative-removebutton-close.png + + \code + + + + \endcode + + The trashIcon image is added as a child of the Rectangle. In this case + the tag isn't used because the default property of the + Rect component is its children. Some elements don't often have children + and use some other default component, when this is the case its possible + to explicitly list the sub component as a child as follows: + + \code + + + + + + \endcode + + The Image element allows loading an image file for display. The source + specified is a URL, and in this case refers to a portable network graphics + file in a relative directory to where the QML file was loaded from. + + Also new in this code is the use of anchors. In QML components can either + have their position and size specified explicitly using x, y, width + and height, or they can instead specify the size and position in relation + to elements either parent or sibling elements. The Image component uses + a combination of both styles. It has a fixed size, but specifies its + position to align to the right of its parent and for its vertical center + to align with the vertical center of its parent. The braces "{}" are + used to indicate that the value is not a static value, but instead a + binding to an expression. In this case it binds to the parent + element, which is a special identifier that always refers to the + parent component of a component. The removeButton identifier can + be used interchangeably with parent in this case, however it must + always be a parent or sibling. Because of this its most common to + use the parent identifier as it makes later refactoring of code easier. + + Anchors are most useful when the size of items might change based on + the component state or contents. + + \omit + See TODO for full list of anchor properties. + \endomit + + At this point the initial state of the RemoveButton is complete. A small + rounded rectangle with a trash icon. The component also needs a + description of its open state: + + \image declarative-removebutton-open.png + + This is a wider rectangle with two images and some text. The code to + draw this state of the button could be written as follows: + + \code + + + + + + \endcode + + The rectangle with is now wider by 200 pixels. Also the trashIcon has + been replaced with the confirm state children. Normally we wouldn't + remove the trashIcon when developing an alternate state of the RemoveButton, + however since this is a tutorial its been done so that its easier to + understand the alternate state we are aiming for and how it relates to + transitioning between states. + + We also introduce the Text element, which is used to display read only + text. \omit see {Text} for more information on the text element \endomit + Because we want text to fill the space between the icons, rather than + a fixed with the left and right anchors are specified instead. This + means as the parent removeButton gets wider, so will the text component. + It also means that if we animate a width change on the removeButton, + any bindings, that is the values specified by a braced expression such as + "{parent.left}" will be evaluated and animated as well. + + \section1 Defining States + + When designing a component with multiple states, it should be developed + with the initial state and the changes that would be made specified + as an additional state. Its not possible to add new children to an + element when changing state, only changing the properties of existing + children. This means that all possible child components should be included + in the initial state, and those that should not be visible in the initial + state should have their opacity set to zero. Thus + for the RemoveButton we specify the starting size of the removeButton + and hide any items that should not initially be visible. + + The code snippet below shows what the start of the duel state specification + might look like. + + \code + + + + \endcode + + The code above includes components from both states of the RemoveButton, + but by setting opacity="0" for the cancelIcon it means that the + components of the second state won't be drawn yet. + The base state of a component always has an empty name, however new + states can be added that describe how a component and its children + should be changed. For the RemoveButton there is only one non-base state + required. In this tutorial we will name it the 'opened' state. + + \code + + + + + + + + + + \endcode + + In the opened state the width of the button itself changes from the base + width of 30 to the new width of 230. Also the opacity of the children + are changed so that the trash icon is now hidden and the other elements + are now visible. + + \section1 Changing States + + To trigger the change we will react to the 'clicked' signal of a + MouseRegion component. + + \code + + + + \endcode + + MouseRegion components handle mouse actions within their geometry. This + geometry behaves the same way as painted components, such that children + cover their parents and later siblings will cover earlier siblings and + all the children of the earlier sibling, should they overlap. + + When a component has a signal, such as clicked, the action for the signal + can be specified using on, as is done above. In this + case when the clicked signal is emitted by the MouseRegion component, + a function called toggle() is called. It might also have been written + + \code + onClicked="removeButton.state='opened'" + \endcode + + However in this case we are using a function because it allows multiple + mouse regions to use the same functionality, and also makes it + easier to specify complex behavior in response to a signal. + + The toggle() function is a new function specified as part of the remove + button element. + + \code + + + + \endcode + + Any QML component can have a set of resources specified. One of those + resources is any Script that might be needed. See the + {QtScript Module}{QtScript Module} for more information on how to write + script code in Qt. There are only a couple of additional items to + note when using Script with QML components. The first is that it + is an xml file, that means either CDATA or other forms of escaping + should be used if special characters are needed. For example, + the expression; + + \code + if (a && b) {} + \endcode + + Should either be escaped as: + + \code + if (a && b) {} + \endcode + + or enclosed in a CDATA section as + + \code + + \endcode + + The other item to note is that you can refer to identified QML components + within the script. Hence the function for our RemoveButton will check + if the state is already open to determine what the new state should be. + + We also have added a print function. This isn't required for the button + to function, but is useful for tracking down possible bugs when + working with QML. + + See the file RemoveButton4.qml for the full multi-state specification. + + \section1 Animation + + Currently the RemoveButton is function, but snaps between our two states. + Fortunately making the transition between states smooth is very simple. + We only need one more bit of code at the end of our removeButton component. + + \code + + + + + + \endcode + + All QML components have a transitions property. This describes how + properties of items within the component should change. In this case + we specify that if the x, width or opacity of the removeButton or its + children change due to a change in state, that they should take 200ms + to complete their transition. + + \omit + TODO More on types of animation + \endomit + + In the next chapter we will show how we can use the remove button in + other QML components. +*/ diff --git a/doc/src/tutorials/kinetic.qdoc b/doc/src/tutorials/kinetic.qdoc deleted file mode 100644 index 549161c..0000000 --- a/doc/src/tutorials/kinetic.qdoc +++ /dev/null @@ -1,446 +0,0 @@ -/**************************************************************************** -** -** 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 tutorials-kinetic-contacts.html - \startpage {index.html}{Qt Reference Documentation} - \nextpage {tutorials/kinetic-contacts/part1}{Chapter 1} - - \title Kinetic Contacts application tutorial. - \ingroup howto - \ingroup tutorials - \brief An introduction to using Qt Declarative UI to put together a - simple animated application. - - \omit - At the time of writing the tutorial Declarative UI was still under - development. It is extremely likely that an update will be required - prior to 4.6 release. - \endomit - - This tutorial gives an introduction to using the Qt Declarative UI - animation framework. - - In this process we will learn about some of the basics of using - Declarative UI, such as - - \list - \o Basic drawing - \o States and Transitions - \o Reuse of components - \o Models and Views - \endlist - - An existing knowledge of Qt is not required. - - The tutorial's source code is located in Qt's - \c examples/declarative/tutorials/contacts directory. - It is split up into a number of sub directories, and within each - sub directory the files are numbered in an order of increasing features. - - The code in this example is not compiled, but interpreted at run time. - This means you should use the duiviewer application provided with - Qt to run the examples. - - \list 1 - \o \l{tutorials/declarative/contacts/part1}{Drawing and animation} - \o \l{tutorials/declarative/contacts/part2}{Reuse of QML components} - \o \l{tutorials/declarative/contacts/part3}{Models, Views and Delegates} - \o \l{tutorials/declarative/contacts/part4}{Other Tricks} - \endlist -*/ - -/*! - \page tutorials-declarative-contacts-part1.html - \contentspage {Declarative UI Tutorial}{Contents} - \nextpage {tutorials/declarative/contacts/part2}{Chapter 2} - \example tutorials/declarative/contacts/1_Drawing_and_Animation - \title Declarative UI 1 - Drawing and Animation - - The first part of this tutorial covers basic drawing of elements on the - screen and causing them to animate. The file 1_Drawing_and_Animation.qml - loads and displays each of the five stages of this tutorial in a single - window. For now you don't need to worry about the contents of - 1_Drawing_and_Animation.qml. - - \section1 Drawing - - In this first chapter we will build a button that indicates something - can be removed and asks for confirmation. When clicked it will expand - from a small button with a trash can icon, to a wide button with a - confirm icon on the left, the text "Remove" in the middle, and a - cancel icon on the right. - - Because Declarative UI is declarative, you don't pass instructions on - what to paint in a sequential manner as you may be used to. Instead - elements and how they appear on the screen are declared in much the - same was as elements on a web page are declared. - - \i RemoveButton1.qml - \code - - \endcode - - This is the simplest of QML components. It describes a rectangle with - some simple properties. In QML all components start with a capital - letter, and their properties with lower case letters. Properties - can either be declared as XML attributes or as children of the - component element. The above rectangle could equally be written - - \code - - 30 - 30 - 5 - - \endcode - - The rectangle component is one of the more simple QML components. Apart - from the properties all QML components share, it has the properties - - \list - \o color - The background color of the rectangle - \o tintColor - The overlay color of the rectangle - \o gradientColor - The color at the base of the rectangle to blend upwards - \o pen - The description of how to draw the border of the rectangle - \o radius - The corner radius used to draw rounded rectangles. - \endlist - - \omit - For more information on the Rect element, see: TODO - \endomit - - There are also a number of properties all QML components share. To see - a full description of the base QML item, see {QFxItem}. The rectangle - drawn in the above code uses the properties; - - \list - \o id - An identifier of the component - \o width - the width of the component when drawn - \o height - the height of the component when drawn - \endlist - - All items have properties to handle their position on the screen, size, - clipping, rotation, scale and layout in regards to other elements. In - the current example width and height refer to how large to draw the - rectangle. The identifier allows other components to refer to the - identified component. - - Another important property of a component is its children. All components - have a list of children. When drawing, first any components earlier - siblings are drawn, then the component, then any of the components children. - - The next step of the tutorial adds an image over the rectangle. - - \code - - - - \endcode - - The trashIcon image is added as a child of the Rectangle. In this case - the tag isn't used because the default property of the - Rect component is its children. Some elements don't often have children - and use some other default component, when this is the case its possible - to explicitly list the sub component as a child as follows: - - \code - - - - - - \endcode - - The Image element allows loading an image file for display. The source - specified is a URL, and in this case refers to a portable network graphics - file in a relative directory to where the QML file was loaded from. - - Also new in this code is the use of anchors. In QML components can either - have their position and size specified explicitly using x, y, width - and height, or they can instead specify the size and position in relation - to elements either parent or sibling elements. The Image component uses - a combination of both styles. It has a fixed size, but specifies its - position to align to the right of its parent and for its vertical center - to align with the vertical center of its parent. The braces "{}" are - used to indicate that the value is not a static value, but instead a - binding to an expression. In this case it binds to the parent - element, which is a special identifier that always refers to the - parent component of a component. The removeButton identifier can - be used interchangeably with parent in this case, however it must - always be a parent or sibling. Because of this its most common to - use the parent identifier as it makes later refactoring of code easier. - - Anchors are most useful when the size of items might change based on - the component state or contents. - - \omit - See TODO for full list of anchor properties. - \endomit - - At this point the initial state of the RemoveButton is complete. A small - rounded rectangle with a trash icon. The description of the alternate - state of the button can be written as: - - \code - - - - - - \endcode - - The rectangle with is now wider, by 200 pixels. Also the trashIcon has - been replaced with the confirm state children. Normally we wouldn't - remove the trashIcon when developing an alternate state of the RemoveButton, - however since this is a tutorial its been done so that its easier to - understand the alternate state we are aiming for and how it relates to - transitioning between states. - - We also introduce the Text element, which is used to display read only - text. \omit see {Text} for more information on the text element \endomit - Because we want text to fill the space between the icons, rather than - a fixed with the left and right anchors are specified instead. This - means as the parent removeButton gets wider, so will the text component. - It also means that if we animate a width change on the removeButton, - any bindings, that is the values specified by a braced expression such as - "{parent.left}" will be evaluated and animated as well. - - When designing a component with multiple states, it should be developed - with the initial state and the changes that would be made specified - as a state changed. Because we cannot add children to an element from - a state change we instead start with the children that should be present - and then set their opacity or position such that they won't appear. Thus - for the RemoveButton we specify the starting size of the removeButton - and hide any items that should not initially be visible. - - The code snippet below shows what the start of the duel state specification - might look like. - - \code - - - - \endcode - - Which includes both components, but by setting opacity="0" means the - second components won't be drawn unless their is a state change. - The base state of a component always has an empty name, however new - states can be added that describe how a component and its children - should be changed. For the RemoveButton there is only one non-base state - required. In this tutorial we will name it the 'opened' state. - - \code - - - - - - - - - - \endcode - - In the opened state the width of the button itself changes from the base - width of 30 to the new width of 230. Also the opacity of the children - are changed so that the trash icon is hidden and the other elements - appear. - - To trigger the change we will react to the 'clicked' signal of a - MouseRegion component. - - \code - - - - \endcode - - MouseRegion components handle mouse actions within their geometry. This - geometry behaves the same way as painted components, such that children - cover their parents and later siblings will cover earlier siblings and - all the children of the earlier sibling, should they overlap. - - When a component has a signal, such as clicked, the action for the signal - can be specified using on, as is done above. In this - case when the clicked signal is emitted by the MouseRegion component, - a function called toggle() is called. It might also have been written - - \code - onClicked="removeButton.state='opened'" - \endcode - - However in this case we are using a function because it allows multiple - mouse regions to use the same functionality, and also makes it - easier to specify complex behavior in response to a signal. - - The toggle() function is a new function specified as part of the remove - button element. - - \code - - - - \endcode - - Any QML component can have a set of resources specified. One of those - resources is any Script that might be needed. See the - {QtScript Module}{QtScript Module} for more information on how to write - script code in Qt. There are only a couple of additional items to - note when using Script with QML components. The first is that it - is an xml file, that means either CDATA or other forms of escaping - should be used if special characters are needed. For example, - the expression; - - \code - if (a && b) {} - \endcode - - Should either be escaped as: - - \code - if (a && b) {} - \endcode - - or enclosed in a CDATA section as - - \code - - \endcode - - The other item to note is that you can refer to identified QML components - within the script. Hence the function for our RemoveButton will check - if the state is already open to determine what the new state should be. - - We also have added a print function. This isn't required for the button - to function, but is useful for tracking down possible bugs when - working with QML. - - See the file RemoveButton4.qml for the full multi-state specification. - - \section Animation - - Currently the RemoveButton is function, but snaps between our two states. - Fortunately making the transition between states smooth is very simple. - We only need one more bit of code at the end of our removeButton component. - - \code - - - - - - \endcode - - All QML components have a transitions property. This describes how - properties of items within the component should change. In this case - we specify that if the x, width or opacity of the removeButton or its - children change due to a change in state, that they should take 200ms - to complete their transition. - - \omit TODO More on types of animation - - In the next chapter we will show how we can use the remove button in - other QML components. -*/ diff --git a/examples/declarative/tutorials/contacts/1_Drawing_and_Animation/1_Drawing_and_animation.qml b/examples/declarative/tutorials/contacts/1_Drawing_and_Animation/1_Drawing_and_animation.qml index 06c9f5a..181ee44 100644 --- a/examples/declarative/tutorials/contacts/1_Drawing_and_Animation/1_Drawing_and_animation.qml +++ b/examples/declarative/tutorials/contacts/1_Drawing_and_Animation/1_Drawing_and_animation.qml @@ -1,22 +1,14 @@ - - - - - - + + + Rectangle Component + + Closed Remove Item Button + + Open Remove Item Button + + State Based Button + + Animated Button + + -- cgit v0.12