path: root/src/quick/doc/src/whatsnew.qdoc

/****************************************************************************
**
** 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$
**
****************************************************************************/

/*!
\title Qt Quick Release Notes
\page qtquick-releasenotes.html

\section1 Qt Quick in Qt 5.1

\l{Qt Quick} 2.1 is new in Qt 5.1. This is a summary of improvements and new
features introduced by the new import and new classes in Qt 5.1:
\list
\li New threaded render loop for Mac, Linux, and Embedded.
\li New render loop for windows for smoother animations.
\li New \l Window properties: activeFocusItem, minimumWidth, minimumHeight,
    maximumWidth, maximumHeight, visibility, contentOrientation, and opacity.
\li New \l Screen attached properties: name, desktopAvailableWidth,
    desktopAvailableHeight, logicalPixelDensity
\li New \l Grid properties: horizontalAlignment, verticalAlignment, and
    effectiveHorizontalAlignment.
\li New \l TextEdit properties: selectByKeyboard and textDocument
\li A \l Window declared inside another Window or \l Item will automatically be
    transient for (centered upon) the outer window.
\li These types are now part of \l{Qt QML}:
    \list
    \li \l {VisualItemModel}
    \li \l {VisualDataModel} - Encapsulates a model and a delegate
    \li \l {VisualDataGroup}
    \endlist
    These types are kept due to compatibility reasons and are replaced by the
    \l{Qt QML Models QML Types}{Qt QML Models} types.
\endlist

\section2 New Submodules

In Qt 5.1, there are several new modules which extend Qt Quick functionalities.
\list
\li \l{Qt Quick Dialogs} - contains types for creating and interacting with system dialogs
\li \l{Qt Quick Controls} - provides a set of reusable UI components
\li \l{Qt Quick Layouts} - contains types that are used to arrange items in the user interface
\endlist

The \l{What's New in Qt 5.1} has more information about the Qt 5.1 release.

\section1 Qt Quick in Qt 5.0

The \l {Qt Quick} module is new in Qt 5. It provides the visual canvas and scenegraph back-end
as well as the \c QtQuick QML module for QML application development.

As of Qt 5, the \l {Qt Quick} module is based on an OpenGL scenegraph. Many of the classes in
the \l {Qt Quick} module have been ported from the \l {Qt Quick 1}{QtDeclarative} module from Qt 4.8 to use
the scenegraph architecture; these classes have been renamed to use a \c QQuick* prefix.
(See the \l {Porting QML Applications to Qt 5} for porting information.)

The following classes provide the basic functionality for interacting with the QML visual
canvas from C++:

\list
\li QQuickItem - the base visual QML type (replaces \c QDeclarativeItem)
\li QQuickView - a convenience window for rendering a QML scene from a QML file (replaces \c QDeclarativeView)
\li QQuickWindow - a base window for displaying a QML scene
\li QQuickPaintedItem - convenience for using the QPainter API with the scenegraph
\li QQuickImageProvider - fetches custom images for use in QML applications (replaces \c
    QDeclarativeImageProvider)
\li QQuickTextureFactory - use with QQuickImageProvider::requestTexture()
\endlist

Custom rendering can be performed on the scenegraph using the following new classes:

\list
\li QSGNode
\li QSGMaterial
\li QSGBasicGeometryNode
\li QSGGeometryNode
\li QSGClipNode
\li QSGTransformNode
\li QSGOpacityNode
\li QSGFlatColorMaterial
\li QSGSimpleRectNode
\li QSGSimpleTextureNode
\li QSGTexture
\li QSGDynamicTexture
\li QSGOpaqueTextureMaterial
\li QSGTextureMaterial
\li QSGTextureProvider
\li QSGVertexColorMaterial
\endlist


\section1 Qt 5.0 - QtQuick QML Module

The \c {QtQuick 2.0} QML module is a major update.

Below are the additions in \c {QtQuick 2.0}. For a list of behavioral changes which may affect
applications ported from \c {QtQuick 1.x}, see the \l {Porting QML Applications to Qt 5}.

\section2 Visual types, Graphical Effects and Sprites

\list
\li New \l Canvas type for drawing. This provides an API similar to that of the HTML5 Canvas API,
    along with some additional features.
    \list
    \li Supports two render targets: \c Canvas.Image and \c Canvas.FramebufferObject.
    \li Supports background thread rendering.
    \li Supports tiled canvas rendering.
    \li Supports most of the HTML5 context2d APIs.
    \endlist
\li \l Item:
    \list
    \li New \l{Item::}{layer.enabled} property enables an item to be rendered into an offscreen
        cache for optimization.
    \li New \l{Item::}{contains()} method returns whether an item contains a specified point.
    \li New \l{Item::}{anchors.alignWhenCentered} property can force centered anchors to align on a
        whole pixel.
    \li New \l{Item::}{enabled} property is available, which stops input event delivery and removes active focus.
    \endlist
\li \l Image:
    \list
    \li New \l{Image::}{horizontalAlignment} and \l{Image::}{verticalAlignment} properties to set
        the image alignment.
    \li New \c Image.Pad enumeration value for \l{Image::}{fillMode} that does not transform the image,
        unlike other \l{Image::}{fillMode} enumeration values.
    \endlist
\li New ShaderEffect and ShaderEffectSource types enable GLSL shader programs to be integrated
    directly into QML code and applied to QML items and images. (This obsoletes the experimental
    Qt.labs.shaders module.)
\li New SpriteSequence type renders animated sprites and can transition between animations. Each
    animation in a sequence is represented by the new \l Sprite type.
\li New AnimatedSprite type for drawing single sprite animations.
\endlist


\section2 Animations and Transitions
\list
\li New AnimationController type enables an animation to be manually driven by a
    \l{AnimationController::}{progress} value.
\li New PathAnimation type animates an item along a \l Path.
\li New PathInterpolator type provides updated attribute values for an item animating along a path.
    It can be used as an low-level alternative to PathAnimation.
\li \l Transition:
    \list
    \li New \l{Transition::}{running} property holds whether a transition is currently running.
    \li New \l{Transition::}{enabled} property controls whether a transition is enabled.
    \endlist
\endlist


\section2 Paths
\list
\li New PathArc type creates an arc-type path.
\li New PathCurve type creates a catmull-rom curve path.
\li New PathSvg type creates a path from a SVG string.
\li Changes common to PathLine, PathQuad and PathCubic:
    \list
    \li New \c relativeX and \c relativeY properties define the start and end points of a path
relative to its start.
    \endlist
\li PathCubic only:
    \list
    \li New \l{PathCubic::}{relativeControl1X}, \l{PathCubic::}{relativeControl1Y},
        \l{PathCubic::}{relativeControl2X} and \l{PathCubic::}{relativeControl2Y} properties define the
        positions of the control points relative to the start of the curve.
    \endlist
\li PathQuad only:
    \list
    \li New \l{PathQuad::}{relativeControlX} and \l{PathQuad::}{relativeControlY}
        define the positions of the control points relative to the start of the curve.
    \endlist
\endlist


\section2 Text

\list
\li Changes common to \l Text, TextEdit and TextInput:
    \list
    \li New \c contentWidth and \c contentHeight properties provide the dimensions of the textual
        content.
    \li New \c effectiveHorizontalAlignment property provides the read-only actual horizontal
        alignment.
    \endlist
\li Changes common to both TextEdit and TextInput:
    \list
    \li New \c canUndo and \c canRedo properties specify whether undo and redo operations are
        available.
    \li New \c getText() method returns the text located between specified start and end indexes.
        Additionally TextEdit has a \l{TextEdit::}{getFormattedText()} method that returns the formatted
        text.
    \endlist
\li \l Text only:
    \list
    \li \c Text.RightElide is now supported where text spans multiple lines.
    \li New \l{Text::}{linkColor} property controls the color of linked text.
    \li New \l{Text::}{lineLaidOut} signal is emitted for every line during the layout process to
        give the option of positioning and/or resizing lines as they are laid out.
    \li New \l{Text::}{doLayout()} method will trigger the text layout from Javascript.
    \li New \l{Text::}{fontSizeMode} property allows text to be fitted to the item size.
    \li New \l{Text::}{minimumPixelSize} and \l {Text::}{minimumPointSize} properties can be used to
        specify a lower bound when auto-fitting.
    \endlist
\li TextEdit only:
    \list
    \li New \l{TextEdit::}{baseUrl} property specified the base URL used to resolve relative URLs
        within the text.
    \endlist
\li TextInput only:
    \list
    \li New \l{TextInput::}{wrapMode} property sets the text wrapping mode.
    \li New \l{TextInput::}{horizontalAlignment} and \l{TextInput::}{verticalAlignment} properties.
    \li New \l{TextInput::}{length} property provides the total number of text characters.
    \li New \l{TextInput::}{persistentSelection} property enables the text selection to persist when
the window loses focus.
    \li \l{TextInput::}{positionAt()} method now takes a y parameter.
    \endlist
\endlist

\section2 User Input

\list
\li New MultiPointTouchArea type processes multi-point touches and provides information on touch
    points including position, pressure and velocity. Touch point data is provided by the new \l
    TouchPoint type.
\li New DropArea type provides more advanced drag and drop functionality.
\li MouseArea:
    \list
    \li Wheel events are now supported; events are provided through the new WheelEvent type.
    \li New \l{MouseArea::}{propagateComposedEvents} property sets whether composed events are
        propagated to other mouse areas. If this property is true and the handlers of the
        \l{MouseArea::}{clicked}, \l{MouseArea::}{doubleClicked} or \l{MouseArea::}{pressAndHold}
        signals reject a mouse event, the event will be propagated to overlapping MouseArea items
        in the same area that are lower in the stacking order.
    \li New \l{MouseArea::}{cursorShape} property controls the cursor shape.
        \endlist
\endlist

\section2 Specialized Containers

\list
\li Flickable:
    \list
    \li New \l{Flickable::}{rebound} property specifies the transition to be applied when a
        flickable snaps back to its bounds.
    \li New \l{Flickable::}{topMargin}, \l{Flickable::}{bottomMargin}, \l{Flickable::}{leftMargin},
        \l{Flickable::}{rightMargin} allow extra margin space to be specified for a flickable. This can be
        used, for example, to implement pull-to-refresh functionality for a list.
    \li New \l{Flickable::}{originX} and \l{Flickable::}{originY} properties provide the top left
        position of the content item.
    \li New \l{Flickable::}{dragging}, \l{Flickable::}{draggingHorizontally} and
        \l{Flickable::}{draggingVertically} properties provide information on whether a flickable is
        currently being dragged.
    \li New \l{Flickable::}{flick()} method flicks the view with a specific velocity.
    \li New \l{Flickable::}{cancelFlick()} method stops any current flicking movement.
    \endlist
\endlist

\section2 Positioners (Row, Column, Grid, Flow types):

\list
\li Changes common to \l Row, \l Column, \l Grid and \l Flow:
    \list
    \li The \c add and \c move transitions can access a new ViewTransition attached property (see
        the ViewTransition documentation for examples) and can now animate arbitrary item properties
        (instead of being restricted to animating an item's position).
    \li New \c effectiveLayoutDirection property provides the read-only actual layout direction of a
        positioner.
    \li New \l Positioner type provides \c index, \c isFirstItem and \c isLastItem attached
        properties for items within positioners.
    \li All \c spacing properties on positioners now use real numbers instead of integers.
    \endlist
\li Grid only:
    \list
    \li New \l{Grid::}{rowSpacing} and \l{Grid::}{columnSpacing} properties.
    \endlist
\endlist

\section2 Models and Views

\list
\li Any delegate of a view that uses a QAbstractItemModel-derived model type can use the syntax
    \c {model.<role> = <newDataValue>} to modify the data for a particular role. (Previously,
    the \c {model.<role>} syntax was only available for reading, not writing to, a role value.)
\li ListModel:
    \list
    \li By default, roles can no longer change type during a model's lifetime. The new
        \l{ListModel::}{dynamicRoles} property can be set to restore the original (less performant)
        behavior.
    \endlist
\li VisualDataModel:
    \list
    \li Now has features to filter the items to be displayed in a view. This is supported by the new
        \l {VisualDataModel::}{groups}, \l {VisualDataModel::}{filterOnGroup}, \l {VisualDataModel::}{items}
        and \l {VisualDataModel::}{persistedItems} properties.
    \endlist
\li Changes common to both ListView and GridView:
    \list
    \li New transition support for animating the adding, removing and moving of items in a ListView
        or GridView. See the ViewTransition documentation for details.
    \li New \c verticalLayoutDirection property enables items to be laid out from bottom-to-top
        using the new \c BottomToTop enumeration value.
    \li New \c headerItem and \c footerItem properties provide access to the instantiated header and
        footer items.
    \li The \c cacheBuffer property now has a non-zero default.
    \li Delegates in the cache buffer are now created asynchronously.
    \li Setting a \c RightToLeft layout now also reverses the \c preferredHighlightBegin and \c
        preferredHighlightEnd.
    \li If the model is changed after the component is completed, currentIndex is reset to 0.
    \endlist
\li ListView only:
    \list
    \li New \l{ListView::}{section.labelPositioning} property can fix the current section label to
        the start of the view, and the next section label to the end of the view, to prevent labels from
        scrolling while section items are still in view.
    \li \c highlightMoveSpeed and \c highlightResizeSpeed have been renamed to
        \l{ListView::}{highlightMoveVelocity} and \l{ListView::}{highlightResizeVelocity}.
    \endlist
\li GridView only:
    \list
    \li \l{GridView::}{cellWidth} and \l{GridView::}{cellHeight} now use real numbers instead of
        integers.
    \endlist
\li PathView:
    \list
    \li New \l{PathView::}{currentItem} property holds the current item in the view.
    \li New \l{PathView::}{maximumFlickVelocity} property controls the maximum flick velocity of the
        view.
    \li New \l{PathView::}{snapMode} property controls the snap model when flicking between items
    \li If the model is changed after the component is completed, the offset and currentIndex are
        reset to 0.
    \li New \l{PathView::}{positionViewAtIndex()} function allows the view to be moved to display
        the specified index.
    \li New \l{PathView::}{indexAt()} and \l{PathView::}{itemAt()} functions return the index or
        item at a specified point in the view.
    \endlist
\endlist

\section2 Utility types

\list
\li New \l Accessible attached property for implementing accessibility features in QML applications.
\li \l Loader:
    \list
    \li New \l{Loader::}{asynchronous} property allows components to be instantiated with lower
        chance of blocking.  If source is used with \e {asynchronous: true} the component will be compiled in
        a background thread.
    \li New \l{Loader::}{active} property can delay instantiation of a \l Loader object's
        \l{Loader::}{item}.
    \li New \l{Loader::}{setSource()} method loads an object with specific initial property values,
        similar to \l Component::createObject().
    \endlist
\li \l Binding:
    \list
    \li This type can now be used as a value source, and will also restore any previously set
        binding when its \l{Binding::}{when} clause becomes false.
    \endlist
\endlist

\section2 Property types

Support for various math and geometry-related value types, including QVector2D, QVector3D, QVector4D,
QMatrix4x4 and QQuaternion, as well as QColor and QFont, are now provided by \l {Qt Quick}.  Properties of
these types can be declared in QML documents via the property syntax where the type name is \c vector2d,
\c vector3d, \c vector4d, \c matrix4x4, \c quaternion, \c color and \c font respectively.

\l {Qt Quick} also provides implementation for the various value type factory or utility functions of the
\c Qt object which return or operate on values of the above types.  The functions are:
\table
  \header
  \li Value type
  \li Functions

  \row
  \li color
  \li Qt.rgba(), Qt.hsla(), Qt.tint(), Qt.lighter(), Qt.darker(), Qt.colorEqual()

  \row
  \li font
  \li Qt.font(), Qt.fontFamilies()

  \row
  \li vector2d
  \li Qt.vector2d()

  \row
  \li vector3d
  \li Qt.vector3d()

  \row
  \li vector4d
  \li Qt.vector4d()

  \row
  \li matrix4x4
  \li Qt.matrix4x4()

  \row
  \li quaternion
  \li Qt.quaternion()
\endtable

The \c Qt.rgba(), \c Qt.hsla(), \c Qt.tint(), \c Qt.lighter(), \c Qt.darker()
and \c Qt.fontFamilies() functions already existed in \l {Qt Quick 1}{QtDeclarative} prior
to \l {Qt Quick}{Qt Quick 2}; the other functions are all new in \l {Qt Quick}{Qt Quick 2}.

\section1 Qt 5.0 - Additional QML Modules

\section2 QtQuick.Particles

This new module provides particle system support for creating a variety of 2D particle systems. See
the \l QtQuick.Particles documentation for comprehensive details.

This obsoletes the experimental \c Qt.labs.particles module.

\section2 QtQuick.Window

This new module contains the \l Window type for creating a basic window and the \l Screen type for
accessing a screen's resolution and other details. See the \l QtQuick.Window
documentation for comprehensive details.

\section2 QtQuick.XmlListModel

This new module contains XmlListModel and associated types, which were previously in the \c QtQuick
module. See the \l QtQuick.XmlListModel documentation for details.

\section2 QtQuick.LocalStorage

This new module provides access to the SQL Local Storage API that was previously accessible from the
\l {QML Global Object}. See the \l QtQuick.LocalStorage documentation for details.
*/