1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the documentation of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** GNU Free Documentation License
10 ** Alternatively, this file may be used under the terms of the GNU Free
11 ** Documentation License version 1.3 as published by the Free Software
12 ** Foundation and appearing in the file included in the packaging of
16 ** Alternatively, this file may be used in accordance with the terms
17 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
28 \page qtqml-typesystem-objecttypes.html
29 \title QML Object Types
30 \brief describes QML object types and how to create them
33 A QML object type is a type from which a QML object can be instantiated.
35 In syntactic terms, a QML object type is one which can be used to declare an
36 object by specifying the \e{type name} followed by a set of curly braces that
37 encompasses the attributes of that object. This differs from \e {basic types},
38 which cannot be used in the same way. For example, \l Rectangle is a QML object
39 type: it can be used to create \c Rectangle type objects. This cannot be done
40 with primitive types such as \c int and \c bool, which are used to hold simple
41 data types rather than objects.
43 Custom QML object types can be defined by creating a .qml file that defines the
44 type, as discussed in \l {qtqml-documents-definetypes.html}
45 {Documents as QML object type definitions}, or by defining a QML type from C++
46 and registering the type with the QML engine, as discussed in
47 \l{qtqml-registercpptypes.html}{Registering C++ Types with the QML Type System}.
50 \section1 Creating Object Types from QML
53 \section2 Creating Object Types from QML Documents
55 Plugin writers and application developers may provide types defined as QML
56 documents. A QML document, when visible to the QML import system, defines a
57 type identified by the name of the file minus the file extensions.
59 Thus, if a QML document named "MyButton.qml" exists, it provides the definition
60 of the "MyButton" type, which may be used in a QML application.
62 See the documentation about \l{QML Documents} for
63 information on how to define a QML document, and the syntax of the QML
64 language. Once you are familiar with the QML language and how to define QML
65 documents, see the documentation which explains how to
66 \l{qtqml-documents-definetypes.html}
67 {define and use your own reusable QML types in QML documents}.
69 See \l {Defining Object Types through QML Documents} for more information.
73 \section2 Creating Anonymous Types with Component
75 Another method of creating object types from within QML is to use the \l Component type.
76 This allows a type to be defined inline within a QML document, instead of using a separate
77 document in a \c .qml file.
82 width: 500; height: 500
86 Rectangle { width: 100; height: 100; color: "red" }
89 Component.onCompleted: {
90 myComponent.createObject(root)
91 myComponent.createObject(root, {"x": 200})
96 Here the \c myComponent object essentially defines an anonymous type that can be instantiated
97 using \l {Component::createObject} to create objects of this anonymous type.
100 Inline components share all
101 the characteristics of regular top-level components and use the same \c import
102 list as their containing QML document.
106 Note that each \l Component object declaration creates its own \e {component scope}. Any
107 \e id values used and referred to from within a \l Component object declaration must be
108 unique within that scope, but do not need to be unique within the document within which the
109 inline component is declared. So, the \l Rectangle declared in the \c myComponent object
110 declaration could have an \e id of \c root without conflicting with the \c root declared
111 for the \l Item object in the same document, as these two \e id values are declared within
112 different component scopes.
114 See \l{qtqml-documents-scope.html}{Scope and Naming Resolution} for more details.
117 \section1 Creating Object Types from C++
119 Plugin writers and application developers may register types defined in C++
120 through API provided by the Qt QML module. There are various registration
121 functions which each allow different use-cases to be fulfilled.
125 \li qmlRegisterUncreatableType
126 \li qmlRegisterExtendedType
127 \li qmlRegisterInterface
128 \li qmlRegisterCustomType
129 \li qmlRegisterModuleApi
132 For more information on this topic, see the documentation regarding
133 \l{qtqml-cppintegration-registercpptypes.html}{Creating QML Object Types from C++}.
135 The QML type-system relies on imports, plugins and extensions being installed
136 into a known import path. Plugins may be provided by third-party developers
137 and reused by client application developers.