diff options
9 files changed, 308 insertions, 40 deletions
diff --git a/doc/src/declarative/codingconventions.qdoc b/doc/src/declarative/codingconventions.qdoc new file mode 100644 index 0000000..ad2480f --- /dev/null +++ b/doc/src/declarative/codingconventions.qdoc @@ -0,0 +1,131 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE: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 Technology Preview License Agreement accompanying +** this package. +** +** 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.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page codingconventions.html +\title QML Coding Conventions + +This document contains the QML coding conventions that we follow in our documentation and examples and recommend that others follow. + +This page assumes that you are already familiar with the QML language. +If you need an introduction to the language, please read \l {Introduction to the QML language}{the QML introduction} first. + + +\section1 QML objects + +Through our documentation and examples, QML objects are always structured in the following order: + +\list +\o id +\o property declarations +\o signal declarations +\o javascript functions +\o object properties +\o child objects +\o states +\o transitions +\endlist + +For better lisibility, we separate these different parts with an empty line. + + +For example, a hypothetical \e photo QML object would look like this: + +\snippet doc/src/snippets/declarative/codingconventions/photo.qml 0 + + +\section1 Grouped properties + +If using multiple properties from a group of properties, +we use the \e {group notation} rather than the \e {dot notation} to improve lisibility. + +For example, this: + +\snippet doc/src/snippets/declarative/codingconventions/dotproperties.qml 0 + +can be written like this: + +\snippet doc/src/snippets/declarative/codingconventions/dotproperties.qml 1 + + +\section1 Lists + +If a list contains only one element, we generally omit the square brackets. + +For example, it is very common for a component to only have one state. + +In this case, instead of: + +\snippet doc/src/snippets/declarative/codingconventions/lists.qml 0 + +we will write this: + +\snippet doc/src/snippets/declarative/codingconventions/lists.qml 1 + + +\section1 Javascript + +If the script is a single expression, we recommend writing it inline: + +\snippet doc/src/snippets/declarative/codingconventions/javascript.qml 0 + +If the script is only a couple of lines long, we generally use a block: + +\snippet doc/src/snippets/declarative/codingconventions/javascript.qml 1 + +If the script is more than a couple of lines long or can be used by different objects, we recommend creating a function and calling it like this: + +\snippet doc/src/snippets/declarative/codingconventions/javascript.qml 2 + +For long scripts, we will put the functions in their own javascript file and import it like this: + +\snippet doc/src/snippets/declarative/codingconventions/javascript-imports.qml 0 + +*/ + + + + + + + + + diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc index f310484..a4f4bc7 100644 --- a/doc/src/declarative/declarativeui.qdoc +++ b/doc/src/declarative/declarativeui.qdoc @@ -47,10 +47,10 @@ highly dynamic, custom user interfaces. Qt Declarative UI provides a declarative framework for building highly dynamic, custom -user interfaces. Declarative UI helps programmers and designers collaborate to build -the animation rich, fluid user interfaces that are becoming common in portable -consumer devices, such as mobile phones, media players, set-top boxes and netbooks. -The Qt Declarative module provides an engine for interpreting the declarative QML +user interfaces. Declarative UI helps programmers and designers collaborate to build +the animation rich, fluid user interfaces that are becoming common in portable +consumer devices, such as mobile phones, media players, set-top boxes and netbooks. +The Qt Declarative module provides an engine for interpreting the declarative QML language, and a rich set of \l {QML Elements}{QML elements} that can be used from QML. @@ -106,5 +106,6 @@ completely new applications. QML is fully \l {Extending QML in C++}{extensible \o \l {QML Security} \o \l {QtDeclarative Module} \o \l {Debugging QML} +\o \l {QML Coding Conventions} \endlist */ diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc index 3544bc9..d2926f7 100644 --- a/doc/src/declarative/javascriptblocks.qdoc +++ b/doc/src/declarative/javascriptblocks.qdoc @@ -41,25 +41,25 @@ /*! \page qdeclarativejavascript.html -\title Integrating JavaScript +\title Integrating JavaScript -QML encourages building UIs declaratively, using \l {Property Binding} and the +QML encourages building UIs declaratively, using \l {Property Binding} and the composition of existing \l {QML Elements}. To allow the implementation of more advanced behavior, QML integrates tightly with imperative JavaScript code. The JavaScript environment provided by QML is stricter than that in a webbrowser. In QML you cannot add, or modify, members of the JavaScript global object. It is possible to do this accidentally by using a variable without declaring it. In -QML this will throw an exception, so all local variables should be explicitly +QML this will throw an exception, so all local variables should be explicitly declared. -In addition to the standard JavaScript properties, the \l {QML Global Object} +In addition to the standard JavaScript properties, the \l {QML Global Object} includes a number of helper methods that simplify building UIs and interacting with the QML environment. \section1 Inline JavaScript -Small JavaScript functions can be written inline with other QML declarations. +Small JavaScript functions can be written inline with other QML declarations. These inline functions are added as methods to the QML element that contains them. @@ -73,21 +73,21 @@ Item { return a * factorial(a - 1); } - MouseRegion { + MouseArea { anchors.fill: parent onClicked: print(factorial(10)) } } \endcode -As methods, inline functions on the root element in a QML component can be +As methods, inline functions on the root element in a QML component can be invoked by callers outside the component. If this is not desired, the method can be added to a non-root element or, preferably, written in an external JavaScript file. \section1 Separate JavaScript files -Large blocks of JavaScript should be written in separate files. Like element +Large blocks of JavaScript should be written in separate files. Like element types, external JavaScript files are \c {import}'ed into QML files. The \c {factorial()} method used in the \l {Inline JavaScript} section could @@ -96,35 +96,35 @@ be refactored into an external file, and accessed like this. \code import "factorial.js" as MathFunctions Item { - MouseRegion { + MouseArea { anchors.fill: parent onClicked: print(MathFunctions.factorial(10)) } } \endcode -Both relative and absolute JavaScript URLs can be imported. In the case of a -relative URL, the location is resolved relative to the location of the -\l {QML Document} that contains the import. If the script file is not accessible, -an error will occur. If the JavaScript needs to be fetched from a network -resource, the QML document will remain in the -\l {QDeclarativeComponent::status()}{waiting state} until the script has been +Both relative and absolute JavaScript URLs can be imported. In the case of a +relative URL, the location is resolved relative to the location of the +\l {QML Document} that contains the import. If the script file is not accessible, +an error will occur. If the JavaScript needs to be fetched from a network +resource, the QML document will remain in the +\l {QDeclarativeComponent::status()}{waiting state} until the script has been downloaded. -Imported JavaScript files are always qualified using the "as" keyword. The +Imported JavaScript files are always qualified using the "as" keyword. The qualifier for JavaScript files must be unique, so there is always a one-to-one mapping between qualifiers and JavaScript files. \section2 Code-Behind Implementation Files -Most JavaScript files imported into a QML file are stateful, logic implementations -for the QML file importing them. In these cases, for QML component instances to -behave correctly each instance requires a separate copy of the JavaScript objects +Most JavaScript files imported into a QML file are stateful, logic implementations +for the QML file importing them. In these cases, for QML component instances to +behave correctly each instance requires a separate copy of the JavaScript objects and state. The default behavior when importing JavaScript files is to provide a unique, isolated -copy for each QML component instance. The code runs in the same scope as the QML -component instance and consequently can can access and manipulate the objects and +copy for each QML component instance. The code runs in the same scope as the QML +component instance and consequently can can access and manipulate the objects and properties declared. \section2 Stateless JavaScript libraries @@ -133,8 +133,8 @@ Some JavaScript files act more like libraries - they provide a set of stateless helper functions that take input and compute output, but never manipulate QML component instances directly. -As it would be wasteful for each QML component instance to have a unique copy of -these libraries, the JavaScript programmer can indicate a particular file is a +As it would be wasteful for each QML component instance to have a unique copy of +these libraries, the JavaScript programmer can indicate a particular file is a stateless library through the use of a pragma, as shown in the following example. \code @@ -161,7 +161,7 @@ parameters. It is occasionally necessary to run some imperative code at application (or component instance) "startup". While it is tempting to just include the startup script as \e {global code} in an external script file, this can have severe limitations -as the QML environment may not have been fully established. For example, some objects +as the QML environment may not have been fully established. For example, some objects might not have been created or some \l {Property Binding}s may not have been run. \l {QML JavaScript Restrictions} covers the exact limitations of global script code. @@ -181,25 +181,25 @@ Rectangle { } \endcode -Any element in a QML file - including nested elements and nested QML component -instances - can use this attached property. If there is more than one onCompleted +Any element in a QML file - including nested elements and nested QML component +instances - can use this attached property. If there is more than one onCompleted handler to execute at startup, they are run sequentially in an undefined order. -\section1 QML JavaScript Restrictions +\section1 QML JavaScript Restrictions QML executes standard JavaScript code, with the following restrictions: \list \o JavaScript code cannot modify the global object. -In QML, the global object is constant - existing properties cannot be modified or +In QML, the global object is constant - existing properties cannot be modified or deleted, and no new properties may be created. -Most JavaScript programs do not intentionally modify the global object. However, +Most JavaScript programs do not intentionally modify the global object. However, JavaScript's automatic creation of undeclared variables is an implicit modification of the global object, and is prohibited in QML. -Assuming that the \c a variable does not exist in the scope chain, the following code +Assuming that the \c a variable does not exist in the scope chain, the following code is illegal in QML. \code @@ -217,18 +217,18 @@ for (var ii = 1; ii < 10; ++ii) a = a * ii; console.log("Result: " + a); \endcode -Any attempt to modify the global object - either implicitly or explicitly - will -cause an exception. If uncaught, this will result in an warning being printed, +Any attempt to modify the global object - either implicitly or explicitly - will +cause an exception. If uncaught, this will result in an warning being printed, that includes the file and line number of the offending code. \o Global code is run in a reduced scope During startup, if a QML file includes an external JavaScript file with "global" code, it is executed in a scope that contains only the external file itself and -the global object. That is, it will not have access to the QML objects and +the global object. That is, it will not have access to the QML objects and properties it \l {QML Scope}{normally would}. -Global code that only accesses script local variable is permitted. This is an +Global code that only accesses script local variable is permitted. This is an example of valid global code. \code @@ -242,8 +242,8 @@ Global code that accesses QML objects will not run correctly. var initialPosition = { rootObject.x, rootObject.y } \endcode -This restriction exists as the QML environment is not yet fully established. -To run code after the environment setup has completed, refer to +This restriction exists as the QML environment is not yet fully established. +To run code after the environment setup has completed, refer to \l {Running JavaScript at Startup}. \endlist diff --git a/doc/src/snippets/declarative/codingconventions/dotproperties.qml b/doc/src/snippets/declarative/codingconventions/dotproperties.qml new file mode 100644 index 0000000..211cac1 --- /dev/null +++ b/doc/src/snippets/declarative/codingconventions/dotproperties.qml @@ -0,0 +1,28 @@ +import Qt 4.6 + +Item { + +//! [0] +Rectangle { + anchors.left: parent.left; anchors.top: parent.top; anchors.right: parent.right; anchors.leftMargin: 20 +} + +Text { + text: "hello" + font.bold: true; font.italic: true; font.pixelSize: 20; font.capitalization: Font.AllUppercase +} + +//! [0] + +//! [1] +Rectangle { + anchors { left: parent.left; top: parent.top; right: parent.right; leftMargin: 20 } +} + +Text { + text: "hello" + font { bold: true; italic: true; pixelSize: 20; capitalization: Font.AllUppercase } +} +//! [1] + +} diff --git a/doc/src/snippets/declarative/codingconventions/javascript-imports.qml b/doc/src/snippets/declarative/codingconventions/javascript-imports.qml new file mode 100644 index 0000000..a216e1c --- /dev/null +++ b/doc/src/snippets/declarative/codingconventions/javascript-imports.qml @@ -0,0 +1,7 @@ +import Qt 4.6 + +//![0] +import "myscript.js" as Script + +Rectangle { color: "blue"; width: Script.calculateWidth(parent) } +//![0] diff --git a/doc/src/snippets/declarative/codingconventions/javascript.qml b/doc/src/snippets/declarative/codingconventions/javascript.qml new file mode 100644 index 0000000..ccb299b --- /dev/null +++ b/doc/src/snippets/declarative/codingconventions/javascript.qml @@ -0,0 +1,33 @@ +import Qt 4.6 + +Rectangle { + +//![0] +Rectangle { color: "blue"; width: parent.width / 3 } +//![0] + +//![1] +Rectangle { + color: "blue" + width: { + var w = parent.width / 3 + console.debug(w) + return w + } +} +//![1] + +//![2] +function calculateWidth(object) +{ + var w = object.width / 3 + // ... + // more javascript code + // ... + console.debug(w) + return w +} + +Rectangle { color: "blue"; width: calculateWidth(parent) } +//![2] +} diff --git a/doc/src/snippets/declarative/codingconventions/lists.qml b/doc/src/snippets/declarative/codingconventions/lists.qml new file mode 100644 index 0000000..a08b61c --- /dev/null +++ b/doc/src/snippets/declarative/codingconventions/lists.qml @@ -0,0 +1,22 @@ +import Qt 4.6 + +Item { + Item { +//! [0] +states: [ + State { + name: "open" + PropertyChanges { target: container; width: 200 } + } +] +//! [0] + } + Item { +//! [1] + states: State { + name: "open" + PropertyChanges { target: container; width: 200 } +} +//! [1] + } +} diff --git a/doc/src/snippets/declarative/codingconventions/myscript.js b/doc/src/snippets/declarative/codingconventions/myscript.js new file mode 100644 index 0000000..cfa6462 --- /dev/null +++ b/doc/src/snippets/declarative/codingconventions/myscript.js @@ -0,0 +1,9 @@ +function calculateWidth(parent) +{ + var w = parent.width / 3 + // ... + // more javascript code + // ... + console.debug(w) + return w +} diff --git a/doc/src/snippets/declarative/codingconventions/photo.qml b/doc/src/snippets/declarative/codingconventions/photo.qml new file mode 100644 index 0000000..3a59e1f --- /dev/null +++ b/doc/src/snippets/declarative/codingconventions/photo.qml @@ -0,0 +1,37 @@ +import Qt 4.6 + +//! [0] +Rectangle { + id: photo // id on the first line makes it easy to find an object + + property bool thumbnail: false // property declarations + property alias image: photoImage.source + + signal clicked // signal declarations + + function doSomething(x) { // javascript functions + return x + photoImage.width + } + + x: 20; y: 20; width: 200; height: 150 // object properties + color: "gray" // try to group related properties together + + Rectangle { // child objects + id: border + anchors.centerIn: parent; color: "white" + + Image { id: photoImage; anchors.centerIn: parent } + } + + states: State { // states + name: "selected" + PropertyChanges { target: border; color: "red" } + } + + transitions: Transition { // transitions + from: ""; to: "selected" + ColorAnimation { target: border; duration: 200 } + } +} +//! [0] + |