diff options
Diffstat (limited to 'doc')
5 files changed, 264 insertions, 17 deletions
diff --git a/doc/src/declarative/qmlreusablecomponents.qdoc b/doc/src/declarative/qmlreusablecomponents.qdoc index 0d02f4d..0fd5515 100644 --- a/doc/src/declarative/qmlreusablecomponents.qdoc +++ b/doc/src/declarative/qmlreusablecomponents.qdoc @@ -45,35 +45,71 @@ 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). An inline component definition may also reside in a -\l Component element. - +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 -For example, one of the simplest and most common components you can build in QML is a -button-type component. Below, we implement this component as a \l Rectangle with a clickable -\l MouseArea, in a file named \c Button.qml: +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 -\snippet doc/src/snippets/declarative/qml-extending-types/components/Button.qml 0 +\keyword qml-loading-components +\section1 Loading a Component -Now this component can be reused by another file within the same directory. Since the file is -named \c Button.qml, the component is referred to as \c Button: +The initialization of inline components is different from loading a component +from a \c .qml file. -\table -\row -\o \snippet doc/src/snippets/declarative/qml-extending-types/components/application.qml 0 -\o \image qml-extending-types.png -\endtable +\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. +Specifically, 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, 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-propert}{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 root object in \c Button.qml defines the attributes that are available to users of the \c Button component. In this case, the root object is a \l Rectangle, so any properties, methods and signals of \l Rectangle are made available, allowing \c application.qml to customize the \c width, \c height, \c radius and \c color properties of \c Button objects. - If \c Button.qml was not in the same directory, \c application.qml would need to load it as a \l {Modules}{module} from a specific filesystem path or \l{QDeclarativeExtensionPlugin}{plugin}. Also, note the letter case of the component file name is significant on some (notably UNIX) @@ -81,6 +117,10 @@ filesystems. It is recommended the file name case matches the case of the QML co exactly - for example, \c Box.qml and not \c BoX.qml - regardless of the platform to which the QML component will be deployed. -\section1 Loading a Component +\snippet doc/src/snippets/declarative/qml-extending-types/components/Button.qml 0 +\table +\row +\o \snippet doc/src/snippets/declarative/qml-extending-types/components/application.qml 0 +\o \image qml-extending-types.png +\endtable -*/ diff --git a/doc/src/snippets/declarative/reusablecomponents/Button.qml b/doc/src/snippets/declarative/reusablecomponents/Button.qml new file mode 100644 index 0000000..955e73a --- /dev/null +++ b/doc/src/snippets/declarative/reusablecomponents/Button.qml @@ -0,0 +1,71 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +//! [document] +//contents of Button.qml +import QtQuick 1.0 + +Rectangle { + width: 145; height: 60 + color: "blue" + smooth: true; radius: 9 + property alias text: label.text + + border {color: "#B9C5D0"; width: 1} + + gradient: Gradient { + GradientStop {color: "#CFF7FF"; position: 0.0} + GradientStop {color: "#99C0E5"; position: 0.57} + GradientStop {color: "#719FCB"; position: 0.9} + } + + Text { + id: label + anchors.centerIn: parent + text: "Click Me!" + font.pointSize: 12 + color: "blue" + } + + MouseArea { + anchors.fill: parent + onClicked: console.log(text + " clicked") + } +} +//! [document] diff --git a/doc/src/snippets/declarative/reusablecomponents/application.qml b/doc/src/snippets/declarative/reusablecomponents/application.qml new file mode 100644 index 0000000..094134f --- /dev/null +++ b/doc/src/snippets/declarative/reusablecomponents/application.qml @@ -0,0 +1,55 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +//! [document] +import QtQuick 1.0 + +Rectangle { + width: 175; height: 350 + color: "lightgrey" + + Column { + anchors.centerIn: parent + spacing: 15 + Button {} + Button {text: "Click Me Too!"} + Button {text: "Click Me Three!"} + } +} +//! [document] diff --git a/doc/src/snippets/declarative/reusablecomponents/component.qml b/doc/src/snippets/declarative/reusablecomponents/component.qml new file mode 100644 index 0000000..88fc9b1 --- /dev/null +++ b/doc/src/snippets/declarative/reusablecomponents/component.qml @@ -0,0 +1,77 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +//! [document] +import QtQuick 1.0 + +//! [parent begin] +Rectangle { +//! [parent begin] + id: screen + width: 175; height: 175 + color: "lightgrey" + +//! [define inline component] + Component { + id: inlinecomponent + Rectangle { + id: display + width: 50; height: 50 + color: "blue" + } + } +//! [define inline component] +//! [create inline component] + MouseArea { + anchors.fill: parent + onClicked: { + inlinecomponent.createObject(screen) + + var second = inlinecomponent.createObject(screen) + + var third = inlinecomponent.createObject(screen) + third.x = second.width + 10 + third.color = "red" + } + } +//! [create inline component] +//! [parent end] +} +//! [parent end] +//! [document] diff --git a/doc/src/snippets/declarative/reusablecomponents/qmldir b/doc/src/snippets/declarative/reusablecomponents/qmldir new file mode 100644 index 0000000..93b53f9 --- /dev/null +++ b/doc/src/snippets/declarative/reusablecomponents/qmldir @@ -0,0 +1,4 @@ +//! [document] +Button ./Button.qml 1.0 +SimpleButton ./simplebutton.qml +//! [document] |