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