1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qml-coding-conventions.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
\li id
\li property declarations
\li signal declarations
\li JavaScript functions
\li object properties
\li child objects
\li states
\li transitions
\endlist
For better readability, 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 readability.
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 Private Properties
QML and JavaScript do not enforce private properties like C++. There is a need
to hide these private properties, for example, when the properties are part of
the implementation. As a convention, private properties begin with two
\e underscore characters. For example, \c __area, is a property that is
accessible but is not meant for public use. Note that QML and JavaScript will
grant the user access to these properties.
\snippet doc/src/snippets/declarative/codingconventions/private.qml 0
\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 Code
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
*/
|
