diff options
Diffstat (limited to 'doc/src/declarative/qmlreusablecomponents.qdoc')
| -rw-r--r-- | doc/src/declarative/qmlreusablecomponents.qdoc | 143 |
1 files changed, 143 insertions, 0 deletions
diff --git a/doc/src/declarative/qmlreusablecomponents.qdoc b/doc/src/declarative/qmlreusablecomponents.qdoc new file mode 100644 index 0000000..ee360eb --- /dev/null +++ b/doc/src/declarative/qmlreusablecomponents.qdoc @@ -0,0 +1,143 @@ +/**************************************************************************** +** +** 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$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** 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 qmlreusablecomponents.html +\ingroup qml-features +\previouspage {QML Signal and Handler Event System}{Signal and Handler Event System} +\nextpage {QML States}{States} +\contentspage QML Features + +\title Importing Reusable Components + +A \e component is an instantiable QML definition, typically contained in a +\c .qml file. For instance, a Button \e component may be defined in +\c Button.qml. The QML runtime may instantiate this Button component to create +Button \e objects. Alternatively, a component may be defined inside a +\l Component element. + +Moreover, the Button definition may also contain other components. A Button +component could use a Text element for its label and other components to +implement its functions. Compounding components to form new components +(and effectively new interfaces) is the emphasis in QML. + +\keyword qml-define-components +\section1 Defining New Components + +Any snippet of QML code may become a component, by placing the code in a QML +file (extension is \c .qml). A complete Button component that responds to user +input may be in a Button.qml file. +\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml document + +Alternatively, a \l Component element may encapsulate a QML object to form a +component. +\snippet doc/src/snippets/declarative/reusablecomponents/component.qml parent begin +\snippet doc/src/snippets/declarative/reusablecomponents/component.qml define inline component +\snippet doc/src/snippets/declarative/reusablecomponents/component.qml parent end + +\keyword qml-loading-components +\section1 Loading a Component + +The initialization of inline components is different from loading a component +from a \c .qml file. + +\section2 Importing a Component + +A component defined in a \c .qml file is directly usable by declaring the name +of the component. For example, a button defined in \c Button.qml is created by +declaring a \c Button. The button is defined in the +\l {qml-define-components}{Defining New Components} section. +\snippet doc/src/snippets/declarative/reusablecomponents/application.qml document + +Note that the component name, \c Button, matches the QML filename, \c Button.qml. +Also, the first character is in upper case. Matching the names allow +components in the same directory to be in the direct import path of the +application. + +For flexibility, a \c qmldir file is for dictating which additional components, +plugins, or directories should be imported. By using a \c qmldir file, +component names do not need to match the filenames. The \c qmldir file should, +however, be in an imported path. +\snippet doc/src/snippets/declarative/reusablecomponents/qmldir document + +\section2 Loading an Inline Component + +A consequence of inline components is that initialization may be deferred or +delayed. A component may be created during a MouseArea event or by using a +\l Loader element. The component can create an object, which is addressable in a +similar way as an \l {qml-id-property}{id property}. Thus, the created object may +have its bindings set and read like a normal QML object. +\snippet doc/src/snippets/declarative/reusablecomponents/component.qml define inline component +\snippet doc/src/snippets/declarative/reusablecomponents/component.qml create inline component + +\keyword qml-component-properties +\section1 Component Properties + +Initializing a component, either from a .qml file or initializing an inline +component, have several properties to facilitate component execution. +Specifically, there are \l{attached-properties}{attached properties} and +\l{attached-signalhandlers}{attached signal handlers} for setting properties +during the lifetime of a component. + +The \c{Component.onCompleted} attached signal handler is called when the +component completes initialization. It is useful for executing any commands +after component initialization. Similarly, the \c{Component.onDestruction} +signal handler executes when the component finishes destruction. + +\keyword qml-top-level +\section1 Top-Level Component + +Choosing the \e{top-level} or the \e{root} object of components is an important +design aspect because the top-level object dictates which properties are +accessible outside the component. Some elements are not visual elements and +will not have visual properties exposed outside the component. Likewise, some +elements add functionality that are not available to visual elements. + +Consider the Button component from the +\l{qml-define-components}{Defining New Components} section; it's top-level +object is a \l Rectangle. When imported, the Button component will possess the +Rectangle's properties, methods, signals, and any custom properties. + +\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml parent begin +\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml ellipses +\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml properties +\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml ellipses +\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml parent end + +The Button's \c text alias is accessible from outside the component as well as +the Rectangle's visual properties and signals such as \c x, \c y, \c anchors, +and \c states. + +Alternatively, we may choose a \l {Keyboard Focus in QML}{FocusScope} as our +top-level object. The \l FocusScope element manage keyboard focus for its +children which is beneficial for certain types of interfaces. However, since +\c FocusScopes are not visual elements, the visual properties of its child need +to be exposed. + +\snippet doc/src/snippets/declarative/reusablecomponents/focusbutton.qml document +*/ + |