src/declarative/qml/qdeclarative.h

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the QtDeclarative module of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** GNU Lesser General Public License Usage
  11 ** This file may be used under the terms of the GNU Lesser General Public
  12 ** License version 2.1 as published by the Free Software Foundation and
  13 ** appearing in the file LICENSE.LGPL included in the packaging of this
  14 ** file. Please review the following information to ensure the GNU Lesser
  15 ** General Public License version 2.1 requirements will be met:
  16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  17 **
  18 ** In addition, as a special exception, Nokia gives you certain additional
  19 ** rights. These rights are described in the Nokia Qt LGPL Exception
  20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  21 **
  22 ** GNU General Public License Usage
  23 ** Alternatively, this file may be used under the terms of the GNU General
  24 ** Public License version 3.0 as published by the Free Software Foundation
  25 ** and appearing in the file LICENSE.GPL included in the packaging of this
  26 ** file. Please review the following information to ensure the GNU General
  27 ** Public License version 3.0 requirements will be met:
  28 ** http://www.gnu.org/copyleft/gpl.html.
  29 **
  30 ** Other Usage
  31 ** Alternatively, this file may be used in accordance with the terms and
  32 ** conditions contained in a signed written agreement between you and Nokia.
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #ifndef QDECLARATIVE_H
  43 #define QDECLARATIVE_H
  44
  45 #include <QtDeclarative/qdeclarativeprivate.h>
  46 #include <QtDeclarative/qdeclarativeparserstatus.h>
  47 #include <QtDeclarative/qdeclarativepropertyvaluesource.h>
  48 #include <QtDeclarative/qdeclarativepropertyvalueinterceptor.h>
  49 #include <QtDeclarative/qdeclarativelist.h>
  50
  51 #include <QtCore/qbytearray.h>
  52 #include <QtCore/qmetaobject.h>
  53
  54 QT_BEGIN_HEADER
  55
  56 #define QML_VERSION     0x020000
  57 #define QML_VERSION_STR "2.0"
  58
  59 #define QML_DECLARE_TYPE(TYPE) \
  60     Q_DECLARE_METATYPE(TYPE *) \
  61     Q_DECLARE_METATYPE(QDeclarativeListProperty<TYPE>)
  62
  63 #define QML_DECLARE_TYPE_HASMETATYPE(TYPE) \
  64     Q_DECLARE_METATYPE(QDeclarativeListProperty<TYPE>)
  65
  66 #define QML_DECLARE_INTERFACE(INTERFACE) \
  67     QML_DECLARE_TYPE(INTERFACE)
  68
  69 #define QML_DECLARE_INTERFACE_HASMETATYPE(INTERFACE) \
  70     QML_DECLARE_TYPE_HASMETATYPE(INTERFACE)
  71
  72 enum { /* TYPEINFO flags */
  73     QML_HAS_ATTACHED_PROPERTIES = 0x01
  74 };
  75
  76 #define QML_DECLARE_TYPEINFO(TYPE, FLAGS) \
  77 QT_BEGIN_NAMESPACE \
  78 template <> \
  79 class QDeclarativeTypeInfo<TYPE > \
  80 { \
  81 public: \
  82     enum { \
  83         hasAttachedProperties = (((FLAGS) & QML_HAS_ATTACHED_PROPERTIES) == QML_HAS_ATTACHED_PROPERTIES) \
  84     }; \
  85 }; \
  86 QT_END_NAMESPACE
  87
  88 QT_BEGIN_NAMESPACE
  89
  90 QT_MODULE(Declarative)
  91
  92 template<typename T>
  93 int qmlRegisterType()
  94 {
  95     QByteArray name(T::staticMetaObject.className());
  96
  97     QByteArray pointerName(name + '*');
  98     QByteArray listName("QDeclarativeListProperty<" + name + ">");
  99
 100     QDeclarativePrivate::RegisterType type = {
 101         0,
 102
 103         qRegisterMetaType<T *>(pointerName.constData()),
 104         qRegisterMetaType<QDeclarativeListProperty<T> >(listName.constData()),
 105         0, 0,
 106         QString(),
 107
 108         0, 0, 0, 0, &T::staticMetaObject,
 109
 110         QDeclarativePrivate::attachedPropertiesFunc<T>(),
 111         QDeclarativePrivate::attachedPropertiesMetaObject<T>(),
 112
 113         QDeclarativePrivate::StaticCastSelector<T,QDeclarativeParserStatus>::cast(),
 114         QDeclarativePrivate::StaticCastSelector<T,QDeclarativePropertyValueSource>::cast(),
 115         QDeclarativePrivate::StaticCastSelector<T,QDeclarativePropertyValueInterceptor>::cast(),
 116
 117         0, 0,
 118
 119         0,
 120         0
 121     };
 122
 123     return QDeclarativePrivate::qmlregister(QDeclarativePrivate::TypeRegistration, &type);
 124 }
 125
 126 int Q_AUTOTEST_EXPORT qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message);
 127
 128 template<typename T>
 129 int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& reason)
 130 {
 131     QByteArray name(T::staticMetaObject.className());
 132
 133     QByteArray pointerName(name + '*');
 134     QByteArray listName("QDeclarativeListProperty<" + name + ">");
 135
 136     QDeclarativePrivate::RegisterType type = {
 137         0,
 138
 139         qRegisterMetaType<T *>(pointerName.constData()),
 140         qRegisterMetaType<QDeclarativeListProperty<T> >(listName.constData()),
 141         0, 0,
 142         reason,
 143
 144         uri, versionMajor, versionMinor, qmlName, &T::staticMetaObject,
 145
 146         QDeclarativePrivate::attachedPropertiesFunc<T>(),
 147         QDeclarativePrivate::attachedPropertiesMetaObject<T>(),
 148
 149         QDeclarativePrivate::StaticCastSelector<T,QDeclarativeParserStatus>::cast(),
 150         QDeclarativePrivate::StaticCastSelector<T,QDeclarativePropertyValueSource>::cast(),
 151         QDeclarativePrivate::StaticCastSelector<T,QDeclarativePropertyValueInterceptor>::cast(),
 152
 153         0, 0,
 154
 155         0,
 156         0
 157     };
 158
 159     return QDeclarativePrivate::qmlregister(QDeclarativePrivate::TypeRegistration, &type);
 160 }
 161
 162 template<typename T>
 163 int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
 164 {
 165     QByteArray name(T::staticMetaObject.className());
 166
 167     QByteArray pointerName(name + '*');
 168     QByteArray listName("QDeclarativeListProperty<" + name + ">");
 169
 170     QDeclarativePrivate::RegisterType type = {
 171         0,
 172
 173         qRegisterMetaType<T *>(pointerName.constData()),
 174         qRegisterMetaType<QDeclarativeListProperty<T> >(listName.constData()),
 175         sizeof(T), QDeclarativePrivate::createInto<T>,
 176         QString(),
 177
 178         uri, versionMajor, versionMinor, qmlName, &T::staticMetaObject,
 179
 180         QDeclarativePrivate::attachedPropertiesFunc<T>(),
 181         QDeclarativePrivate::attachedPropertiesMetaObject<T>(),
 182
 183         QDeclarativePrivate::StaticCastSelector<T,QDeclarativeParserStatus>::cast(),
 184         QDeclarativePrivate::StaticCastSelector<T,QDeclarativePropertyValueSource>::cast(),
 185         QDeclarativePrivate::StaticCastSelector<T,QDeclarativePropertyValueInterceptor>::cast(),
 186
 187         0, 0,
 188
 189         0,
 190         0
 191     };
 192
 193     return QDeclarativePrivate::qmlregister(QDeclarativePrivate::TypeRegistration, &type);
 194 }
 195
 196 template<typename T, int metaObjectRevision>
 197 int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
 198 {
 199     QByteArray name(T::staticMetaObject.className());
 200
 201     QByteArray pointerName(name + '*');
 202     QByteArray listName("QDeclarativeListProperty<" + name + ">");
 203
 204     QDeclarativePrivate::RegisterType type = {
 205         1,
 206
 207         qRegisterMetaType<T *>(pointerName.constData()),
 208         qRegisterMetaType<QDeclarativeListProperty<T> >(listName.constData()),
 209         sizeof(T), QDeclarativePrivate::createInto<T>,
 210         QString(),
 211
 212         uri, versionMajor, versionMinor, qmlName, &T::staticMetaObject,
 213
 214         QDeclarativePrivate::attachedPropertiesFunc<T>(),
 215         QDeclarativePrivate::attachedPropertiesMetaObject<T>(),
 216
 217         QDeclarativePrivate::StaticCastSelector<T,QDeclarativeParserStatus>::cast(),
 218         QDeclarativePrivate::StaticCastSelector<T,QDeclarativePropertyValueSource>::cast(),
 219         QDeclarativePrivate::StaticCastSelector<T,QDeclarativePropertyValueInterceptor>::cast(),
 220
 221         0, 0,
 222
 223         0,
 224         metaObjectRevision
 225     };
 226
 227     return QDeclarativePrivate::qmlregister(QDeclarativePrivate::TypeRegistration, &type);
 228 }
 229
 230 template<typename T, int metaObjectRevision>
 231 int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor)
 232 {
 233     QByteArray name(T::staticMetaObject.className());
 234
 235     QByteArray pointerName(name + '*');
 236     QByteArray listName("QDeclarativeListProperty<" + name + ">");
 237
 238     QDeclarativePrivate::RegisterType type = {
 239         1,
 240
 241         qRegisterMetaType<T *>(pointerName.constData()),
 242         qRegisterMetaType<QDeclarativeListProperty<T> >(listName.constData()),
 243         sizeof(T), QDeclarativePrivate::createInto<T>,
 244         QString(),
 245
 246         uri, versionMajor, versionMinor, 0, &T::staticMetaObject,
 247
 248         QDeclarativePrivate::attachedPropertiesFunc<T>(),
 249         QDeclarativePrivate::attachedPropertiesMetaObject<T>(),
 250
 251         QDeclarativePrivate::StaticCastSelector<T,QDeclarativeParserStatus>::cast(),
 252         QDeclarativePrivate::StaticCastSelector<T,QDeclarativePropertyValueSource>::cast(),
 253         QDeclarativePrivate::StaticCastSelector<T,QDeclarativePropertyValueInterceptor>::cast(),
 254
 255         0, 0,
 256
 257         0,
 258         metaObjectRevision
 259     };
 260
 261     return QDeclarativePrivate::qmlregister(QDeclarativePrivate::TypeRegistration, &type);
 262 }
 263
 264
 265 template<typename T, typename E>
 266 int qmlRegisterExtendedType()
 267 {
 268     QByteArray name(T::staticMetaObject.className());
 269
 270     QByteArray pointerName(name + '*');
 271     QByteArray listName("QDeclarativeListProperty<" + name + ">");
 272
 273     QDeclarativePrivate::RegisterType type = {
 274         0,
 275
 276         qRegisterMetaType<T *>(pointerName.constData()),
 277         qRegisterMetaType<QDeclarativeListProperty<T> >(listName.constData()),
 278         0, 0,
 279         QString(),
 280
 281         0, 0, 0, 0, &T::staticMetaObject,
 282
 283         QDeclarativePrivate::attachedPropertiesFunc<T>(),
 284         QDeclarativePrivate::attachedPropertiesMetaObject<T>(),
 285
 286         QDeclarativePrivate::StaticCastSelector<T,QDeclarativeParserStatus>::cast(),
 287         QDeclarativePrivate::StaticCastSelector<T,QDeclarativePropertyValueSource>::cast(),
 288         QDeclarativePrivate::StaticCastSelector<T,QDeclarativePropertyValueInterceptor>::cast(),
 289
 290         QDeclarativePrivate::createParent<E>, &E::staticMetaObject,
 291
 292         0,
 293         0
 294     };
 295
 296     return QDeclarativePrivate::qmlregister(QDeclarativePrivate::TypeRegistration, &type);
 297 }
 298
 299 template<typename T, typename E>
 300 int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor,
 301                             const char *qmlName)
 302 {
 303     QByteArray name(T::staticMetaObject.className());
 304
 305     QByteArray pointerName(name + '*');
 306     QByteArray listName("QDeclarativeListProperty<" + name + ">");
 307
 308     QDeclarativeAttachedPropertiesFunc attached = QDeclarativePrivate::attachedPropertiesFunc<E>();
 309     const QMetaObject * attachedMetaObject = QDeclarativePrivate::attachedPropertiesMetaObject<E>();
 310     if (!attached) {
 311         attached = QDeclarativePrivate::attachedPropertiesFunc<T>();
 312         attachedMetaObject = QDeclarativePrivate::attachedPropertiesMetaObject<T>();
 313     }
 314
 315     QDeclarativePrivate::RegisterType type = {
 316         0,
 317
 318         qRegisterMetaType<T *>(pointerName.constData()),
 319         qRegisterMetaType<QDeclarativeListProperty<T> >(listName.constData()),
 320         sizeof(T), QDeclarativePrivate::createInto<T>,
 321         QString(),
 322
 323         uri, versionMajor, versionMinor, qmlName, &T::staticMetaObject,
 324
 325         attached,
 326         attachedMetaObject,
 327
 328         QDeclarativePrivate::StaticCastSelector<T,QDeclarativeParserStatus>::cast(),
 329         QDeclarativePrivate::StaticCastSelector<T,QDeclarativePropertyValueSource>::cast(),
 330         QDeclarativePrivate::StaticCastSelector<T,QDeclarativePropertyValueInterceptor>::cast(),
 331
 332         QDeclarativePrivate::createParent<E>, &E::staticMetaObject,
 333
 334         0,
 335         0
 336     };
 337
 338     return QDeclarativePrivate::qmlregister(QDeclarativePrivate::TypeRegistration, &type);
 339 }
 340
 341 template<typename T>
 342 int qmlRegisterInterface(const char *typeName)
 343 {
 344     QByteArray name(typeName);
 345
 346     QByteArray pointerName(name + '*');
 347     QByteArray listName("QDeclarativeListProperty<" + name + ">");
 348
 349     QDeclarativePrivate::RegisterInterface qmlInterface = {
 350         0,
 351
 352         qRegisterMetaType<T *>(pointerName.constData()),
 353         qRegisterMetaType<QDeclarativeListProperty<T> >(listName.constData()),
 354
 355         qobject_interface_iid<T *>()
 356     };
 357
 358     return QDeclarativePrivate::qmlregister(QDeclarativePrivate::InterfaceRegistration, &qmlInterface);
 359 }
 360
 361 template<typename T>
 362 int qmlRegisterCustomType(const char *uri, int versionMajor, int versionMinor,
 363                           const char *qmlName, QDeclarativeCustomParser *parser)
 364 {
 365     QByteArray name(T::staticMetaObject.className());
 366
 367     QByteArray pointerName(name + '*');
 368     QByteArray listName("QDeclarativeListProperty<" + name + ">");
 369
 370     QDeclarativePrivate::RegisterType type = {
 371         0,
 372
 373         qRegisterMetaType<T *>(pointerName.constData()),
 374         qRegisterMetaType<QDeclarativeListProperty<T> >(listName.constData()),
 375         sizeof(T), QDeclarativePrivate::createInto<T>,
 376         QString(),
 377
 378         uri, versionMajor, versionMinor, qmlName, &T::staticMetaObject,
 379
 380         QDeclarativePrivate::attachedPropertiesFunc<T>(),
 381         QDeclarativePrivate::attachedPropertiesMetaObject<T>(),
 382
 383         QDeclarativePrivate::StaticCastSelector<T,QDeclarativeParserStatus>::cast(),
 384         QDeclarativePrivate::StaticCastSelector<T,QDeclarativePropertyValueSource>::cast(),
 385         QDeclarativePrivate::StaticCastSelector<T,QDeclarativePropertyValueInterceptor>::cast(),
 386
 387         0, 0,
 388
 389         parser,
 390         0
 391     };
 392
 393     return QDeclarativePrivate::qmlregister(QDeclarativePrivate::TypeRegistration, &type);
 394 }
 395
 396 class QDeclarativeContext;
 397 class QDeclarativeEngine;
 398 class QScriptValue;
 399 class QScriptEngine;
 400 Q_DECLARATIVE_EXPORT void qmlExecuteDeferred(QObject *);
 401 Q_DECLARATIVE_EXPORT QDeclarativeContext *qmlContext(const QObject *);
 402 Q_DECLARATIVE_EXPORT QDeclarativeEngine *qmlEngine(const QObject *);
 403 Q_DECLARATIVE_EXPORT QObject *qmlAttachedPropertiesObjectById(int, const QObject *, bool create = true);
 404 Q_DECLARATIVE_EXPORT QObject *qmlAttachedPropertiesObject(int *, const QObject *, const QMetaObject *, bool create);
 405
 406 template<typename T>
 407 QObject *qmlAttachedPropertiesObject(const QObject *obj, bool create = true)
 408 {
 409     static int idx = -1;
 410     return qmlAttachedPropertiesObject(&idx, obj, &T::staticMetaObject, create);
 411 }
 412
 413 /*!
 414    This function may be used to register a module API provider \a callback in a particular \a uri
 415    with a version specified in \a versionMajor and \a versionMinor.
 416
 417    Installing a module API into a uri allows developers to provide arbitrary functionality
 418    (methods and properties) in a namespace that doesn't necessarily contain elements.
 419
 420    A module API may be either a QObject or a QScriptValue.  Only one module API provider
 421    may be registered into any given namespace (combination of \a uri, \a majorVersion and \a minorVersion).
 422    This function should be used to register a module API provider function which returns a QScriptValue as a module API.
 423
 424    Usage:
 425    \code
 426    // first, define the module API provider function (callback).
 427    static QScriptValue *example_qscriptvalue_module_api_provider(QDeclarativeEngine *engine, QScriptEngine *scriptEngine)
 428    {
 429        Q_UNUSED(engine)
 430
 431        static int seedValue = 5;
 432        QScriptValue example = scriptEngine->newObject();
 433        example.setProperty("someProperty", seedValue++);
 434        return example;
 435    }
 436
 437    // second, register the module API provider with QML by calling this function in an initialization function.
 438    ...
 439    qmlRegisterModuleApi("Qt.example.qscriptvalueApi", 1, 0, example_qscriptvalue_module_api_provider);
 440    ...
 441    \endcode
 442
 443    In order to use the registered module API in QML, you must import the module API.
 444    \qml
 445    import QtQuick 2.0
 446    import Qt.example.qscriptvalueApi 1.0 as ExampleApi
 447    Item {
 448        id: root
 449        property int someValue: ExampleApi.someProperty
 450    }
 451    \endqml
 452   */
 453 inline int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor,
 454                                 QScriptValue (*callback)(QDeclarativeEngine *, QScriptEngine *))
 455 {
 456     QDeclarativePrivate::RegisterModuleApi api = {
 457         0,
 458
 459         uri, versionMajor, versionMinor,
 460
 461         callback, 0
 462     };
 463
 464     return QDeclarativePrivate::qmlregister(QDeclarativePrivate::ModuleApiRegistration, &api);
 465 }
 466
 467 /*!
 468    This function may be used to register a module API provider \a callback in a particular \a uri
 469    with a version specified in \a versionMajor and \a versionMinor.
 470
 471    Installing a module API into a uri allows developers to provide arbitrary functionality
 472    (methods and properties) in a namespace that doesn't necessarily contain elements.
 473
 474    A module API may be either a QObject or a QScriptValue.  Only one module API provider
 475    may be registered into any given namespace (combination of \a uri, \a majorVersion and \a minorVersion).
 476    This function should be used to register a module API provider function which returns a QObject as a module API.
 477
 478    Usage:
 479    \code
 480    // first, define your QObject which provides the functionality.
 481    class ModuleApiExample : public QObject
 482    {
 483        Q_OBJECT
 484        Q_PROPERTY (int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged)
 485
 486    public:
 487        ModuleApiExample(QObject* parent = 0)
 488            : QObject(parent), m_someProperty(0)
 489        {
 490        }
 491
 492        ~ModuleApiExample() {}
 493
 494        Q_INVOKABLE int doSomething() { setSomeProperty(5); return m_someProperty; }
 495
 496        int someProperty() const { return m_someProperty; }
 497        void setSomeProperty(int val) { m_someProperty = val; emit somePropertyChanged(val); }
 498
 499    signals:
 500        void somePropertyChanged(int newValue);
 501
 502    private:
 503        int m_someProperty;
 504    };
 505
 506    // second, define the module API provider function (callback).
 507    static QObject *example_qobject_module_api_provider(QDeclarativeEngine *engine, QScriptEngine *scriptEngine)
 508    {
 509        Q_UNUSED(engine)
 510        Q_UNUSED(scriptEngine)
 511
 512        ModuleApiExample *example = new ModuleApiExample();
 513        return example;
 514    }
 515
 516    // third, register the module API provider with QML by calling this function in an initialization function.
 517    ...
 518    qmlRegisterModuleApi("Qt.example.qobjectApi", 1, 0, example_qobject_module_api_provider);
 519    ...
 520    \endcode
 521
 522    In order to use the registered module API in QML, you must import the module API.
 523    \qml
 524    import QtQuick 2.0
 525    import Qt.example.qobjectApi 1.0 as ExampleApi
 526    Item {
 527        id: root
 528        property int someValue: ExampleApi.someProperty
 529
 530        Component.onCompleted: {
 531            someValue = ExampleApi.doSomething()
 532        }
 533    }
 534    \endqml
 535   */
 536 inline int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor,
 537                                 QObject *(*callback)(QDeclarativeEngine *, QScriptEngine *))
 538 {
 539     QDeclarativePrivate::RegisterModuleApi api = {
 540         0,
 541
 542         uri, versionMajor, versionMinor,
 543
 544         0, callback
 545     };
 546
 547     return QDeclarativePrivate::qmlregister(QDeclarativePrivate::ModuleApiRegistration, &api);
 548 }
 549
 550 QT_END_NAMESPACE
 551
 552 QML_DECLARE_TYPE(QObject)
 553 Q_DECLARE_METATYPE(QVariant)
 554
 555 QT_END_HEADER
 556
 557 #endif // QDECLARATIVE_H