From c9d487b6ed3ac9bb666c2a1fe08252f3c6dcb455 Mon Sep 17 00:00:00 2001 From: Bea Lam Date: Tue, 6 Jul 2010 15:30:33 +1000 Subject: doc improvements --- doc/src/declarative/extending.qdoc | 38 ++++++++++++++++-- doc/src/examples/qml-examples.qdoc | 7 +++- .../ui-components/tabwidget/TabWidget.qml | 7 +++- src/declarative/qml/qdeclarativecomponent.cpp | 30 +++++++++++++++ src/declarative/qml/qdeclarativecontext.cpp | 2 + src/declarative/qml/qdeclarativeexpression.cpp | 24 +++++++++++- .../qml/qdeclarativeextensionplugin.cpp | 4 +- src/declarative/util/qdeclarativepackage.cpp | 4 +- src/declarative/util/qdeclarativeview.cpp | 45 +++++++++++----------- src/declarative/util/qdeclarativexmllistmodel.cpp | 4 +- 10 files changed, 129 insertions(+), 36 deletions(-) diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc index 6476dfb..1ee3574 100644 --- a/doc/src/declarative/extending.qdoc +++ b/doc/src/declarative/extending.qdoc @@ -684,10 +684,6 @@ of some of the types. For the remaining types the default values are undefined. \row \o color \o #000000 (black) \endtable -If specified, the optional "default" attribute marks the new property as the -types default property, overriding any existing default property. Using the -default attribute twice in the same type block is an error. - The following example shows how to declare a new "innerColor" property that controls the color of the inner rectangle. @@ -705,6 +701,40 @@ controls the color of the inner rectangle. } \endcode + +\section3 Setting default properties + +The optional "default" attribute marks a property as the \e {default property} +for a type. This allows other items to specify the default property's value +as child elements. For example, the \l Item element's default property is its +\l{Item::children}{children} property. This allows the children of an \l Item +to be set like this: + +\qml +Item { + Rectangle {} + Rectangle {} +} +\endqml + +If the \l{Item::children}{children} property was not the default property for +\l Item, its value would have to be set like this instead: + +\qml +Item { + children: [ + Rectangle {} + Rectangle {} + ] +} +\endqml + +Specifying a default property overrides any existing default property (for +example, any default property inherited from a parent item). Using the +default attribute twice in the same type block is an error. + + + \target qml-property-aliases \section2 Property aliases diff --git a/doc/src/examples/qml-examples.qdoc b/doc/src/examples/qml-examples.qdoc index c8a7403..dec5441 100644 --- a/doc/src/examples/qml-examples.qdoc +++ b/doc/src/examples/qml-examples.qdoc @@ -196,6 +196,9 @@ \o \l{declarative/cppextensions/qgraphicslayouts/qgraphicsgridlayout}{QGraphicsGridLayout} \o \l{declarative/cppextensions/qgraphicslayouts/qgraphicslinearlayout}{QGraphicsLinearLayout} \endlist + + Also see \l {Integrating QML with existing Qt UI code} for information on using QML + in Qt applications that use the Graphics View framework or ordinary QWidget-based views. */ /*! @@ -608,7 +611,9 @@ \title UI Components: Tab Widget \example declarative/ui-components/tabwidget - This example shows how to create a tab widget. + This example shows how to create a tab widget. It also demonstrates how + \l {Setting default properties}{default properties} can be used to collect and + assemble the child items declared within an \l Item. \image qml-tabwidget-example.png */ diff --git a/examples/declarative/ui-components/tabwidget/TabWidget.qml b/examples/declarative/ui-components/tabwidget/TabWidget.qml index 9642e04..ce57213 100644 --- a/examples/declarative/ui-components/tabwidget/TabWidget.qml +++ b/examples/declarative/ui-components/tabwidget/TabWidget.qml @@ -43,9 +43,14 @@ import Qt 4.7 Item { id: tabWidget - property int current: 0 + // Setting the default property to stack.children means any child items + // of the TabWidget are actually added to the 'stack' item's children. + // See the "Extending Types from QML" documentation for details on default + // properties. default property alias content: stack.children + property int current: 0 + onCurrentChanged: setOpacities() Component.onCompleted: setOpacities() diff --git a/src/declarative/qml/qdeclarativecomponent.cpp b/src/declarative/qml/qdeclarativecomponent.cpp index 9d3032c..6d15278 100644 --- a/src/declarative/qml/qdeclarativecomponent.cpp +++ b/src/declarative/qml/qdeclarativecomponent.cpp @@ -70,6 +70,36 @@ class QByteArray; \since 4.7 \brief The QDeclarativeComponent class encapsulates a QML component description. \mainclass + + Components are reusable, encapsulated QML elements with well-defined interfaces. + They are often defined in \l {qdeclarativedocuments.html}{Component Files}. + + A QDeclarativeComponent instance can be created from a QML file. + For example, if there is a \c main.qml file like this: + + \qml + import Qt 4.7 + + Item { + width: 200 + height: 200 + } + \endqml + + The following code loads this QML file as a component, creates an instance of + this component using create(), and then queries the \l Item's \l {Item::}{width} + value: + + \code + QDeclarativeEngine *engine = new QDeclarativeEngine; + QDeclarativeComponent component(engine, QUrl::fromLocalFile("main.qml")); + + QObject *myObject = component.create(); + QDeclarativeItem *item = qobject_cast(myObject); + int width = item->width(); + \endcode + + \sa {Using QML in C++ Applications} */ /*! diff --git a/src/declarative/qml/qdeclarativecontext.cpp b/src/declarative/qml/qdeclarativecontext.cpp index 60e9dd3..3d25291 100644 --- a/src/declarative/qml/qdeclarativecontext.cpp +++ b/src/declarative/qml/qdeclarativecontext.cpp @@ -145,6 +145,8 @@ QDeclarativeContextPrivate::QDeclarativeContextPrivate() has been created in that context is an expensive operation (essentially forcing all bindings to reevaluate). Thus whenever possible you should complete "setup" of the context before using it to create any objects. + + \sa {Using QML in C++ Applications} */ /*! \internal */ diff --git a/src/declarative/qml/qdeclarativeexpression.cpp b/src/declarative/qml/qdeclarativeexpression.cpp index 8ae5f2f..96cdec1 100644 --- a/src/declarative/qml/qdeclarativeexpression.cpp +++ b/src/declarative/qml/qdeclarativeexpression.cpp @@ -214,8 +214,30 @@ QScriptValue QDeclarativeExpressionPrivate::evalInObjectScope(QDeclarativeContex /*! \class QDeclarativeExpression - \since 4.7 + \since 4.7 \brief The QDeclarativeExpression class evaluates JavaScript in a QML context. + + For example, given a file \c main.qml like this: + + \qml + import Qt 4.7 + + Item { + width: 200; height: 200 + } + \endqml + + The following code evaluates a JavaScript expression in the context of the + above QML: + + \code + QDeclarativeEngine *engine = new QDeclarativeEngine; + QDeclarativeComponent component(engine, QUrl::fromLocalFile("main.qml")); + + QObject *myObject = component.create(); + QDeclarativeExpression *expr = new QDeclarativeExpression(engine->rootContext(), myObject, "width * 2"); + int result = expr->evaluate().toInt(); // result = 400 + \endcode */ /*! diff --git a/src/declarative/qml/qdeclarativeextensionplugin.cpp b/src/declarative/qml/qdeclarativeextensionplugin.cpp index c2e8300..0660599 100644 --- a/src/declarative/qml/qdeclarativeextensionplugin.cpp +++ b/src/declarative/qml/qdeclarativeextensionplugin.cpp @@ -67,10 +67,8 @@ QT_BEGIN_NAMESPACE See \l {Tutorial: Writing QML extensions with C++} for details on creating QML extensions, including how to build a plugin with with QDeclarativeExtensionPlugin. For a simple overview, see the \l{declarative/cppextensions/plugins}{plugins} example. - - Also see \l {How to Create Qt Plugins} for general Qt plugin documentation. - \sa QDeclarativeEngine::importPlugin() + \sa QDeclarativeEngine::importPlugin(), {How to Create Qt Plugins} */ /*! diff --git a/src/declarative/util/qdeclarativepackage.cpp b/src/declarative/util/qdeclarativepackage.cpp index 1e49ad9..1a4f2a7 100644 --- a/src/declarative/util/qdeclarativepackage.cpp +++ b/src/declarative/util/qdeclarativepackage.cpp @@ -65,12 +65,12 @@ QT_BEGIN_NAMESPACE \snippet examples/declarative/modelviews/package/Delegate.qml 0 These named items are used as the delegates by the two views who - reference the special VisualDataModel.parts property to select + reference the special \l{VisualDataModel::parts} property to select a model which provides the chosen delegate. \snippet examples/declarative/modelviews/package/view.qml 0 - \sa {declarative/modelviews/package}{Package example}, QtDeclarative + \sa {declarative/modelviews/package}{Package example}, {demos/declarative/photoviewer}{Photo Viewer demo}, QtDeclarative */ /*! diff --git a/src/declarative/util/qdeclarativeview.cpp b/src/declarative/util/qdeclarativeview.cpp index 12a8d3a..496f2ad 100644 --- a/src/declarative/util/qdeclarativeview.cpp +++ b/src/declarative/util/qdeclarativeview.cpp @@ -194,45 +194,46 @@ void QDeclarativeViewPrivate::itemGeometryChanged(QDeclarativeItem *resizeItem, \since 4.7 \brief The QDeclarativeView class provides a widget for displaying a Qt Declarative user interface. - Any QGraphicsObject or QDeclarativeItem - created via QML can be placed on a standard QGraphicsScene and viewed with a standard - QGraphicsView. + QDeclarativeItem objects can be placed on a standard QGraphicsScene and + displayed with QGraphicsView. QDeclarativeView is a QGraphicsView subclass + provided as a convenience for displaying QML files, and connecting between + QML and C++ Qt objects. - QDeclarativeView is a QGraphicsView subclass provided as a convenience for displaying QML - files, and connecting between QML and C++ Qt objects. - - QDeclarativeView performs the following functions: + QDeclarativeView provides: \list - \o Manages QDeclarativeComponent loading and object creation. - \o Initializes QGraphicsView for optimal performance with QML: + \o Management of QDeclarativeComponent loading and object creation + \o Initialization of QGraphicsView for optimal performance with QML using these settings: \list - \o QGraphicsView::setOptimizationFlags(QGraphicsView::DontSavePainterState); - \o QGraphicsView::setViewportUpdateMode(QGraphicsView::BoundingRectViewportUpdate); - \o QGraphicsScene::setItemIndexMethod(QGraphicsScene::NoIndex); + \o QGraphicsView::setOptimizationFlags(QGraphicsView::DontSavePainterState) + \o QGraphicsView::setViewportUpdateMode(QGraphicsView::BoundingRectViewportUpdate) + \o QGraphicsScene::setItemIndexMethod(QGraphicsScene::NoIndex) \endlist - \o Initializes QGraphicsView for QML key handling: + \o Initialization of QGraphicsView for QML key handling using these settings: \list - \o QGraphicsView::viewport()->setFocusPolicy(Qt::NoFocus); - \o QGraphicsView::setFocusPolicy(Qt::StrongFocus); - \o QGraphicsScene::setStickyFocus(true); + \o QGraphicsView::viewport()->setFocusPolicy(Qt::NoFocus) + \o QGraphicsView::setFocusPolicy(Qt::StrongFocus) + \o QGraphicsScene::setStickyFocus(true) \endlist \endlist Typical usage: - \code - ... - QDeclarativeView *view = new QDeclarativeView(this); - vbox->addWidget(view); - QUrl url = QUrl::fromLocalFile(fileName); - view->setSource(url); + \code + QDeclarativeView *view = new QDeclarativeView; + view->setSource(QUrl::fromLocalFile("myqmlfile.qml")); view->show(); \endcode + Since QDeclarativeView is a QWidget-based class, it can be used to + display QML interfaces within QWidget-based GUI applications that do not + use the Graphics View framework. + To receive errors related to loading and executing QML with QDeclarativeView, you can connect to the statusChanged() signal and monitor for QDeclarativeView::Error. The errors are available via QDeclarativeView::errors(). + + \sa {Integrating QML with existing Qt UI code}, {Using QML in C++ Applications} */ diff --git a/src/declarative/util/qdeclarativexmllistmodel.cpp b/src/declarative/util/qdeclarativexmllistmodel.cpp index 5583007..00169db 100644 --- a/src/declarative/util/qdeclarativexmllistmodel.cpp +++ b/src/declarative/util/qdeclarativexmllistmodel.cpp @@ -667,7 +667,7 @@ QString QDeclarativeXmlListModel::toString(int role) const \qmlproperty url XmlListModel::source The location of the XML data source. - If both source and xml are set, xml will be used. + If both \c source and \l xml are set, \l xml is used. */ QUrl QDeclarativeXmlListModel::source() const { @@ -692,7 +692,7 @@ void QDeclarativeXmlListModel::setSource(const QUrl &src) The text is assumed to be UTF-8 encoded. - If both \l source and \c xml are set, \c xml will be used. + If both \l source and \c xml are set, \c xml is used. */ QString QDeclarativeXmlListModel::xml() const { -- cgit v0.12