/*! 
\page cppitem.html
\target cppitem
\title C++ Components

\section1 Making a C++ object available in QML

In QML, the item types and properties correspond to Qt objects and properties. Thus, any Qt object
can potentially be used as an item 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 type 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.

*/