1 files changed, 127 insertions, 0 deletions
diff --git a/doc/src/declarative/cppitem.qdoc b/doc/src/declarative/cppitem.qdoc
new file mode 100644
index 0000000..959bc6d
--- /dev/null
+++ b/doc/src/declarative/cppitem.qdoc
@@ -0,0 +1,127 @@
+/*! 
+\page cppitem.html
+\target cppitem
+\title C++ Components
+
+\section1 Making a C++ object available in QML
+
+In QML, XML tags and attributes correspond to Qt objects and properties. Thus, any Qt object
+can potentially be used as an element in QML. More specifically, to make an object available in QML,
+it should:
+\list
+\o Be a subclass of QObject.
+\o Provide a default constructor.
+\o Declare Q_PROPERTYs.
+\o Be registered via the QML_DECLARE_TYPE and QML_DEFINE_TYPE macros.
+\endlist
+
+\section2 Declaring Q_PROPERTYs
+\target properties
+
+Properties of QObject subclasses are available as properties in QML.
+Like any QObject, these properties are defined by the Q_PROPERTY
+macro in the header file.
+
+Properties should have a NOTIFY function if they can change dynamically and
+if any useful response could be made to them changing in another object. Almost
+all properties will thus need a NOTIFY function.
+
+\code
+    Q_PROPERTY(qreal scale READ scale WRITE setScale NOTIFY scaleChanged);
+    qreal scale() const;
+    void setScale(qreal);
+    ...
+    signals: void scaleChanged();
+\endcode
+
+The property types currently supported by QML are:
+\list
+\o int
+\o qreal
+\o QString
+\o QColor
+\o QDate, QTime, and QDateTime
+\o QSize and QSizeF
+\o QPoint and QPointF
+\o QRect and QRectF
+\o QPixmap
+\o QIcon
+\o enums registered with Q_ENUMS
+\o flags registered with Q_FLAGS
+\o QVariant
+\o QObject* (or subclass)
+\endlist
+
+Custom property types that provide string-to-type conversion can be used as well, by:
+\list
+\o Registering them as a metatype (Q_DECLARE_METATYPE() and qRegisterMetaType())
+\o Registering a string-to-type convertor function (QML::addCustomStringConvertor()).
+\endlist
+
+\section2 Registering your type
+\target register
+
+In order for your type to be usable in QML, you must register it:
+
+\code
+QML_DECLARE_TYPE(TypeName);
+QML_DEFINE_TYPE(TypeName,QmlName);
+\endcode
+
+These macros make the C++ \e TypeName available from the declarative markup language under the name \e QmlName.
+Of course there's nothing stopping you using the same name for both the C++ and the QML name!
+
+For example:
+\code
+QML_DECLARE_TYPE(MyCircle);
+QML_DEFINE_TYPE(MyCircle,Circle);
+\endcode
+would make the \e MyCircle class accessable though the \c <Circle/> tag in QML.
+
+
+\section1 Creating a new 'Fx' item in C++
+
+You can create a new type of 'Fx' item by:
+\list 1
+\o Creating a subclass of QFxItem,
+\o Adding Q_PROPERTYs appropriate for your item (see \l {properties}{Properties}),
+\o Reimplementing the relevant paint functions,
+\o Registering the type with the QML_DECLARE_TYPE and QML_DEFINE_TYPE macros  (see \l {register}{Register}).
+\endlist
+
+\section2 Creating a subclass of QFxItem
+
+To add a new type, you first must add a new C++ class derived from QFxItem.
+You may of course extend existing QFxItem subclasses.
+
+One existing subclass is QFxPainted, which provides
+a simple cached-image painting model.
+
+\section2 Reimplementing paint functions
+
+Two alternative painters are available, offering
+different levels of performance and functionality:
+QPainter, GLPainter.
+
+You can choose to subclass QFxPainted rather than QFxItem,
+and then implement the virtual method:
+
+\code
+    void paint(QPainter *painter);
+\endcode
+
+This paints into an offscreen pixmap which is then painted to the display (transformed,
+etc. as needed). The cost of this offscreen pixmap should be carefully considered, as
+should the specific performance of the painting done in the paint function.
+
+If you require more control, subclass QFxItem instead.
+QFxItem subclasses must implement both simple software canvas painting
+and GL painting:
+\list
+\o \c QFxItem::paintContents(QPainter &) for the simple software canvas,
+\o \c QFxItem::paintGLContents(GLPainter &) for OpenGL.
+\endlist
+
+See the documentation of those functions for detailed subclassing notes.
+
+*/