From 0e0f46c01cf6a183996d36c31987ca4a46b50bd9 Mon Sep 17 00:00:00 2001 From: Bea Lam Date: Thu, 9 Aug 2012 12:07:02 +1000 Subject: Improve main QtQml and QtQuick doc pages Make the content of the two pages more consistent with one another. Also improve the reference documentation sections and fix some links. Also the apireferences.qdoc page is not necessary. Change-Id: I01c5b3757c2ec03b1365e4c9c348e33e06f8315f Reviewed-by: Chris Adams --- src/qml/doc/src/qtqml.qdoc | 82 +++++++++++++-------------------- src/quick/doc/src/apireference.qdoc | 32 ------------- src/quick/doc/src/qmltypereference.qdoc | 6 ++- src/quick/doc/src/qtquick.qdoc | 75 +++++++++++++++--------------- 4 files changed, 76 insertions(+), 119 deletions(-) delete mode 100644 src/quick/doc/src/apireference.qdoc diff --git a/src/qml/doc/src/qtqml.qdoc b/src/qml/doc/src/qtqml.qdoc index efd969c7a9..416d957110 100644 --- a/src/qml/doc/src/qtqml.qdoc +++ b/src/qml/doc/src/qtqml.qdoc @@ -24,6 +24,7 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ + /*! \page qtqml-main.html \title Qt QML Module @@ -31,40 +32,28 @@ \section1 Overview of the Qt QML Module -The Qt QML module provides a framework for developing applications. It defines -and implements the QML language, and provides API which allows clients to -extend the QML language with more types, and to integrate QML code with -JavaScript or C++. - -Application developers who are interested in writing applications using QML -should start by reading the \l{qtquick-applicationdevelopers.html} -{QML Application Developer Resources}. - -\section2 What is QML? - -QML is a user-interface specification and programming language. It was -designed specifically to enable and ease the development of modern, -touch-driven, fluidly animated and visually-appealling applications. - -One of the core goals of QML is to allow closer interaction between designers -and programmers during the development of an application. - -\section2 What Does the Qt QML Module Provide? +The Qt QML module provides a framework for developing applications and +libraries with the QML language. It defines and implements the language +and engine infrastructure, and provides an API to enable application +developers to extend the QML language with custom types and integrate QML code +with JavaScript and C++. -The Qt QML module provides the definition and an implementation of the QML -language. It uses a JavaScript engine to provide JavaScript integration, and -provides C++ API to provide integration with C++. It provides a framework for -object instantiation and manipulation along with strong typing, which can be -integrated with a visual canvas and an animation framework to enable the -development of highly-appealling interactive applications. +The Qt QML module provides both the \c QtQml QML module, which supplies +\l{qtquick-qmltypereference.html}{a set of core QML types} for creating QML +applications, and the QtQml C++ module, which supplies \l{QtQml}{a set of C++ +APIs} for extending QML applications with custom types and integrating C++ +implementations with QML applications. -\section2 What Does the Qt QML Module Not Provide? +Note that the Qt QML module provides only the language and infrastructure +for the QML, and does not provide a visual canvas or rendering engine for +creating user interfaces. These are provided instead by the +\l{qtquick-main.html}{Qt Quick module}, which provides many visual components, +model/view support, an animation framework and much more for building user +interfaces with QML. -It does not provide a visual canvas, visual items, or an animation framework. -These are provided instead by the \l{QtQuick} module. - -Qt Quick can be thought of as the "standard library" of types (including visual -types, animation classes, and canvas integration) for the QML language. +For those new to QML and Qt Quick, please see +\l{qtquick-applicationdevelopers.html}{QML Application Developer Resources} +for an introduction to writing QML applications. \section1 Qt QML Module Documentation @@ -177,27 +166,22 @@ types, animation classes, and canvas integration) for the QML language. \section1 Reference Documentation -More information about the Qt QML module is contained within the class and -function documentation of the \l{QtQml} -{Qt QML Singleton Type Reference}. The QML types provided by the Qt QML module -are listed in the \l{qtqml-typereference-topic.html} -{Qt QML Module QML Type Reference} page. - -Application developers who are interested in writing applications using QML -should start by reading the \l{qtquick-applicationdevelopers.html} -{QML Application Developer Resources}. The documentation for the -\l{qtquick-main.html}{QtQuick} module is also an indispensible resource for -application developers, as it provides the standard library of QML types which -application developers will use in their applications. +Additional Qt QML information: +\list +\li \l{QtQml}{QtQml Module C++ API Reference} - the C++ API provided by the + Qt QML module +\li \l{qtqml-releasenotes.html}{QtQml Release Notes} - list of changes and + additions in the Qt QML module +\endlist -Quick Links: +Further information for writing QML applications: \list -\li \l{qtqml-typereference-topic.html}{Qt QML Module QML Type Reference} -\li \l{QtQml}{Qt QML Module C++ API Reference} -\li \l{qtquick-main.html}{Qt Quick Module Documentation} \li \l{qtquick-applicationdevelopers.html}{QML Application Developer Resources} -\li \l{qtqml-releasenotes.html}{QtQml Release Notes} + - essential information for application development with QML and Qt Quick +\li \l{qtquick-main.html}{Qt Quick Module Documentation} - documentation for + the Qt Quick module, which provides a visual canvas, an animation + framework, model/view components and more for building fluid user + interfaces and applications with QML \endlist - */ diff --git a/src/quick/doc/src/apireference.qdoc b/src/quick/doc/src/apireference.qdoc deleted file mode 100644 index c6c255aaa4..0000000000 --- a/src/quick/doc/src/apireference.qdoc +++ /dev/null @@ -1,32 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qtquick-apireference.html -\title Qt Quick Module API Reference -\brief Description of the C++ API provided by the Qt Quick module -*/ diff --git a/src/quick/doc/src/qmltypereference.qdoc b/src/quick/doc/src/qmltypereference.qdoc index 40191671bb..cdccb27135 100644 --- a/src/quick/doc/src/qmltypereference.qdoc +++ b/src/quick/doc/src/qmltypereference.qdoc @@ -30,8 +30,10 @@ \title QML Types Provided by Qt Quick \brief Description of the QML types provided by the Qt Quick module -This page contains links to documentation for every QML type provided by the -\c QtQuick QML module, organized according to category and purpose. +The \c QtQuick QML module provides a variety of QML types for creating user +interfaces and applications with QML. This page lists every QML type provided +by this module, organized according to category and purpose. + \section1 Importing QtQuick diff --git a/src/quick/doc/src/qtquick.qdoc b/src/quick/doc/src/qtquick.qdoc index bd8071e999..45a4b7684d 100644 --- a/src/quick/doc/src/qtquick.qdoc +++ b/src/quick/doc/src/qtquick.qdoc @@ -1,4 +1,4 @@ -/**************************************************************************** +/**************************************************************************** ** ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/ @@ -32,24 +32,34 @@ \section1 Overview of the Qt Quick Module -The Qt Quick module is the standard library for the QML language (which is -defined and implemented by the \l{qtqml-main.html}{Qt QML module}). -The Qt Quick module provides a visual canvas, visual item types, an animation -framework, and types which make dynamic instantiation of objects more -convenient. It also provides the QQuickView C++ class to enable displaying -a user-interface written in Qt Quick. +The Qt Quick module is the standard library for writing QML applications. +While the \l{qtqml-main.html}{Qt QML module} provides the QML engine and +language infrastructure, the Qt Quick module provides all the basic +elements necessary for creating user interfaces with QML. It +provides a visual canvas and includes types for creating and animating +visual components, receiving user input, creating data models and views +and delayed object instantiation. + +The Qt Quick module provides both the \c QtQuick QML module, which supplies +\l{qtquick-qmltypereference.html}{a set of QML types} for creating user +interfaces with the QML language, and the QtQuick C++ module, which supplies +\l{QtQuick}{a set of C++ APIs} for integrating with user interfaces and +applications built with QML and the \c QtQuick QML module. + +For those new to QML and Qt Quick, please see +\l{qtquick-applicationdevelopers.html}{QML Application Developer Resources} +for an introduction to writing QML applications. -In summary, Qt Quick provides a library of visual types to allow building a -user-interface, and the C++ API to instantiate and interact with it. \section1 Important Concepts in Qt Quick Qt Quick provides everything needed to create a rich application with a fluid -and dynamic user interface. It is based around behavior declaration rather -than imperative programming, and defines a visual canvas with its own -coordinate system and drawing implementation. There are many ways to position -user-interface elements on the screen, and animation and transition effects are -a first-class concept in Qt Quick. +and dynamic user interface. It enables user interfaces to be built around the +behavior of user interface components and how they connect with one another, +and it provides a visual canvas with its own coordinate system and rendering +engine. Animation and transition effects are a first class concept in Qt Quick, +and visual effects can be supplemented through specialised components for +particle and shader effects. \list \li \l{qtquick-visualcanvas-topic.html}{The Visual Canvas} @@ -61,18 +71,18 @@ a first-class concept in Qt Quick. \li \l{qtquick-convenience-topic.html}{Convenience Types} \endlist -When using the QtQuick module, you will need to know how to write QML +When using the \c QtQuick module, you will need to know how to write QML applications using the QML language. In particular, you should have a grasp of the \l{qtquick-quickstart-basics.html}{QML Basics} and \l{qtquick-quickstart-essentials.html}{QML Essentials} from the \l{qtquick-applicationdevelopers.html}{QML Application Developer Resources}. + To find out more about using the QML language, see the \l{Qt QML Module Documentation}. \section1 Qt Quick Module Documentation \list - \li \l{qtquick-qmltypereference.html}{QML Types provided by the QtQuick Module} \list \li \l{qtquick-qmltypereference.html#importing-qtquick}{Importing QtQuick} @@ -100,27 +110,20 @@ To find out more about using the QML language, see the \l{Qt QML Module Document \section1 Reference Documentation -More information about the Qt Quick module is contained within the class and -function documentation of the \l{qtquick-apireference.html} -{Qt Quick Singleton Type Reference}. The QML types provided by the Qt Quick module -are listed in the \l{qtquick-qmltypereference.html} -{Qt Quick Module QML Type Reference} page. - -Application developers who are interested in writing applications using QML -should start by reading the \l{qtquick-applicationdevelopers.html} -{QML Application Developer Resources}. The documentation for the -\l{qtqml-main.html}{Qt QML} module is also an indispensible resource for -application developers who are using Qt Quick, as it provides the definition -and implementation of the QML language (for which Qt Quick is the standard -library of types and functionality). - -Quick Links: +Additional Qt Quick information: \list -\li \l{qtquick-qmltypereference.html}{Qt Quick Module QML Type Reference} -\li \l{qtquick-module.html}{Qt Quick Module C++ API Reference} -\li \l{qtqml-main.html}{Qt QML Module Documentation} -\li \l{qtquick-applicationdevelopers.html}{QML Application Developer Resources} -\li \l{qtquick-releasenotes.html}{QtQuick Release Notes} +\li \l{QtQuick}{QtQuick Module C++ API Reference} - the C++ API provided by the + Qt Quick module +\li \l{qtquick-releasenotes.html}{QtQuick Release Notes} - list of changes and + additions in the Qt Quick module \endlist +Further information for writing QML applications: +\list +\li \l{qtquick-applicationdevelopers.html}{QML Application Developer Resources} + - essential information for application development with QML and Qt Quick +\li \l{qtqml-main.html}{Qt QML Module Documentation} - documentation for the + Qt QML module, which provides the QML engine and language infrastructure +\endlist */ + -- cgit v1.2.3