objecttypes.qdoc

Go to the documentation of this file.

// Copyright (C) 2017 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\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 {value 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++}.
Note that in both cases, the type name must begin with an uppercase letter in
order to be declared as a QML object type in a QML file.
 
For more information about C++ and the different QML integration methods,
see the
\l {Overview - QML and C++ Integration} {C++ and QML integration overview} page.
 
There are two built-in object types that can be used without importing any other
modules: \l{QtObject} is the base type of all object types. \l{Component} can be
used to define new object types inline in QML documents.
 
\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.
 
*/