src/qml/doc/src/typesystem/objecttypes.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   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
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27 /*!
  28 \page qtqml-typesystem-objecttypes.html
  29 \title QML Object Types
  30 \brief describes QML object types and how to create them
  31
  32
  33 A QML object type is a type from which a QML object can be instantiated.
  34
  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.
  42
  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}.
  48
  49
  50 \section1 Creating Object Types from QML
  51
  52
  53 \section2 Creating Object Types from QML Documents
  54
  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.
  58
  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.
  61
  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}.
  68
  69 See \l {Defining Object Types through QML Documents} for more information.
  70
  71
  72
  73 \section2 Creating Anonymous Types with Component
  74
  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.
  78
  79 \qml
  80 Item {
  81     id: root
  82     width: 500; height: 500
  83
  84     Component {
  85         id: myComponent
  86         Rectangle { width: 100; height: 100; color: "red" }
  87     }
  88
  89     Component.onCompleted: {
  90         myComponent.createObject(root)
  91         myComponent.createObject(root, {"x": 200})
  92     }
  93 }
  94 \endqml
  95
  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.
  98
  99
 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.
 103
 104
 105
 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.
 113
 114 See \l{qtqml-documents-scope.html}{Scope and Naming Resolution} for more details.
 115
 116
 117 \section1 Creating Object Types from C++
 118
 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.
 122
 123 \list
 124 \li qmlRegisterType
 125 \li qmlRegisterUncreatableType
 126 \li qmlRegisterExtendedType
 127 \li qmlRegisterInterface
 128 \li qmlRegisterCustomType
 129 \li qmlRegisterModuleApi
 130 \endlist
 131
 132 For more information on this topic, see the documentation regarding
 133 \l{qtqml-cppintegration-registercpptypes.html}{Creating QML Object Types from C++}.
 134
 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.
 138
 139 */