path: root/doc/src/declarative/basictypes.qdoc

/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** GNU Free Documentation License
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page qdeclarativebasictypes.html
    \title QML Basic Types

    QML has a set of primitive types, as listed below, that are used throughout
    the \l {QML Elements}.

    Some of these types can also be used for defining 
    \c property values in QML. See \l{Extending types from QML} for the
    list of types that can be used for \c property values.

    \annotatedlist qmlbasictypes
*/

/*!
    \qmlbasictype int
    \ingroup qmlbasictypes

    \brief An integer is a whole number, e.g. 0, 10, or -20. 

    An integer is a whole number, e.g. 0, 10, or -20. The possible \c
    int values range from around -2000000000 to around 2000000000,
    although most elements will only accept a reduced range (which they
    mention in their documentation).

    Example:
    \qml
    Item { width: 100; height: 200 }
    \endqml

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype bool
    \ingroup qmlbasictypes

    \brief A boolean is a binary true/false value.

    A boolean is a binary true/false value.

    Example:
    \qml
    Item { focus: true; clip: false }
    \endqml

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype real
    \ingroup qmlbasictypes

    \brief A real number has a decimal point, e.g. 1.2 or -29.8.

    A real number has a decimal point, e.g. 1.2 or -29.8.

    Example:
    \qml
    Item { width: 100.45; height: 150.82 }
    \endqml

    \note In QML all reals are stored in single precision, \l
    {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point}
    format.

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype string
    \ingroup qmlbasictypes

    \brief A string is a free form text in quotes, e.g. "Hello world!".

    A string is a free form text 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.

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype url
    \ingroup qmlbasictypes

    \brief A URL is a resource locator, like a file name. 

    A URL is a resource locator, like a file name. 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 component where the URL is converted from a JavaScript string
    expression to a url property value.

    Example:
    \qml
    Image { source: "pics/logo.png" }
    \endqml

    \raw HTML
    \endraw

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype color
    \ingroup qmlbasictypes

    \brief A color is a standard color name in quotes.

    A color is a standard color name in quotes. It is normally specified
    as an \l {http://www.w3.org/TR/SVG/types.html#ColorKeywords} {SVG
    color name}. These names include colors like "red", "green" and
    "lightsteelblue".

    If the color you want isn't part of this list, colors can also be
    specified in hexidecimal triplets or quads that take the form \c
    "#RRGGBB" and \c "#AARRGGBB" respectively. For example, the color
    red corresponds to a triplet of \c "#FF0000" and a slightly
    transparent blue to a quad of \c "#800000FF".

    Example:
    \qml
    Rectangle { color: "steelblue" }
    Rectangle { color: "transparent" }
    Rectangle { color: "#FF0000" }
    Rectangle { color: "#800000FF" }
    Rectangle { color: "#00000000" }    // ARGB fully transparent
    \endqml

    Or with the \l{QML:Qt::rgba()}{Qt.rgba()}, \l{QML:Qt::hsla()}{Qt.hsla()}, \l{QML:Qt::darker()}{Qt.darker()},
    \l{QML:Qt::lighter()}{Qt.lighter()} or \l{QML:Qt::tint()}{Qt.tint()} functions:

    \qml
    Rectangle { color: Qt.rgba(255, 0, 0, 1) }
    \endqml

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype point
    \ingroup qmlbasictypes

    \brief A point type has x and y attributes.

    A \c point type has \c x and \c y attributes.

    To create a \c point value, specify it as a "x,y" string:

    \qml
    CustomObject { myPointProperty: "0,20" }
    \endqml

    Or use the \l{QML:Qt::point()}{Qt.point()} function:

    \qml
    CustomObject { myPointProperty: Qt.point(0, 20) }
    \endqml

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype size
    \ingroup qmlbasictypes
    
    \brief A size type has width and height attributes

    A \c size type has \c width and \c height attributes.

    For example, to read the \l {Image::sourceSize} \c size property:

    \qml
    Column {
        Image { id: image; source: "logo.png" }
        Text { text: image.sourceSize.width + "," + image.sourceSize.height }
    }
    \endqml

    To create a \c size value, specify it as a "width x height" string:

    \qml
    LayoutItem { preferredSize: "150x50" }
    \endqml

    Or use the \l{QML:Qt::size()}{Qt.size()} function:

    \qml
    LayoutItem { preferredSize: Qt.size(150, 50) }
    \endqml

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype rect
    \ingroup qmlbasictypes

    \brief A rect type has x, y, width and height attributes.

    A \c rect type has \c x, \c y, \c width and \c height attributes.

    For example, to read the \l {Item::childrenRect.x}{Item::childrenRect} \c rect property:
    \qml
    Rectangle { 
        width: childrenRect.width
        height: childrenRect.height

        Rectangle { width: 100; height: 100 }
    }
    \endqml

    To create a \c rect value, specify it as a "x, y, width x height" string:

    \qml
    CustomObject { myRectProperty: "50,50,100x100" }
    \endqml

    Or use the \l{QML:Qt::rect()}{Qt.rect()} function:

    \qml
    CustomObject { myRectProperty: Qt.rect(50, 50, 100, 100) }
    \endqml

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype date
    \ingroup qmlbasictypes

    \brief A date is specified as "YYYY-MM-DD".

    To create a \c date value, specify it as a "YYYY-MM-DD" string:

    Example:
    \qml
    MyDatePicker { minDate: "2000-01-01"; maxDate: "2020-12-31" }
    \endqml

    To read a date value returned from a C++ extension class, use 
    \l{QML:Qt::formatDate()}{Qt.formatDate()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}.

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype time
    \ingroup qmlbasictypes

    \brief A time is specified as "hh:mm:ss".

    A time is specified as "hh:mm:ss".

    Example:
    \qml
    MyTimePicker { time: "14:22:15" }
    \endqml

    To read a time value returned from a C++ extension class, use 
    \l{QML:Qt::formatTime()}{Qt.formatTime()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}.

    \sa {QML Basic Types}
 */

