src/qml/doc/src/qmlfunctions.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 /*!
  29   \macro QML_DECLARE_TYPE()
  30   \relates QQmlEngine
  31
  32   Equivalent to \c Q_DECLARE_METATYPE(TYPE *) and \c Q_DECLARE_METATYPE(QQmlListProperty<TYPE>)
  33
  34   #include <QtQml> to use this macro.
  35 */
  36
  37 /*!
  38   \macro QML_DECLARE_TYPEINFO(Type,Flags)
  39   \relates QQmlEngine
  40
  41   Declares additional properties of the given \a Type as described by the
  42   specified \a Flags.
  43
  44   Current the only supported type info is \c QML_HAS_ATTACHED_PROPERTIES which
  45   declares that the \a Type supports \l {Attached Properties}.
  46
  47   #include <QtQml> to use this macro.
  48 */
  49
  50
  51 /*!
  52   \fn int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
  53   \relates QQmlEngine
  54
  55   This template function registers the C++ type in the QML system with
  56   the name \a qmlName, in the library imported from \a uri having the
  57   version number composed from \a versionMajor and \a versionMinor.
  58
  59   Returns the QML type id.
  60
  61   There are two forms of this template function:
  62
  63   \code
  64   template<typename T>
  65   int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);
  66
  67   template<typename T, int metaObjectRevision>
  68   int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);
  69   \endcode
  70
  71   The former is the standard form which registers the type \e T as a new type.
  72   The latter allows a particular revision of a class to be registered in
  73   a specified version (see \l {QML Type Versioning}).
  74
  75
  76   For example, this registers a C++ class \c MySliderItem as a QML type
  77   named \c Slider for version 1.0 of a \l{QML Modules}{module} called
  78   "com.mycompany.qmlcomponents":
  79
  80   \code
  81   #include <QtQml>
  82
  83   ...
  84
  85   qmlRegisterType<MySliderItem>("com.mycompany.qmlcomponents", 1, 0, "Slider");
  86   \endcode
  87
  88   Once this is registered, the type can be used in QML by importing the
  89   specified module name and version number:
  90
  91   \qml
  92   import com.mycompany.qmlcomponents 1.0
  93
  94   Slider {
  95       // ...
  96   }
  97   \endqml
  98
  99   Note that it's perfectly reasonable for a library to register types to older versions
 100   than the actual version of the library. Indeed, it is normal for the new library to allow
 101   QML written to previous versions to continue to work, even if more advanced versions of
 102   some of its types are available.
 103 */
 104
 105 /*!
 106   \fn int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor)
 107   \relates QQmlEngine
 108
 109   This template function registers the specified revision of a C++ type in the QML system with
 110   the library imported from \a uri having the version number composed
 111   from \a versionMajor and \a versionMinor.
 112
 113   Returns the QML type id.
 114
 115   \code
 116   template<typename T, int metaObjectRevision>
 117   int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor);
 118   \endcode
 119
 120   This function is typically used to register the revision of a base class to
 121   use for the specified module version (see \l {QML Type Versioning}).
 122 */
 123
 124 /*!
 125   \fn int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message)
 126   \relates QQmlEngine
 127
 128   This template function registers the C++ type in the QML system with
 129   the name \a qmlName, in the library imported from \a uri having the
 130   version number composed from \a versionMajor and \a versionMinor.
 131
 132   While the type has a name and a type, it cannot be created, and the
 133   given error \a message will result if creation is attempted.
 134
 135   This is useful where the type is only intended for providing attached properties or enum values.
 136
 137   Returns the QML type id.
 138
 139   #include <QtQml> to use this function.
 140
 141   \sa qmlRegisterTypeNotAvailable()
 142 */
 143
 144 /*!
 145   \fn int qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message)
 146   \relates QQmlEngine
 147
 148   This function registers a type in the QML system with the name \a qmlName, in the library imported from \a uri having the
 149   version number composed from \a versionMajor and \a versionMinor, but any attempt to instantiate the type
 150   will produce the given error \a message.
 151
 152   Normally, the types exported by a module should be fixed. However, if a C++ type is not available, you should
 153   at least "reserve" the QML type name, and give the user of your module a meaningful error message.
 154
 155   Returns the QML type id.
 156
 157   Example:
 158
 159   \code
 160   #ifdef NO_GAMES_ALLOWED
 161   qmlRegisterTypeNotAvailable("MinehuntCore", 0, 1, "Game", "Get back to work, slacker!");
 162   #else
 163   qmlRegisterType<MinehuntGame>("MinehuntCore", 0, 1, "Game");
 164   #endif
 165   \endcode
 166
 167   This will cause any QML which uses this module and attempts to use the type to produce an error message:
 168   \code
 169   fun.qml: Get back to work, slacker!
 170      Game {
 171      ^
 172   \endcode
 173
 174   Without this, a generic "Game is not a type" message would be given.
 175
 176   #include <QtQml> to use this function.
 177
 178   \sa qmlRegisterUncreatableType()
 179 */
 180
 181 /*!
 182   \fn int qmlRegisterType()
 183   \relates QQmlEngine
 184   \overload
 185
 186   This template function registers the C++ type in the QML
 187   system. Instances of this type cannot be created from the QML
 188   system.
 189
 190   #include <QtQml> to use this function.
 191
 192   Returns the QML type id.
 193 */
 194
 195 /*!
 196   \fn int qmlRegisterInterface(const char *typeName)
 197   \relates QQmlEngine
 198
 199   This template function registers the C++ type in the QML system
 200   under the name \a typeName.
 201
 202   #include <QtQml> to use this function.
 203
 204   Returns the QML type id.
 205 */
 206
 207 /*!
 208    \fn int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QJSValue (*callback)(QQmlEngine *, QJSEngine *))
 209    \relates QQmlEngine
 210
 211    This function may be used to register a module API provider \a callback in a particular \a uri
 212    with a version specified in \a versionMajor and \a versionMinor.
 213
 214    Installing a module API into a uri allows developers to provide arbitrary functionality
 215    (methods and properties) in a namespace that doesn't necessarily contain elements.
 216
 217    A module API may be either a QObject or a QJSValue.  Only one module API provider
 218    may be registered into any given namespace (combination of \a uri, \a versionMajor and \a versionMinor).
 219    This function should be used to register a module API provider function which returns a QJSValue as a module API.
 220
 221    \b{NOTE:} QJSValue module API properties will \b{not} trigger binding re-evaluation if changed.
 222
 223    Usage:
 224    \code
 225    // first, define the module API provider function (callback).
 226    static QJSValue *example_qjsvalue_module_api_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
 227    {
 228        Q_UNUSED(engine)
 229
 230        static int seedValue = 5;
 231        QJSValue example = scriptEngine->newObject();
 232        example.setProperty("someProperty", seedValue++);
 233        return example;
 234    }
 235
 236    // second, register the module API provider with QML by calling this function in an initialization function.
 237    ...
 238    qmlRegisterModuleApi("Qt.example.qjsvalueApi", 1, 0, example_qjsvalue_module_api_provider);
 239    ...
 240    \endcode
 241
 242    In order to use the registered module API in QML, you must import the module API.
 243    \qml
 244    import QtQuick 2.0
 245    import Qt.example.qjsvalueApi 1.0 as ExampleApi
 246    Item {
 247        id: root
 248        property int someValue: ExampleApi.someProperty
 249    }
 250    \endqml
 251   */
 252
 253 /*!
 254    \fn template<typename T> int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QObject *(*callback)(QQmlEngine *, QJSEngine *))
 255    \relates QQmlEngine
 256
 257    This function may be used to register a module API provider \a callback in a particular \a uri
 258    with a version specified in \a versionMajor and \a versionMinor.
 259
 260    Installing a module API into a uri allows developers to provide arbitrary functionality
 261    (methods and properties) in a namespace that doesn't necessarily contain elements.
 262
 263    A module API may be either a QObject or a QJSValue.  Only one module API provider
 264    may be registered into any given namespace (combination of \a uri, \a versionMajor and \a versionMinor).
 265    This function should be used to register a module API provider function which returns a QObject
 266    of the given type T as a module API.
 267
 268    A QObject module API must be imported with a qualifier, and that qualifier may be used as
 269    the target in a \l Connections element or otherwise used as any other element id would.
 270    One exception to this is that a QObject module API property may not be aliased (because the
 271    module API qualifier does not identify an object within the same component as any other item).
 272
 273    \b{NOTE:} A QObject module API instance returned from a module API provider is owned by the QML
 274    engine.  For this reason, the module API provider function should \b{not} be implemented as a
 275    singleton factory.
 276
 277    Usage:
 278    \code
 279    // first, define your QObject which provides the functionality.
 280    class ModuleApiExample : public QObject
 281    {
 282        Q_OBJECT
 283        Q_PROPERTY (int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged)
 284
 285    public:
 286        ModuleApiExample(QObject* parent = 0)
 287            : QObject(parent), m_someProperty(0)
 288        {
 289        }
 290
 291        ~ModuleApiExample() {}
 292
 293        Q_INVOKABLE int doSomething() { setSomeProperty(5); return m_someProperty; }
 294
 295        int someProperty() const { return m_someProperty; }
 296        void setSomeProperty(int val) { m_someProperty = val; emit somePropertyChanged(val); }
 297
 298    signals:
 299        void somePropertyChanged(int newValue);
 300
 301    private:
 302        int m_someProperty;
 303    };
 304
 305    // second, define the module API provider function (callback).
 306    static QObject *example_qobject_module_api_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
 307    {
 308        Q_UNUSED(engine)
 309        Q_UNUSED(scriptEngine)
 310
 311        ModuleApiExample *example = new ModuleApiExample();
 312        return example;
 313    }
 314
 315    // third, register the module API provider with QML by calling this function in an initialization function.
 316    ...
 317    qmlRegisterModuleApi<ModuleApiExample>("Qt.example.qobjectApi", 1, 0, example_qobject_module_api_provider);
 318    ...
 319    \endcode
 320
 321    In order to use the registered module API in QML, you must import the module API.
 322    \qml
 323    import QtQuick 2.0
 324    import Qt.example.qobjectApi 1.0 as ExampleApi
 325    Item {
 326        id: root
 327        property int someValue: ExampleApi.someProperty
 328
 329        Component.onCompleted: {
 330            someValue = ExampleApi.doSomething()
 331        }
 332    }
 333    \endqml
 334   */