diff options
Diffstat (limited to 'src/qml/doc/src/qmllanguageref/typesystem/objecttypes.qdoc')
-rw-r--r-- | src/qml/doc/src/qmllanguageref/typesystem/objecttypes.qdoc | 132 |
1 files changed, 132 insertions, 0 deletions
diff --git a/src/qml/doc/src/qmllanguageref/typesystem/objecttypes.qdoc b/src/qml/doc/src/qmllanguageref/typesystem/objecttypes.qdoc new file mode 100644 index 0000000000..9209ebe68e --- /dev/null +++ b/src/qml/doc/src/qmllanguageref/typesystem/objecttypes.qdoc @@ -0,0 +1,132 @@ +/**************************************************************************** +** +** Copyright (C) 2013 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 qtqml-typesystem-objecttypes.html +\title QML Object Types +\brief describes QML object types and how to create them + + +A QML object type is a type from which a QML object can be instantiated. + +In syntactic terms, a QML object type is one which can be used to declare an +object by specifying the \e{type name} followed by a set of curly braces that +encompasses the attributes of that object. This differs from \e {basic types}, +which cannot be used in the same way. For example, \l Rectangle is a QML object +type: it can be used to create \c Rectangle type objects. This cannot be done +with primitive types such as \c int and \c bool, which are used to hold simple +data types rather than objects. + +Custom QML object types can be defined by creating a .qml file that defines the +type, as discussed in \l {qtqml-documents-definetypes.html} +{Documents as QML object type definitions}, or by defining a QML type from C++ +and registering the type with the QML engine, as discussed in +\l{qtqml-cppintegration-definetypes.html}{Defining QML Types from C++}. + + +\section1 Defining Object Types from QML + + +\section2 Defining Object Types through QML Documents + +Plugin writers and application developers may provide types defined as QML +documents. A QML document, when visible to the QML import system, defines a +type identified by the name of the file minus the file extensions. + +Thus, if a QML document named "MyButton.qml" exists, it provides the definition +of the "MyButton" type, which may be used in a QML application. + +See the documentation about \l{QML Documents} for +information on how to define a QML document, and the syntax of the QML +language. Once you are familiar with the QML language and how to define QML +documents, see the documentation which explains how to +\l{qtqml-documents-definetypes.html} +{define and use your own reusable QML types in QML documents}. + +See \l {Defining Object Types through QML Documents} for more information. + + + +\section2 Defining Anonymous Types with Component + +Another method of creating object types from within QML is to use the \l Component type. +This allows a type to be defined inline within a QML document, instead of using a separate +document in a \c .qml file. + +\qml +Item { + id: root + width: 500; height: 500 + + Component { + id: myComponent + Rectangle { width: 100; height: 100; color: "red" } + } + + Component.onCompleted: { + myComponent.createObject(root) + myComponent.createObject(root, {"x": 200}) + } +} +\endqml + +Here the \c myComponent object essentially defines an anonymous type that can be instantiated +using \l {Component::createObject} to create objects of this anonymous type. + + +Inline components share all +the characteristics of regular top-level components and use the same \c import +list as their containing QML document. + + + +Note that each \l Component object declaration creates its own \e {component scope}. Any +\e id values used and referred to from within a \l Component object declaration must be +unique within that scope, but do not need to be unique within the document within which the +inline component is declared. So, the \l Rectangle declared in the \c myComponent object +declaration could have an \e id of \c root without conflicting with the \c root declared +for the \l Item object in the same document, as these two \e id values are declared within +different component scopes. + +See \l{qtqml-documents-scope.html}{Scope and Naming Resolution} for more details. + + +\section1 Defining Object Types from C++ + +C++ plugin writers and application developers may register types defined in C++ +through API provided by the Qt QML module. There are various registration +functions which each allow different use-cases to be fulfilled. +For more information about those registration functions, and the specifics of +exposing custom C++ types to QML, see the documentation regarding +\l{qtqml-cppintegration-definetypes.html}{Defining QML Types from C++}. + +The QML type-system relies on imports, plugins and extensions being installed +into a known import path. Plugins may be provided by third-party developers +and reused by client application developers. Please see the documentation +about \l{qtqml-modules-topic.html}{QML modules} for more information about +how to create and deploy a QML extension module. + +*/ |