diff options
Diffstat (limited to 'doc/src/qml/qmlcomponents.qdoc')
| -rw-r--r-- | doc/src/qml/qmlcomponents.qdoc | 194 |
1 files changed, 0 insertions, 194 deletions
diff --git a/doc/src/qml/qmlcomponents.qdoc b/doc/src/qml/qmlcomponents.qdoc deleted file mode 100644 index b423ea97df..0000000000 --- a/doc/src/qml/qmlcomponents.qdoc +++ /dev/null @@ -1,194 +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 qml-components.html -\ingroup qml-features -\contentspage QML Reference - -\title QML Components -\brief creating and instantiating 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 -file. The \l{The QML Engine}{QML engine} 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 might have a Text element for its label and other components to -implement its functions. Compounding components to form new components -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, whose 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/qml/reusablecomponents/Button.qml document - -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. The section on \l{Importing a Component} has information about -naming components with different filenames. - -Alternatively, a \l Component element may encapsulate a QML object to form a -component. -\snippet doc/src/snippets/qml/reusablecomponents/component.qml parent begin -\snippet doc/src/snippets/qml/reusablecomponents/component.qml define inline component -\snippet doc/src/snippets/qml/reusablecomponents/component.qml parent end - - -Components may incorporate any \l{Qt Quick}{QML feature} such as: -\list -\li \l{Property Binding in QML}{Properties} - for binding to data and functions -\li \l{JavaScript Expressions in QML}{JavaScript functions} - for performing routines and logic -\li \l{QML Signal and Handler Event System}{Signals and handlers} - t notify other -objects about events -\li \l{States} and \l{QML Animation and Transitions}{Transitions} -\li many others -\endlist -For information about these features, visit the respective overviews or the -main Qt Quick \l{Qt Quick}{reference} page. - -\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/qml/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/qml/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}{identifier}. Thus, the created object may -have its bindings set and read like a normal QML object. -\snippet doc/src/snippets/qml/reusablecomponents/component.qml define inline component -\snippet doc/src/snippets/qml/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/qml/reusablecomponents/Button.qml parent begin -\snippet doc/src/snippets/qml/reusablecomponents/Button.qml ellipses -\snippet doc/src/snippets/qml/reusablecomponents/Button.qml properties -\snippet doc/src/snippets/qml/reusablecomponents/Button.qml ellipses -\snippet doc/src/snippets/qml/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/qml/reusablecomponents/focusbutton.qml document - -\keyword qml-id -\section2 The Object Identifier - -Each QML object may be given a special unique identifier called an \c id. -No other object within the same QML component (see \l{QML Documents}) can have -the same \c id value. QML objects may then access an object using the \c id -property. -\snippet doc/src/snippets/qml/properties.qml id property -A component may readily access its parent's properties by using the \c parent -property. - -Note that an \c id must begin with a lower-case letter or an underscore. The -\c id cannot contain characters other than letters, numbers, underscores, and -\l {JavaScript Reserved Words}{JavaScript reserved words}. - -\section2 Child Components - -Objects or Items declared within a component can be made accessible by binding their id to a -property alias. - -\snippet doc/src/snippets/qml/reusablecomponents/Button.qml parent begin -\snippet doc/src/snippets/qml/reusablecomponents/Button.qml object alias -\snippet doc/src/snippets/qml/reusablecomponents/Button.qml text -\snippet doc/src/snippets/qml/reusablecomponents/Button.qml parent end - -The advantage of using an alias instead a property of type of the object is that the value of -the alias cannot be overridden, and members of the object can be used in property bindings when -declaring an instance of the component. -\snippet doc/src/snippets/qml/reusablecomponents/application.qml grouped property -If a property of type \c Text was used instead of an alias in this instance there would be no -guarantee that \c label would be initialized before the binding was attempted which would cause -the binding to fail. -*/ - |