From 5cfc65d04858563e53987b224f36ee71356aa73c Mon Sep 17 00:00:00 2001 From: David Boddie Date: Mon, 6 Sep 2010 13:22:39 +0200 Subject: Doc: Worked on two more elements, replacing an image. --- doc/src/declarative/pics/flipable.gif | Bin 80659 -> 131710 bytes doc/src/declarative/qml-intro.qdoc | 4 +- doc/src/snippets/declarative/flipable.qml | 77 ----------------- doc/src/snippets/declarative/flipable/flipable.qml | 77 +++++++++++++++++ .../graphicsitems/qdeclarativeflipable.cpp | 29 ++++--- .../qdeclarativefolderlistmodel.cpp | 96 +++++++++++++++------ 6 files changed, 170 insertions(+), 113 deletions(-) delete mode 100644 doc/src/snippets/declarative/flipable.qml create mode 100644 doc/src/snippets/declarative/flipable/flipable.qml diff --git a/doc/src/declarative/pics/flipable.gif b/doc/src/declarative/pics/flipable.gif index 6386f06..da37b2b 100644 Binary files a/doc/src/declarative/pics/flipable.gif and b/doc/src/declarative/pics/flipable.gif differ diff --git a/doc/src/declarative/qml-intro.qdoc b/doc/src/declarative/qml-intro.qdoc index 9130be0..d735042 100644 --- a/doc/src/declarative/qml-intro.qdoc +++ b/doc/src/declarative/qml-intro.qdoc @@ -58,12 +58,12 @@ would be a property. The basic syntax of an \l{QML Elements}{element} is -\code +\qml SomeElement { id: myObject ... some other things here ... } -\endcode +\endqml Here we are defining a new object. We specify its 'type' first as SomeElement. Then within matching braces { ... } we specify the various parts of our diff --git a/doc/src/snippets/declarative/flipable.qml b/doc/src/snippets/declarative/flipable.qml deleted file mode 100644 index c2ecbbe..0000000 --- a/doc/src/snippets/declarative/flipable.qml +++ /dev/null @@ -1,77 +0,0 @@ -/**************************************************************************** -** -** 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 QtDeclarative module 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$ -** -****************************************************************************/ - -//! [0] -import Qt 4.7 - -Flipable { - id: flipable - width: 240 - height: 240 - - property int angle: 0 - property bool flipped: false - - front: Image { source: "front.png" } - back: Image { source: "back.png" } - - transform: Rotation { - origin.x: flipable.width/2; origin.y: flipable.height/2 - axis.x: 0; axis.y: 1; axis.z: 0 // rotate around y-axis - angle: flipable.angle - } - - states: State { - name: "back" - PropertyChanges { target: flipable; angle: 180 } - when: flipable.flipped - } - - transitions: Transition { - NumberAnimation { properties: "angle"; duration: 1000 } - } - - MouseArea { - anchors.fill: parent - onClicked: flipable.flipped = !flipable.flipped - } -} -//! [0] - diff --git a/doc/src/snippets/declarative/flipable/flipable.qml b/doc/src/snippets/declarative/flipable/flipable.qml new file mode 100644 index 0000000..c2ecbbe --- /dev/null +++ b/doc/src/snippets/declarative/flipable/flipable.qml @@ -0,0 +1,77 @@ +/**************************************************************************** +** +** 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 QtDeclarative module 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$ +** +****************************************************************************/ + +//! [0] +import Qt 4.7 + +Flipable { + id: flipable + width: 240 + height: 240 + + property int angle: 0 + property bool flipped: false + + front: Image { source: "front.png" } + back: Image { source: "back.png" } + + transform: Rotation { + origin.x: flipable.width/2; origin.y: flipable.height/2 + axis.x: 0; axis.y: 1; axis.z: 0 // rotate around y-axis + angle: flipable.angle + } + + states: State { + name: "back" + PropertyChanges { target: flipable; angle: 180 } + when: flipable.flipped + } + + transitions: Transition { + NumberAnimation { properties: "angle"; duration: 1000 } + } + + MouseArea { + anchors.fill: parent + onClicked: flipable.flipped = !flipable.flipped + } +} +//! [0] + diff --git a/src/declarative/graphicsitems/qdeclarativeflipable.cpp b/src/declarative/graphicsitems/qdeclarativeflipable.cpp index 69dd66a..4ecf87b 100644 --- a/src/declarative/graphicsitems/qdeclarativeflipable.cpp +++ b/src/declarative/graphicsitems/qdeclarativeflipable.cpp @@ -71,31 +71,40 @@ public: \qmlclass Flipable QDeclarativeFlipable \since 4.7 \ingroup qml-basic-interaction-elements - \brief The Flipable item provides a surface that can be flipped. \inherits Item Flipable is an item that can be visibly "flipped" between its front and - back sides. It is used together with \l Rotation and \l {State}/\l {Transition} to - produce a flipping effect. + back sides, like a card. It is used together with \l Rotation, \l State + and \l Transition elements to produce a flipping effect. + + The \l front and \l back properties are used to hold the items that are + shown respectively on the front and back sides of the flipable item. - Here is a Flipable that flips whenever it is clicked: + \section1 Example Usage - \snippet doc/src/snippets/declarative/flipable.qml 0 + \beginfloatright + \inlineimage flipable.gif + \endfloat - \image flipable.gif + The following example shows a Flipable item that flips whenever it is + clicked, rotating about the y-axis. The \l Rotation element is used to specify the angle and axis of the flip. - When \c flipped is \c true, the item changes to the "back" state, where + When \c flipped is true, the item changes to the "back" state, where the angle is changed to 180 degrees to produce the flipping effect. - Finally, the \l Transition creates the animation that changes the - angle over one second: when the item changes between its "back" and + + \clearfloat + \snippet doc/src/snippets/declarative/flipable/flipable-snippet.qml 0 + + The \l Transition creates the animation that changes the angle over the + duration of one second. When the item changes between its "back" and default states, the NumberAnimation animates the angle between its old and new values. See the \l {QML States} and \l {QML Animation} documentation for more details on state changes and how animations work within transitions. - + \sa {declarative/ui-components/flipable}{Flipable example} */ diff --git a/src/imports/folderlistmodel/qdeclarativefolderlistmodel.cpp b/src/imports/folderlistmodel/qdeclarativefolderlistmodel.cpp index 6c38911..4983840 100644 --- a/src/imports/folderlistmodel/qdeclarativefolderlistmodel.cpp +++ b/src/imports/folderlistmodel/qdeclarativefolderlistmodel.cpp @@ -95,30 +95,61 @@ public: /*! \qmlclass FolderListModel QDeclarativeFolderListModel \ingroup qml-working-with-data - \brief The FolderListModel provides a model of the contents of a folder in a filesystem. + \brief The FolderListModel provides a model of the contents of a file system folder. - FolderListModel provides access to the local filesystem. The \e folder property - specifies the folder to list. + FolderListModel provides access to information about the contents of a folder + in the local file system, exposing a list of files to views and other data components. - Qt uses "/" as a universal directory separator in the same way that "/" is - used as a path separator in URLs. If you always use "/" as a directory - separator, Qt will translate your paths to conform to the underlying - operating system. - - This type is made available by importing the \c Qt.labs.folderlistmodel module. - \e {Elements in the Qt.labs module are not guaranteed to remain compatible + \note This type is made available by importing the \c Qt.labs.folderlistmodel module. + \e{Elements in the Qt.labs module are not guaranteed to remain compatible in future versions.} \bold{import Qt.labs.folderlistmodel 1.0} - The roles available are: + The \l folder property specifies the folder to access. Information about the + files and directories in the folder is supplied via the model's interface. + Components access names and paths via the following roles: + \list \o fileName \o filePath \endlist - Additionally a file entry can be differentiated from a folder entry - via the \l isFolder() method. + Additionally a file entry can be differentiated from a folder entry via the + isFolder() method. + + \section1 Filtering + + Various properties can be set to filter the number of files and directories + exposed by the model. + + The \l nameFilters property can be set to contain a list of wildcard filters + that are applied to names of files and directories, causing only those that + match the filters to be exposed. + + Directories can be included or excluded using the \l showDirs property, and + navigation directories can also be excluded by setting the \l showDotAndDotDot + property to false. + + It is sometimes useful to limit the files and directories exposed to those + that the user can access. The \l showOnlyReadable property can be set to + enable this feature. + + \section1 Example Usage + + The following example shows a FolderListModel being used to provide a list + of QML files in a \l ListView: + + \snippet doc/src/snippets/declarative/folderlistmodel.qml 0 + + \section1 Path Separators + + Qt uses "/" as a universal directory separator in the same way that "/" is + used as a path separator in URLs. If you always use "/" as a directory + separator, Qt will translate your paths to conform to the underlying + operating system. + + \sa {QML Data Models} */ QDeclarativeFolderListModel::QDeclarativeFolderListModel(QObject *parent) @@ -168,9 +199,13 @@ int QDeclarativeFolderListModel::rowCount(const QModelIndex &parent) const /*! \qmlproperty string FolderListModel::folder - The \a folder property holds the folder the model is currently providing. + The \a folder property holds a URL for the folder that the model is + currently providing. - It is a URL, but must be a file: or qrc: URL (or relative to such a URL). + The value is a URL expressed as a string, and must be a \c file: or \c qrc: + URL, or a relative URL. + + By default, the value is an invalid URL. */ QUrl QDeclarativeFolderListModel::folder() const { @@ -214,16 +249,18 @@ QUrl QDeclarativeFolderListModel::parentFolder() const /*! \qmlproperty list FolderListModel::nameFilters - The \a nameFilters property contains a list of filename filters. + The \a nameFilters property contains a list of file name filters. The filters may include the ? and * wildcards. The example below filters on PNG and JPEG files: - \code + \qml FolderListModel { nameFilters: [ "*.png", "*.jpg" ] } - \endcode + \endqml + + \note Directories are not excluded by filters. */ QStringList QDeclarativeFolderListModel::nameFilters() const { @@ -335,9 +372,14 @@ void QDeclarativeFolderListModel::dataChanged(const QModelIndex &start, const QM /*! \qmlproperty bool FolderListModel::showDirs - If true (the default), directories are included in the model. + If true, directories are included in the model; otherwise only files + are included. + + By default, this property is true. - Note that the nameFilters are ignored for directories. + Note that the nameFilters are not applied to directories. + + \sa showDotAndDotDot */ bool QDeclarativeFolderListModel::showDirs() const { @@ -357,9 +399,12 @@ void QDeclarativeFolderListModel::setShowDirs(bool on) /*! \qmlproperty bool FolderListModel::showDotAndDotDot - If true, the "." and ".." directories are included in the model. + If true, the "." and ".." directories are included in the model; otherwise + they are excluded. + + By default, this property is false. - The default is false. + \sa showDirs */ bool QDeclarativeFolderListModel::showDotAndDotDot() const { @@ -379,9 +424,12 @@ void QDeclarativeFolderListModel::setShowDotAndDotDot(bool on) /*! \qmlproperty bool FolderListModel::showOnlyReadable - If true, only readable files and directories are shown. + If true, only readable files and directories are shown; otherwise all files + and directories are shown. + + By default, this property is false. - The default is false. + \sa showDirs */ bool QDeclarativeFolderListModel::showOnlyReadable() const { -- cgit v0.12