Doc: Refactored and focused the Qt QML documentation.

Before it wasn't clear to what the module provided, especially
with the coupling of Qt QML and Qt Quick.

The doc is centered around these documentation:
-QML refernce: the language syntax and the application constructs
-JavaScript environment: the environment provided by the module
-Integration with C++: more about the engine and the C++ API
-QML Types and Classes reference (created by \qmlmodule and \module)

The distinction are made in the directory and the section titles in
the Qt QML landing page.

Change-Id: I033bfcbf8368b94ffa5ee4b1225bee74347f53eb
Reviewed-by: Martin Smith <martin.smith@digia.com>

1 files changed, 675 insertions, 0 deletions

diff --git a/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc b/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc
new file mode 100644
index 0000000000..6f468d42bc
--- /dev/null
+++ b/src/qml/doc/src/qmllanguageref/typesystem/basictypes.qdoc
@@ -0,0 +1,675 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+\page qtqml-typesystem-basictypes.html
+\title QML Basic Types
+\brief Description of basic types provided by the Qt QML module
+
+QML supports a number of basic types.
+
+A \e{basic type} is one that refers to a simple value, such as an \c int
+or a \c string. This contrasts with a \l{qtqml-typesystem-topic.html#qml-object-types}{QML Object Types},
+which refers to an object with properties, signals, methods and so on. Unlike an object type,
+a basic type cannot be used to declare QML objects: it is not possible, for example, to declare an
+\c int{} object or a \c size{} object.
+
+Basic types can be used to refer to:
+
+\list
+\li A single value (e.g. \l int refers to a single number, \l var can refer to a single list of items)
+\li A value that contains a simple set of property-value pairs (e.g. \l size refers to a value with \c width and \c height attributes)
+\endlist
+
+\sa {qtqml-typesystem-topic.html}{The QML Type System}
+
+
+\section1 Supported Basic Types
+
+Some basic types are supported by the engine by default and do not require an
+\l {Import Statements}{import statement} to be used, while others do require
+the client to import the module which provides them.
+All of the basic types listed below may be used as a \c property type in a QML
+document, with the following exceptions:
+\list
+  \li \c list must be used in conjunction with a QML object type
+  \li \c enumeration cannot be used directly as the enumeration must be defined by a registered QML object type
+\endlist
+
+\section2 Basic Types Provided By The QML Language
+
+The basic types supported natively in the QML language are listed below:
+\annotatedlist qmlbasictypes
+
+\section2 Basic Types Provided By QML Modules
+
+QML modules may extend the QML language with more basic types.
+For example, the basic types provided by the QtQuick module are listed below:
+\annotatedlist qtquickbasictypes
+
+Currently only QML modules which are provided by Qt may provide their
+own basic types, however this may change in future releases of Qt QML.
+In order to use types provided by a particular QML module, clients
+must import that module in their QML documents.
+
+\section1 Property Change Behavior for Basic Types
+
+Some basic types have properties: for example, the \l font type has
+\c pixelSize, \c family and \c b properties. Unlike properties of
+\l{qtqml-typesystem-topic.html#qml-object-types}{object types}, properties of
+basic types do not provide their own property change signals. It is only possible
+to create a property change signal handler for the basic type property itself:
+
+\code
+Text {
+    // invalid!
+    onFont.pixelSizeChanged: doSomething()
+
+    // also invalid!
+    font {
+        onPixelSizeChanged: doSomething()
+    }
+
+    // but this is ok
+    onFontChanged: doSomething()
+}
+\endcode
+
+Be aware, however, that a property change signal for a basic type is emitted
+whenever \e any of its attributes have changed, as well as when the property itself
+changes. Take the following code, for example:
+
+\qml
+Text {
+    onFontChanged: console.log("font changed")
+
+    Text { id: otherText }
+
+    focus: true
+
+    // changing any of the font attributes, or reassigning the property
+    // to a different font value, will invoke the onFontChanged handler
+    Keys.onDigit1Pressed: font.pixelSize += 1
+    Keys.onDigit2Pressed: font.b = !font.b
+    Keys.onDigit3Pressed: font = otherText.font
+}
+\endqml
+
+In contrast, properties of an \l{qtqml-typesystem-topic.html#qml-object-types}{object type}
+emit their own property change signals, and a property change signal handler for an object-type
+property is only invoked when the property is reassigned to a different object value.
+
+*/
+
+/*!
+    \qmlbasictype int
+    \ingroup qmlbasictypes
+    \brief a whole number, e.g. 0, 10, or -20.
+
+    The \c int type refers to a whole number, e.g. 0, 10, or -20.
+
+    The possible \c int values range from around -2000000000 to around 2000000000,
+    although most types will only accept a reduced range (which they
+    mention in their documentation).
+
+    Example:
+    \qml
+    Item { width: 100; height: 200 }
+    \endqml
+
+    This basic type is provided by the QML language.
+
+    \sa {QML Basic Types}
+*/
+
+/*!
+    \qmlbasictype bool
+    \ingroup qmlbasictypes
+    \brief a binary true/false value.
+
+    The \c bool type refers to a binary true/false value.
+
+    Example:
+    \qml
+    Item {
+        focus: true
+        clip: false
+    }
+    \endqml
+
+    This basic type is provided by the QML language.
+
+    \sa {QML Basic Types}
+*/
+
+/*!
+    \qmlbasictype real
+    \ingroup qmlbasictypes
+
+    \brief a number with a decimal point.
+
+    The \c real type refers to a number with decimal point, e.g. 1.2 or -29.8.
+
+    Example:
+    \qml
+    Item { width: 100.45; height: 150.82 }
+    \endqml
+
+    \b{Note:} In QML all reals are stored in double precision, \l
+    {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point}
+    format.
+
+    This basic type is provided by the QML language.
+
+    \sa {QML Basic Types}
+*/
+
+/*!
+    \qmlbasictype double
+    \ingroup qmlbasictypes
+
+    \brief a number with a decimal point, stored in double precision.
+
+    The \c double type refers to a number with a decimal point and is stored in double precision, \l
+    {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point} format.
+
+    Example:
+    \qml
+    Item {
+        property double number: 32155.2355
+    }
+    \endqml
+
+    This basic type is provided by the QML language.
+
+    \sa {QML Basic Types}
+*/
+
+/*!
+    \qmlbasictype string
+    \ingroup qmlbasictypes
+    \brief a free form text string.
+
+    The \c string type refers to a free form text string in quotes, e.g. "Hello world!".
+
+    Example:
+    \qml
+    Text { text: "Hello world!" }
+    \endqml
+
+    Strings have a \c length attribute that holds the number of
+    characters in the string.
+
+    QML extends the JavaScript String type with a \l {String::arg}{arg()} function
+    to support value substitution.
+
+    When integrating with C++, note that any QString value
+    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
+    converted into a \c string value, and vice-versa.
+
+    This basic type is provided by the QML language.
+
+    \sa {QML Basic Types}
+*/
+
+/*!
+    \qmlbasictype url
+    \ingroup qmlbasictypes
+    \brief a resource locator.
+
+    The \c url type refers to a resource locator (like a file name, for example). It can be either
+    absolute, e.g. "http://qt.nokia.com", or relative, e.g.  "pics/logo.png". A relative URL is
+    resolved relative to the URL of the containing component.
+
+    For example, the following assigns a valid URL to the \l {Image::source}
+    property, which is of type \c url:
+
+    \qml
+    Image { source: "pics/logo.png" }
+    \endqml
+
+    When integrating with C++, note that any QUrl value
+    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
+    converted into a \c url value, and vice-versa.
+
+
+    \section1 Using the url Type
+
+    When a relative URL is written to a \c url type property, it is converted
+    into a URL object, so \b {matching the URL value against the input string
+    value will fail}. Instead, convert the string to a URL using Qt.resolvedUrl()
+    for means of comparison, and use \c toString() to get the contents of the URL:
+
+    \qml
+    Image {
+        source: "pics/logo.png"
+
+        Component.onCompleted: {
+            // This prints 'false'. Although "pics/logo.png" was the input string,
+            // it's been converted from a string to a URL, so these two are not the same.
+            console.log(source == "pics/logo.png")
+
+            // This prints 'true' as Qt.resovledUrl() converts the string into a
+            // URL with the correctly resolved path
+            console.log(source == Qt.resolvedUrl("pics/logo.png"))
+
+            // This prints the absolute path, e.g. "file:///path/to/pics/logo.png"
+            console.log(source.toString())
+        }
+    }
+    \endqml
+
+    \note When referring to files stored with the \l{resources.html}{Qt Resource System}
+    from within QML, you should use "qrc:///" instead of ":/" as QML requires URL paths.
+    Relative URLs resolved from within that file will use the same protocol.
+
+    Additionally, URLs may contain encoded characters using the 'percent-encoding' scheme
+    specified by \l {http://tools.ietf.org/html/rfc3986}{RFC 3986}.  These characters
+    will be preserved within properties of type \c url, to allow QML code to
+    construct precise URL values. An exception to this rule is the preemptive
+    decoding of directory-separator characters (\c '/') - these characters are decoded
+    to allow the URL to be correctly classified.
+
+    For example, a local file containing a '#' character, which would normally be
+    interpreted as the beginning of the URL 'fragment' element, can be accessed by
+    encoding the characters of the file name:
+
+    \qml
+    Image { source: encodeURIComponent("/tmp/test#1.png") }
+    \endqml
+
+    This basic type is provided by the QML language.
+
+    \sa {QML Basic Types}
+*/
+
+
+/*!
+    \qmlbasictype list
+    \ingroup qmlbasictypes
+    \brief a list of QML objects.
+
+    The \c list type refers to a list of QML objects.
+
+    A list value can be accessed in a similar way to a JavaScript array:
+
+    \list
+    \li Values are assigned using the \c[] square bracket syntax with comma-separated values
+    \li The \c length property provides the number of items in the list
+    \li Values in the list are accessed using the \c [index] syntax
+    \endlist
+
+    A \c list can only store QML objects, and cannot contain any
+    \l {QML Basic Types}{basic type} values. (To store basic types within a
+    list, use the \l var type instead.)
+
+    When integrating with C++, note that any QQmlListProperty value
+    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
+    converted into a \c list value, and vice-versa.
+
+
+    \section1 Using the list Type
+
+    For example, the \l Item type has a \l {Item::}{states} list-type property that
+    can be assigned to and used as follows:
+
+    \qml
+    import QtQuick 2.0
+
+    Item {
+        width: 100; height: 100
+
+        states: [
+            State { name: "activated" },
+            State { name: "deactivated" }
+        ]
+
+        Component.onCompleted: {
+            console.log("Name of first state:", states[0].name)
+            for (var i = 0; i < states.length; i++)
+                console.log("state", i, states[i].name)
+        }
+    }
+    \endqml
+
+    The defined \l State objects will be added to the \c states list
+    in the order in which they are defined.
+
+    If the list only contains one object, the square brackets may be omitted:
+
+    \qml
+    import QtQuick 2.0
+
+    Item {
+        width: 100; height: 100
+        states: State { name: "activated" }
+    }
+    \endqml
+
+    Note that objects cannot be individually added to or removed from
+    the list once created; to modify the contents of a list, it must be
+    reassigned to a new list.
+
+    \note The \c list type is not recommended as a type for custom properties.
+    The \c var type should be used instead for this purpose as
+    lists stored by the \c var type can be manipulated with greater
+    flexibility from within QML.
+
+    This basic type is provided by the QML language.
+
+    \sa {QML Basic Types}
+*/
+
+ /*!
+    \qmlbasictype var
+    \ingroup qmlbasictypes
+    \brief a generic property type.
+
+    The \c var type is a generic property type that can refer to any data type.
+
+    It is equivalent to a regular JavaScript variable.
+    For example, var properties can store numbers, strings, objects,
+    arrays and functions:
+
+    \qml
+    Item {
+        property var aNumber: 100
+        property var aBool: false
+        property var aString: "Hello world!"
+        property var anotherString: String("#FF008800")
+        property var aColor: Qt.rgba(0.2, 0.3, 0.4, 0.5)
+        property var aRect: Qt.rect(10, 10, 10, 10)
+        property var aPoint: Qt.point(10, 10)
+        property var aSize: Qt.size(10, 10)
+        property var aVector3d: Qt.vector3d(100, 100, 100)
+        property var anArray: [1, 2, 3, "four", "five", (function() { return "six"; })]
+        property var anObject: { "foo": 10, "bar": 20 }
+        property var aFunction: (function() { return "one"; })
+    }
+    \endqml
+
+    \section1 Change Notification Semantics
+
+    It is important to note that changes in regular properties of JavaScript
+    objects assigned to a var property will \b{not} trigger updates of bindings
+    that access them.  The example below will display "The car has 4 wheels" as
+    the change to the wheels property will not cause the reevaluation of the
+    binding assigned to the "text" property:
+
+    \qml
+    Item {
+        property var car: new Object({wheels: 4})
+
+        Text {
+            text: "The car has " + car.wheels + " wheels";
+        }
+
+        Component.onCompleted: {
+            car.wheels = 6;
+        }
+    }
+    \endqml
+
+    If the onCompleted handler instead had \tt{"car = new Object({wheels: 6})"}
+    then the text would be updated to say "The car has 6 wheels", since the
+    car property itself would be changed, which causes a change notification
+    to be emitted.
+
+    \section1 Property Value Initialization Semantics
+
+    The QML syntax defines that curly braces on the right-hand-side of a
+    property value initialization assignment denote a binding assignment.
+    This can be confusing when initializing a \c var property, as empty curly
+    braces in JavaScript can denote either an expression block or an empty
+    object declaration.  If you wish to initialize a \c var property to an
+    empty object value, you should wrap the curly braces in parentheses.
+
+    For example:
+    \qml
+    Item {
+        property var first:  {}   // nothing = undefined
+        property var second: {{}} // empty expression block = undefined
+        property var third:  ({}) // empty object
+    }
+    \endqml
+
+    In the previous example, the \c first property is bound to an empty
+    expression, whose result is undefined.  The \c second property is bound to
+    an expression which contains a single, empty expression block ("{}"), which
+    similarly has an undefined result.  The \c third property is bound to an
+    expression which is evaluated as an empty object declaration, and thus the
+    property will be initialized with that empty object value.
+
+    Similarly, a colon in JavaScript can be either an object property value
+    assignment, or a code label.  Thus, initializing a var property with an
+    object declaration can also require parentheses:
+
+    \qml
+    Item {
+        property var first: { example: 'true' }    // example is interpreted as a label
+        property var second: ({ example: 'true' }) // example is interpreted as a property
+        property var third: { 'example': 'true' }  // example is interpreted as a property
+        Component.onCompleted: {
+            console.log(first.example) // prints 'undefined', as "first" was assigned a string
+            console.log(second.example) // prints 'true'
+            console.log(third.example) // prints 'true'
+        }
+    }
+    \endqml
+
+    \sa {QML Basic Types}
+*/
+/*
+ TODO Qt 5.1: see explanation in expressions.qdoc
+     \section1 Using Scarce Resources with the var Type
+
+    A \c var type property can also hold an image or pixmap.
+    A \c var which contains a QPixmap or QImage is known as a
+    "scarce resource" and the declarative engine will attempt to
+    automatically release such resources after evaluation of any JavaScript
+    expression which requires one to be copied has completed.
+
+    Clients may explicitly release such a scarce resource by calling the
+    "destroy" method on the \c var property from within JavaScript.  They
+    may also explicitly preserve the scarce resource by calling the
+    "preserve" method on the \c var property from within JavaScript.
+    For more information regarding the usage of a scarce resource, please
+    see \l{Scarce Resources in JavaScript}.
+
+    This basic type is provided by the QML language.
+*/
+
+/*!
+    \obsolete
+    \qmlbasictype variant
+    \ingroup qmlbasictypes
+    \brief a generic property type.
+
+    The \c variant type is a generic property type. It is obsolete and exists only to
+    support old applications; new applications should use \l var type
+    properties instead.
+
+    A variant type property can hold any of the \l {QML Basic Types}{basic type}
+    values:
+
+    \qml
+    Item {
+        property variant aNumber: 100
+        property variant aString: "Hello world!"
+        property variant aBool: false
+    }
+    \endqml
+
+    When integrating with C++, note that any QVariant value
+    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
+    converted into a \c variant value, and vice-versa.
+
+
+    \section1 Using Scarce Resources with the variant Type
+
+    A \c variant type property can also hold an image or pixmap.
+    A \c variant which contains a QPixmap or QImage is known as a
+    "scarce resource" and the declarative engine will attempt to
+    automatically release such resources after evaluation of any JavaScript
+    expression which requires one to be copied has completed.
+
+    Clients may explicitly release such a scarce resource by calling the
+    "destroy" method on the \c variant property from within JavaScript.  They
+    may also explicitly preserve the scarce resource by calling the
+    "preserve" method on the \c variant property from within JavaScript.
+    For more information regarding the usage of a scarce resource, please
+    see \l{Scarce Resources in JavaScript}.
+
+    \section1 Storing Arrays and Objects
+
+    The \c variant type can also hold:
+
+    \list
+    \li An array of \l {QML Basic Types}{basic type} values
+    \li A map of key-value pairs with \l {QML Basic Types}{basic-type} values
+    \endlist
+
+    For example, below is an \c items array and an \c attributes map. Their
+    contents can be examined using JavaScript \c for loops. Individual array
+    values are accessible by index, and individual map values are accessible
+    by key:
+
+    \qml
+    Item {
+        property variant items: [1, 2, 3, "four", "five"]
+        property variant attributes: { 'color': 'red', 'width': 100 }
+
+        Component.onCompleted: {
+            for (var i = 0; i < items.length; i++)
+                console.log(items[i])
+
+            for (var prop in attributes)
+                console.log(prop, "=", attributes[prop])
+        }
+    }
+    \endqml
+
+    While this is a convenient way to store array and map-type values, you
+    must be aware that the \c items and \c attributes properties above are \e not
+    QML objects (and certainly not JavaScript object either) and the key-value
+    pairs in \c attributes are \e not QML properties. Rather, the \c items
+    property holds an array of values, and \c attributes holds a set of key-value
+    pairs. Since they are stored as a set of values, instead of as an object,
+    their contents \e cannot be modified individually:
+
+    \qml
+    Item {
+        property variant items: [1, 2, 3, "four", "five"]
+        property variant attributes: { 'color': 'red', 'width': 100 }
+
+        Component.onCompleted: {
+            items[0] = 10
+            console.log(items[0])     // This will still be '1'!
+            attributes.color = 'blue'
+            console.log(attributes.color)     // This will still be 'red'!
+        }
+    }
+    \endqml
+
+    Since it is not possible to individually add or remove items from a list or
+    object stored in a \c variant, the only way to modify its contents is to
+    reassign a new value. However, this is not efficent, as it causes the value
+    to be serialized and deserialized.
+
+    Additionally, since \c items and \c attributes are not QML objects, changing
+    their individual values do not trigger property change notifications. If
+    the above example had \c onNumberChanged or \c onAnimalChanged signal
+    handlers, they would not have been called.  If, however, the \c items or
+    \c attributes properties themselves were reassigned to different values, then
+    such handlers would be called.
+
+    JavaScript programmers should also note that when a JavaScript object is
+    copied to an array or map property, the \e contents of the object (that is,
+    its key-value properties) are copied, rather than the object itself. The
+    property does not hold a reference to the original JavaScript object, and
+    extra data such as the object's JavaScript prototype chain is also lost in
+    the process.
+
+    This basic type is provided by the QML language.
+
+    \sa {QML Basic Types}
+*/
+
+/*!
+    \qmlbasictype enumeration
+    \ingroup qmlbasictypes
+    \brief a named enumeration value.
+
+    The \c enumeration type refers to a named enumeration value.
+
+    Each named value can be referred to as \c {<Type>.<value>}. For
+    example, the \l Text type has an \c AlignRight enumeration value:
+
+    \qml
+    Text { horizontalAlignment: Text.AlignRight }
+    \endqml
+
+    (For backwards compatibility, the enumeration value may also be
+    specified as a string, e.g. "AlignRight". This form is not
+    recommended for new code.)
+
+    When integrating with C++, note that any \c enum value
+    \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically
+    converted into an \c enumeration value, and vice-versa.
+
+    This basic type is provided by the QML language.  Some enumeration values
+    are provided by the QtQuick import.
+
+    \section1 Using the enumeration type in QML
+
+    The \c enumeration type is a representation of a C++ \c enum type. It is
+    not possible to refer to the \c enumeration type in QML itself; instead, the
+    \l int or \l var types can be used when referring to \c enumeration values
+    from QML code.
+
+    For example:
+
+    \qml
+    import QtQuick 2.0
+
+    Item {
+        // refer to Text.AlignRight using an int type
+        property int enumValue: textItem.horizontalAlignment
+
+        signal valueEmitted(int someValue)
+
+        Text {
+            id: textItem
+            horizontalAlignment: Text.AlignRight
+        }
+
+        // emit valueEmitted() signal, which expects an int, with Text.AlignRight
+        Component.onCompleted: valueEmitted(Text.AlignRight)
+    }
+    \endqml
+
+    \sa {QML Basic Types}
+*/