Merge branch '4.7' of scm.dev.nokia.troll.no:qt/qt-qml into 4.7-integration
[qt:qt.git] / 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