| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** 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 The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/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: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \page qml-codingconventions.html |
| \title QML Coding Conventions |
| \brief code style convention |
| |
| This document contains the QML coding conventions that we follow in our documentation and examples and recommend that others follow. |
| |
| \section1 QML Object Declarations |
| |
| Throughout our documentation and examples, \l{QML Object Attributes}{QML object attributes} 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 qmlapp/codingconventions/photo.qml 0 |
| |
| |
| \section1 Grouped Properties |
| |
| If using multiple properties from a group of properties, |
| consider using \e {group notation} instead of \e {dot notation} if it |
| improves readability. |
| |
| For example, this: |
| |
| \snippet qmlapp/codingconventions/dotproperties.qml 0 |
| |
| could be written like this: |
| |
| \snippet qmlapp/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 qmlapp/codingconventions/lists.qml 0 |
| |
| we will write this: |
| |
| \snippet qmlapp/codingconventions/lists.qml 1 |
| |
| |
| \section1 JavaScript Code |
| |
| If the script is a single expression, we recommend writing it inline: |
| |
| \snippet qmlapp/codingconventions/javascript.qml 0 |
| |
| If the script is only a couple of lines long, we generally use a block: |
| |
| \snippet qmlapp/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 qmlapp/codingconventions/javascript.qml 2 |
| |
| For long scripts, we will put the functions in their own JavaScript file and import it like this: |
| |
| \snippet qmlapp/codingconventions/javascript-imports.qml 0 |
| |
| If the code is longer than one line and hence within a block, |
| we use semicolons to indicate the end of each statement: |
| |
| \snippet qmlapp/codingconventions/javascript-semicolons.qml 0 |
| |
| \section1 Related Information |
| |
| \list |
| \li \l {Best Practices for QML and Qt Quick} |
| \endlist |
| |
| */ |