doc/src/declarative/qtbinding.qdoc

   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 documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Free Documentation License
  17 ** Alternatively, this file may be used under the terms of the GNU Free
  18 ** Documentation License version 1.3 as published by the Free Software
  19 ** Foundation and appearing in the file included in the packaging of this
  20 ** file.
  21 **
  22 ** If you have questions regarding the use of this file, please contact
  23 ** Nokia at qt-info@nokia.com.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qtbinding.html
  30 \ingroup qml-features
  31 \previouspage {Extending QML Functionalities using C++}
  32 \nextpage {Integrating QML Code with Existing Qt UI Code}
  33 \contentspage QML Features
  34 \title Using QML Bindings in C++ Applications
  35
  36 QML is designed to be easily extensible to and from C++. The classes in the
  37 Qt Declarative module allow QML components to be loaded and manipulated from C++, and through
  38 Qt's \l{The Meta-Object System}{meta-object system}, QML and C++ objects can easily
  39 communicate through Qt signals and slots. In addition, QML plugins can be written to create
  40 reusable QML components for distribution.
  41
  42 You may want to mix QML and C++ for a number of reasons. For example:
  43
  44 \list
  45 \o To use functionality defined in a C++ source (for example, when using a C++ Qt-based data model, or
  46 calling functions in a third-party C++ library)
  47 \o To access functionality in the Qt Declarative module (for example, to dynamically generate
  48 images using QDeclarativeImageProvider)
  49 \o To write your own QML elements (whether for your applications, or for distribution to others)
  50 \endlist
  51
  52 To use the Qt Declarative module, you must include and link to the module appropriately, as shown on
  53 the \l {QtDeclarative}{module index page}. The \l {Qt Declarative UI Runtime} documentation
  54 shows how to build a basic C++ application that uses this module.
  55
  56
  57 \section1 Core module classes
  58
  59 The Qt Declarative module provides a set of C++ APIs for extending your QML applications from C++ and
  60 embedding QML into C++ applications. There are several core classes in the Qt Declarative module
  61 that provide the essential capabilities for doing this. These are:
  62
  63 \list
  64 \o QDeclarativeEngine: A QML engine provides the environment for executing QML code. Every
  65 application requires at least one engine instance.
  66 \o QDeclarativeComponent: A component encapsulates a \l{QML Documents}{QML document}.
  67 \o QDeclarativeContext: A context allows an application to expose data to the QML components
  68 created by an engine.
  69 \endlist
  70
  71 A QDeclarativeEngine allows the configuration of global settings that apply to all of its QML
  72 component instances: for example, the QNetworkAccessManager to be used for network communications,
  73 and the file path to be used for persistent storage.
  74
  75 QDeclarativeComponent is used to load QML documents. Each QDeclarativeComponent instance represents
  76 a single document. A component can be created from the URL or file path of a QML document, or the raw
  77 QML code of the document. Component instances are instatiated through the
  78 QDeclarativeComponent::create() method, like this:
  79
  80 \code
  81 QDeclarativeEngine engine;
  82 QDeclarativeComponent component(&engine, QUrl::fromLocalFile("MyRectangle.qml"));
  83 QObject *rectangleInstance = component.create();
  84
  85 // ...
  86 delete rectangleInstance;
  87 \endcode
  88
  89 QML documents can also be loaded using QDeclarativeView. This class provides a convenient
  90 QWidget-based view for embedding QML components into QGraphicsView-based applications. (For other
  91 methods of integrating QML into QWidget-based applications, see \l {Integrating QML Code with existing Qt
  92 UI code}.)
  93
  94
  95 \section1 Approaches to using QML with C++
  96
  97 There are a number of ways to extend your QML application through C++. For example, you could:
  98
  99 \list
 100 \o Load a QML component and manipulate it (or its children) from C++
 101 \o Embed a C++ object and its properties directly into a QML component (for example, to make a
 102 particular C++ object callable from QML, or to replace a dummy list model with a real data set)
 103 \o Define new QML elements (through QObject-based C++ classes) and create them directly from your
 104 QML code
 105 \endlist
 106
 107 These methods are shown below. Naturally these approaches are not exclusive; you can mix any of
 108 these methods throughout your application as appropriate.
 109
 110
 111 \section2 Loading QML components from C++
 112
 113 A QML document can be loaded with QDeclarativeComponent or QDeclarativeView. QDeclarativeComponent
 114 loads a QML component as a C++ object; QDeclarativeView also does this,
 115 but additionally loads the QML component directly into a QGraphicsView. It is convenient for loading
 116 a displayable QML component into a QWidget-based application.
 117
 118 For example, suppose there is a \c MyItem.qml file that looks like this:
 119
 120 \snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml start
 121 \snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml end
 122
 123 This QML document can be loaded with QDeclarativeComponent or QDeclarativeView with the following
 124 C++ code. Using a QDeclarativeComponent requires calling QDeclarativeComponent::create() to create
 125 a new instance of the component, while a QDeclarativeView automatically creates an instance of the
 126 component, which is accessible via QDeclarativeView::rootObject():
 127
 128 \table
 129 \row
 130 \o
 131 \snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp QDeclarativeComponent-a
 132 \dots 0
 133 \snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp QDeclarativeComponent-b
 134 \o
 135 \snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp QDeclarativeView
 136 \endtable
 137
 138 This \c object is the instance of the \c MyItem.qml component that has been created. You can now
 139 modify the item's properties using QObject::setProperty() or QDeclarativeProperty:
 140
 141 \snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp properties
 142
 143 Alternatively, you can cast the object to its actual type and call functions with compile-time
 144 safety. In this case the base object of \c MyItem.qml is an \l Item, which is defined by the
 145 QDeclarativeItem class:
 146
 147 \snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp cast
 148
 149 You can also connect to any signals or call functions defined in the component using
 150 QMetaObject::invokeMethod() and QObject::connect(). See \l {Exchanging data between QML and C++}
 151 below for further details.
 152
 153 \section3 Locating child objects
 154
 155 QML components are essentially object trees with children that have siblings and their own children.
 156 Child objects of QML components can be located using the QObject::objectName property with
 157 QObject::findChild(). For example, if the root item in \c MyItem.qml had a child \l Rectangle item:
 158
 159 \snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml start
 160 \codeline
 161 \snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml child
 162 \snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml end
 163
 164 The child could be located like this:
 165
 166 \snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp findChild
 167
 168 If \c objectName is used inside a delegate of a ListView, \l Repeater or some other
 169 element that creates multiple instances of its delegates, there will be multiple children with
 170 the same \c objectName. In this case, QObject::findChildren() can be used to find all children
 171 with a matching \c objectName.
 172
 173 \warning While it is possible to use C++ to access and manipulate QML objects deep into the
 174 object tree, we recommend that you do not take this approach outside of application
 175 testing and prototyping. One strength of QML and C++ integration is the ability to implement the
 176 QML user interface separately from the C++ logic and dataset backend, and this strategy breaks if the
 177 C++ side reaches deep into the QML components to manipulate them directly. This would make it difficult
 178 to, for example, swap a QML view component for another view, if the new component was missing a
 179 required \c objectName. It is better for the C++ implementation to know as little as possible about
 180 the QML user interface implementation and the composition of the QML object tree.
 181
 182
 183 \section2 Embedding C++ objects into QML components
 184
 185 When loading a QML scene into a C++ application, it can be useful to directly embed C++ data into
 186 the QML object. QDeclarativeContext enables this by exposing data to the context of a QML
 187 component, allowing data to be injected from C++ into QML.
 188
 189 For example, here is a QML item that refers to a \c currentDateTime value that does not exist in
 190 the current scope:
 191
 192 \snippet doc/src/snippets/declarative/qtbinding/context/MyItem.qml 0
 193
 194 This \c currentDateTime value can be set directly by the C++ application that loads the QML
 195 component, using QDeclarativeContext::setContextProperty():
 196
 197 \snippet doc/src/snippets/declarative/qtbinding/context/main.cpp 0
 198
 199 Context properties can hold either QVariant or QObject* values. This means custom C++ objects can
 200 also be injected using this approach, and these objects can be modified and read directly in QML.
 201 Here, we modify the above example to embed a QObject instance instead of a QDateTime value, and the QML code
 202 invokes a method on the object instance:
 203
 204 \table
 205 \row
 206 \o
 207 \snippet doc/src/snippets/declarative/qtbinding/context-advanced/applicationdata.h 0
 208 \codeline
 209 \snippet doc/src/snippets/declarative/qtbinding/context-advanced/main.cpp 0
 210 \o
 211 \snippet doc/src/snippets/declarative/qtbinding/context-advanced/MyItem.qml 0
 212 \endtable
 213
 214 (Note that date/time values returned from C++ to QML can be formatted through
 215 \l{QML:Qt::formatDateTime}{Qt.formatDateTime()} and associated functions.)
 216
 217 If the QML item needs to receive signals from the context property, it can connect to them using the
 218 \l Connections element. For example, if \c ApplicationData has a signal named \c
 219 dataChanged(), this signal can be connected to using an \c onDataChanged handler within
 220 a \l Connections object:
 221
 222 \snippet doc/src/snippets/declarative/qtbinding/context-advanced/connections.qml 0
 223
 224 Context properties can be useful for using C++ based data models in a QML view. See the
 225 \l {declarative/modelviews/stringlistmodel}{String ListModel},
 226 \l {declarative/modelviews/objectlistmodel}{Object ListModel} and
 227 \l {declarative/modelviews/abstractitemmodel}{AbstractItemModel} models for
 228 respective examples on using QStringListModel, QObjectList-based models and QAbstractItemModel
 229 in QML views.
 230
 231 Also see the QDeclarativeContext documentation for more information.
 232
 233
 234 \section2 Defining new QML elements
 235
 236 While new QML elements can be \l {Defining New Components}{defined in QML}, they can also be
 237 defined by C++ classes; in fact, many of the core \l {QML Elements} are implemented through
 238 C++ classes. When you create a QML object using one of these elements, you are simply creating an
 239 instance of a QObject-based C++ class and setting its properties.
 240
 241 To create a visual item that fits in with the Qt Quick elements, base your class off \l QDeclarativeItem instead of QObject directly.
 242 You can then implement your own painting and functionality like any other QGraphicsObject. Note that QGraphicsItem::ItemHasNoContents is set by default on QDeclarativeItem because
 243 it does not paint anything; you will need to clear this if your item is supposed to paint anything (as opposed to being solely for input handling or logical grouping).
 244
 245 For example, here is an \c ImageViewer class with an \c image URL property:
 246
 247 \snippet doc/src/snippets/declarative/qtbinding/newelements/imageviewer.h 0
 248
 249 Aside from the fact that it inherits QDeclarativeItem, this is an ordinary class that could
 250 exist outside of QML. However, once it is registered with the QML engine using qmlRegisterType():
 251
 252 \snippet doc/src/snippets/declarative/qtbinding/newelements/main.cpp register
 253
 254 Then, any QML code loaded by your C++ application or \l{QDeclarativeExtensionPlugin}{plugin} can create and manipulate
 255 \c ImageViewer objects:
 256
 257 \snippet doc/src/snippets/declarative/qtbinding/newelements/standalone.qml 0
 258
 259
 260 It is advised that you avoid using QGraphicsItem functionality beyond the properties documented in QDeclarativeItem.
 261 This is because the GraphicsView backend is intended to be an implementation detail for QML, so the QtQuick items can be moved to faster backends as they become available with no change from a QML perspective.
 262 To minimize any porting requirements for custom visual items, try to stick to the documented properties in QDeclarativeItem where possible. Properties QDeclarativeItem inherits but doesn't document are classed as implementation details; they are not officially supported and may disappear between releases.
 263
 264 Note that custom C++ types do not have to inherit from QDeclarativeItem; this is only necessary if it is
 265 a displayable item. If the item is not displayable, it can simply inherit from QObject.
 266
 267 For more information on defining new QML elements, see the \l {Tutorial: Writing QML extensions with C++}
 268 {Writing QML extensions with C++} tutorial and the
 269 \l {Extending QML Functionalities using C++} reference documentation.
 270
 271
 272
 273 \section1 Exchanging data between QML and C++
 274
 275 QML and C++ objects can communicate with one another through signals, slots and property
 276 modifications. For a C++ object, any data that is exposed to Qt's \l{The Meta-Object System}{Meta-Object System}
 277 - that is, properties, signals, slots and Q_INVOKABLE methods - become available to QML. On
 278 the QML side, all QML object data is automatically made available to the meta-object system and can
 279 be accessed from C++.
 280
 281
 282 \section2 Calling functions
 283
 284 QML functions can be called from C++ and vice-versa.
 285
 286 All QML functions are exposed to the meta-object system and can be called using
 287 QMetaObject::invokeMethod(). Here is a C++ application that uses this to call a QML function:
 288
 289 \table
 290 \row
 291 \o \snippet doc/src/snippets/declarative/qtbinding/functions-qml/MyItem.qml 0
 292 \o \snippet doc/src/snippets/declarative/qtbinding/functions-qml/main.cpp 0
 293 \endtable
 294
 295 Notice the Q_RETURN_ARG() and Q_ARG() arguments for QMetaObject::invokeMethod() must be specified as
 296 QVariant types, as this is the generic data type used for QML functions and return values.
 297
 298 To call a C++ function from QML, the function must be either a Qt slot, or a function marked with
 299 the Q_INVOKABLE macro, to be available to QML. In the following example, the QML code invokes
 300 methods on the \c myObject object, which has been set using QDeclarativeContext::setContextProperty():
 301
 302 \table
 303 \row
 304 \o
 305 \snippet doc/src/snippets/declarative/qtbinding/functions-cpp/MyItem.qml 0
 306 \o
 307 \snippet doc/src/snippets/declarative/qtbinding/functions-cpp/myclass.h 0
 308 \codeline
 309 \snippet doc/src/snippets/declarative/qtbinding/functions-cpp/main.cpp 0
 310 \endtable
 311
 312 QML supports the calling of overloaded C++ functions. If there are multiple C++ functions with the
 313 same name but different arguments, the correct function will be called according to the number and
 314 the types of arguments that are provided.
 315
 316
 317 \section2 Receiving signals
 318
 319 All QML signals are automatically available to C++, and can be connected to using QObject::connect()
 320 like any ordinary Qt C++ signal. In return, any C++ signal can be received by a QML object using
 321 \l {Signal Handlers}{signal handlers}.
 322
 323 Here is a QML component with a signal named \c qmlSignal. This signal is connected to a C++ object's
 324 slot using QObject::connect(), so that the \c cppSlot() method is called whenever the \c qmlSignal
 325 is emitted:
 326
 327 \table
 328 \row
 329 \o
 330 \snippet doc/src/snippets/declarative/qtbinding/signals-qml/MyItem.qml 0
 331 \o
 332 \snippet doc/src/snippets/declarative/qtbinding/signals-qml/myclass.h 0
 333 \codeline
 334 \snippet doc/src/snippets/declarative/qtbinding/signals-qml/main.cpp 0
 335 \endtable
 336
 337 To connect to Qt C++ signals from within QML, use a signal handler with the \c on<SignalName> syntax.
 338 If the C++ object is directly creatable from within QML (see \l {Defining new QML elements} above)
 339 then the signal handler can be defined within the object declaration. In the following example, the
 340 QML code creates a \c ImageViewer object, and the \c imageChanged and \c loadingError signals of the
 341 C++ object are connected to through \c onImagedChanged and \c onLoadingError signal handlers in QML:
 342
 343 \table
 344 \row
 345 \o
 346
 347 \snippet doc/src/snippets/declarative/qtbinding/signals-cpp/imageviewer.h start
 348 \dots 4
 349 \snippet doc/src/snippets/declarative/qtbinding/signals-cpp/imageviewer.h end
 350
 351 \o
 352 \snippet doc/src/snippets/declarative/qtbinding/signals-cpp/standalone.qml 0
 353 \endtable
 354
 355 (Note that if a signal has been declared as the NOTIFY signal for a property, QML allows it to be
 356 received with an \c on<Property>Changed handler even if the signal's name does not follow the \c
 357 <Property>Changed naming convention. In the above example, if the "imageChanged" signal was named
 358 "imageModified" instead, the \c onImageChanged signal handler would still be called.)
 359
 360 If, however, the object with the signal is not created from within the QML code, and the QML item only has a
 361 reference to the created object - for example, if the object was set using
 362 QDeclarativeContext::setContextProperty() - then the \l Connections element can be used
 363 instead to create the signal handler:
 364
 365 \table
 366 \row
 367 \o \snippet doc/src/snippets/declarative/qtbinding/signals-cpp/main.cpp connections
 368 \o \snippet doc/src/snippets/declarative/qtbinding/signals-cpp/MyItem.qml 0
 369 \endtable
 370
 371 C++ signals can use enum values as parameters provided that the enum is declared in the
 372 class that is emitting the signal, and that the enum is registered using Q_ENUMS.
 373 See \l {Using enumerations of a custom type} below for details.
 374
 375
 376 \section2 Modifying properties
 377
 378 Any properties declared in a QML object are automatically accessible from C++. Given a QML item
 379 like this:
 380
 381 \snippet doc/src/snippets/declarative/qtbinding/properties-qml/MyItem.qml 0
 382
 383 The value of the \c someNumber property can be set and read using QDeclarativeProperty, or
 384 QObject::setProperty() and QObject::property():
 385
 386 \snippet doc/src/snippets/declarative/qtbinding/properties-qml/main.cpp 0
 387
 388 You should always use QObject::setProperty(), QDeclarativeProperty or QMetaProperty::write() to
 389 change a QML property value, to ensure the QML engine is made aware of the property change. For example,
 390 say you have a custom element \c PushButton with a \c buttonText property that internally reflects
 391 the value of a \c m_buttonText member variable. Modifying the member variable directly like this is
 392 not a good idea:
 393
 394 \badcode
 395 // BAD!
 396 QDeclarativeComponent component(engine, "MyButton.qml");
 397 PushButton *button = qobject_cast<PushButton*>(component.create());
 398 button->m_buttonText = "Click me";
 399 \endcode
 400
 401 Since the value is changed directly, this bypasses Qt's \l{The Meta-Object System}{meta-object system}
 402 and the QML engine is not made aware of the property change. This means property bindings to
 403 \c buttonText would not be updated, and any \c onButtonTextChanged handlers would not be called.
 404
 405
 406 \target properties-cpp
 407
 408 Any \l {The Property System}{Qt properties} - that is, those declared with the Q_PROPERTY()
 409 macro - are accessible from QML. Here is a modified version of the \l {Embedding C++ objects into
 410 QML components}{earlier example} on this page; here, the \c ApplicationData class has a \c backgroundColor
 411 property. This property can be written to and read from QML:
 412
 413 \table
 414 \row
 415 \o \snippet doc/src/snippets/declarative/qtbinding/properties-cpp/applicationdata.h 0
 416 \o \snippet doc/src/snippets/declarative/qtbinding/properties-cpp/MyItem.qml 0
 417 \endtable
 418
 419 Notice the \c backgroundColorChanged signal is declared as the NOTIFY signal for the
 420 \c backgroundColor property. If a Qt property does not have an associated NOTIFY signal,
 421 the property cannot be used for \l {Property Binding} in QML, as the QML engine would not be
 422 notified when the value changes. If you are using custom types in QML, make sure their
 423 properties have NOTIFY signals so that they can be used in property bindings.
 424
 425 See \l {Tutorial: Writing QML extensions with C++} for further details and examples
 426 on using Qt properties with QML.
 427
 428
 429 \section1 Supported data types
 430
 431 Any C++ data that is used from QML - whether as custom properties, or parameters for signals or
 432 functions - must be of a type that is recognizable by QML.
 433
 434 By default, QML recognizes the following data types:
 435
 436 \list
 437 \o bool
 438 \o unsigned int, int
 439 \o float, double, qreal
 440 \o QString
 441 \o QUrl
 442 \o QColor
 443 \o QDate, QTime, QDateTime
 444 \o QPoint, QPointF
 445 \o QSize, QSizeF
 446 \o QRect, QRectF
 447 \o QVariant
 448 \o QVariantList, QVariantMap
 449 \o QObject*
 450 \o Enumerations declared with Q_ENUMS()
 451 \endlist
 452
 453 To allow a custom C++ type to be created or used in QML, the C++ class must be registered as a QML
 454 type using qmlRegisterType(), as shown in the \l {Defining new QML elements} section above.
 455
 456
 457 \section2 JavaScript arrays and objects
 458
 459 There is built-in support for automatic type conversion between QVariantList and JavaScript
 460 arrays, and QVariantMap and JavaScript objects.
 461
 462 For example, the function defined in QML below left expects two arguments, an array and an object, and prints
 463 their contents using the standard JavaScript syntax for array and object item access. The C++ code
 464 below right calls this function, passing a QVariantList and a QVariantMap, which are automatically
 465 converted to JavaScript array and object values, repectively:
 466
 467 \table
 468 \row
 469 \o \snippet doc/src/snippets/declarative/qtbinding/variantlistmap/MyItem.qml 0
 470 \o \snippet doc/src/snippets/declarative/qtbinding/variantlistmap/main.cpp 0
 471 \endtable
 472
 473 This produces output like:
 474
 475 \code
 476 Array item: 10
 477 Array item: #00ff00
 478 Array item: bottles
 479 Object item: language = QML
 480 Object item: released = Tue Sep 21 2010 00:00:00 GMT+1000 (EST)
 481 \endcode
 482
 483 Similarly, if a C++ type uses a QVariantList or QVariantMap type for a property or method
 484 parameter, the value can be created as a JavaScript array or object in the QML
 485 side, and is automatically converted to a QVariantList or QVariantMap when it is passed to C++.
 486
 487
 488 \section2 Using enumerations of a custom type
 489
 490 To use an enumeration from a custom C++ component, the enumeration must be declared with Q_ENUMS() to
 491 register it with Qt's meta object system. For example, the following C++ type has a \c Status enum:
 492
 493 \snippet doc/src/snippets/declarative/qtbinding/enums/imageviewer.h start
 494 \snippet doc/src/snippets/declarative/qtbinding/enums/imageviewer.h end
 495
 496 Providing the \c ImageViewer class has been registered using qmlRegisterType(), its \c Status enum can
 497 now be used from QML:
 498
 499 \snippet doc/src/snippets/declarative/qtbinding/enums/standalone.qml 0
 500
 501 The C++ type must be registered with QML to use its enums. If your C++ type is not instantiable, it
 502 can be registered using qmlRegisterUncreatableType().  To be accessible from QML, the names of enum values
 503 must begin with a capital letter.
 504
 505 See the \l {Tutorial: Writing QML extensions with C++}{Writing QML extensions with C++} tutorial and
 506 the \l {Extending QML Functionalities using C++} reference documentation for
 507 more information.
 508
 509
 510 \section2 Using enumeration values as signal parameters
 511
 512 C++ signals may pass enumeration values as signal parameters to QML, providing that the enumeration
 513 and the signal are declared within the same class, or that the enumeration value is one of those declared
 514 in the \l {Qt}{Qt Namespace}.
 515
 516 Additionally, if a C++ signal with an enum parameter should be connectable to a QML function using the
 517 \l {Connecting signals to methods and other signals}{connect()} function, the enum type must be
 518 registered using qRegisterMetaType().
 519
 520 For QML signals, enum values may be used as signal parameters using the \c int type:
 521
 522 \snippet doc/src/snippets/declarative/qtbinding/enums/standalone.qml 1
 523
 524
 525 \section2 Automatic type conversion from strings
 526
 527 As a convenience, some basic types can be specified in QML using format strings to make it easier to
 528 pass simple values from QML to C++.
 529
 530 \table
 531 \header
 532 \o Type
 533 \o String format
 534 \o Example
 535 \row
 536 \o QColor
 537 \o Color name, "#RRGGBB", "#RRGGBBAA"
 538 \o "red", "#ff0000", "#ff000000"
 539 \row
 540 \o QDate
 541 \o "YYYY-MM-DD"
 542 \o "2010-05-31"
 543 \row
 544 \o QPoint
 545 \o "x,y"
 546 \o "10,20"
 547 \row
 548 \o QRect
 549 \o "x,y,WidthxHeight"
 550 \o "50,50,100x100"
 551 \row
 552 \o QSize
 553 \o "WidthxHeight"
 554 \o "100x200"
 555 \row
 556 \o QTime
 557 \o "hh:mm:ss"
 558 \o "14:22:55"
 559 \row
 560 \o QUrl
 561 \o URL string
 562 \o "http://www.example.com"
 563 \row
 564 \o QVector3D
 565 \o "x,y,z"
 566 \o "0,1,0"
 567 \row
 568 \o Enumeration value
 569 \o Enum value name
 570 \o "AlignRight"
 571 \endtable
 572
 573 (More details on these string formats and types can be found in the
 574 \l {QML Basic Types}{basic type documentation}.)
 575
 576 These string formats can be used to set QML \c property values and pass arguments to C++
 577 functions. This is demonstrated by various examples on this page; in the above
 578 \l{#properties-cpp}{Qt properties example}, the \c ApplicationData class has a \c backgroundColor
 579 property of a QColor type, which is set from the QML code with the string "red" rather rather
 580 than an actual QColor object.
 581
 582 If it is preferred to pass an explicitly-typed value rather than a string, the global
 583 \l{QmlGlobalQtObject}{Qt object} provides convenience functions for creating some of the object
 584 types listed above. For example, \l{QML:Qt::rgba()}{Qt.rgba()} creates a QColor value from four
 585 RGBA values. The QColor returned from this function could be used instead of a string to set
 586 a QColor-type property or to call a C++ function that requires a QColor parameter.
 587
 588
 589 \section1 Writing QML plugins
 590
 591 The Qt Declarative module includes the QDeclarativeExtensionPlugin class, which is an abstract
 592 class for writing QML plugins. This allows QML extension types to be dynamically loaded into
 593 QML applications.
 594
 595 See the QDeclarativeExtensionPlugin documentation and \l {How to Create Qt Plugins} for more
 596 details.
 597
 598
 599 \section1 Managing resource files with the Qt resource system
 600
 601 The \l {The Qt Resource System}{Qt resource system} allows resource files to be stored as
 602 binary files in an application executable. This can be useful when building a mixed
 603 QML/C++ application as it enables QML files (as well as other resources such as images
 604 and sound files) to be referred to through the resource system URI scheme rather than
 605 relative or absolute paths to filesystem resources. Note, however, that if you use the resource
 606 system, the application executable must be re-compiled whenever a QML source file is changed
 607 in order to update the resources in the package.
 608
 609 To use the resource system in a mixed QML/C++ application:
 610
 611 \list
 612 \o Create a \c .qrc \l {The Qt Resource System}{resource collection file} that lists resource
 613    files in XML format
 614 \o From C++, load the main QML file as a resource using the \c :/ prefix or as a URL with the
 615    \c qrc scheme
 616 \endlist
 617
 618 Once this is done, all files specified by relative paths in QML will be loaded from
 619 the resource system instead. Use of the resource system is completely transparent to
 620 the QML layer; this means all QML code should refer to resource files using relative
 621 paths and should \e not use the \c qrc scheme. This scheme should only be used from
 622 C++ code for referring to resource files.
 623
 624 Here is a application packaged using the \l {The Qt Resource System}{Qt resource system}.
 625 The directory structure looks like this:
 626
 627 \code
 628 project
 629     |- example.qrc
 630     |- main.qml
 631     |- images
 632         |- background.png
 633     |- main.cpp
 634     |- project.pro
 635 \endcode
 636
 637 The \c main.qml and \c background.png files will be packaged as resource files. This is
 638 done in the \c example.qrc resource collection file:
 639
 640 \quotefile doc/src/snippets/declarative/qtbinding/resources/example.qrc
 641
 642 Since \c background.png is a resource file, \c main.qml can refer to it using the relative
 643 path specified in \c example.qrc:
 644
 645 \snippet doc/src/snippets/declarative/qtbinding/resources/main.qml 0
 646
 647 To allow QML to locate resource files correctly, the \c main.cpp loads the main QML
 648 file, \c main.qml, as a resource file using the \c qrc scheme:
 649
 650 \snippet doc/src/snippets/declarative/qtbinding/resources/main.cpp 0
 651
 652 Finally \c project.pro uses the RESOURCES variable to indicate that \c example.qrc should
 653 be used to build the application resources:
 654
 655 \quotefile doc/src/snippets/declarative/qtbinding/resources/resources.pro
 656
 657 See \l {The Qt Resource System} for more information.
 658
 659 */
 660
 661