/*!
    \qmlbasictype font
    \ingroup qmlbasictypes

    \brief A font type has the properties of a QFont.

    A font type has the properties of a QFont. The properties are:

    \list
    \o \c string font.family
    \o \c bool font.bold
    \o \c bool font.italic
    \o \c bool font.underline
    \o \c real font.pointSize
    \o \c int font.pixelSize
    \endlist

    Example:
    \qml
    Text { font.family: "Helvetica"; font.pointSize: 13; font.bold: true }
    \endqml

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype action
    \ingroup qmlbasictypes

    \brief The action type has all the properties of QAction.

    The action type has all the properties of QAction. The properties
    are:

    \list
    \o \c slot action.trigger - invoke the action
    \o \c bool action.enabled - true if the action is enabled
    \o \c string action.text - the text associated with the action
    \endlist

    Actions are used like this:

    \qml
    MouseArea { onClicked: myaction.trigger() }
    State { name: "enabled"; when: myaction.enabled == true }
    Text { text: someaction.text }
    \endqml

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype list
    \ingroup qmlbasictypes

    \brief A list of objects.

    A list of objects. While not technically a basic type, QML also
    supports lists of object types. When used from QML, the engine
    automatically appends each value to the list.

    For example, the \l Item class contains a list property named
    children that can be used like this:

    \qml
    Item {
        children: [
            Item { id: child1 },
            Rectangle { id: child2 },
            Text { id: child3 }
        ]
    }
    \endqml
    \c child1, \c child2 and \c child3 will all be added to the children list
    in the order in which they appear.

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype vector3d
    \ingroup qmlbasictypes

    \brief A vector3d type has x, y, and z attributes.

    A \c vector3d type has \c x, \c y, and \c z attributes.

    To create a \c vector3d value, specify it as a "x,y,z" string:

    \qml
    Rotation { angle: 60; axis: "0,1,0" }
    \endqml

    or with the \l{QML:Qt::vector3d()}{Qt.vector3d()} function:

    \qml
    Rotation { angle: 60; axis: Qt.vector3d(0, 1, 0) }
    \endqml

    or as separate \c x, \c y, and \c z components:

    \qml
    Rotation { angle: 60; axis.x: 0; axis.y: 1; axis.z: 0 }
    \endqml

    \sa {QML Basic Types}
*/

/*!
    \qmlbasictype enumeration
    \ingroup qmlbasictypes

    \brief An enumeration type consists of a set of named values.

    An enumeration type consists of a set of named values.

    An enumeration value may be specifed as either a string:
    \qml
    Text { horizontalAlignment: "AlignRight" }
    \endqml
    
    or as \c {<Element>.<value>}:
    \qml
    Text { horizontalAlignment: Text.AlignRight }
    \endqml

    The second form is preferred.

    \sa {QML Basic Types}
*/