diff options
Diffstat (limited to 'src/doc/src/examples')
-rw-r--r-- | src/doc/src/examples/qml-calculator.qdoc | 36 | ||||
-rw-r--r-- | src/doc/src/examples/qml-examples.qdoc | 718 | ||||
-rw-r--r-- | src/doc/src/examples/qml-extending.qdoc | 303 | ||||
-rw-r--r-- | src/doc/src/examples/qml-flickr.qdoc | 37 | ||||
-rw-r--r-- | src/doc/src/examples/qml-folderlistmodel.qdoc | 138 | ||||
-rw-r--r-- | src/doc/src/examples/qml-minehunt.qdoc | 37 | ||||
-rw-r--r-- | src/doc/src/examples/qml-photoviewer.qdoc | 36 | ||||
-rw-r--r-- | src/doc/src/examples/qml-rssnews.qdoc | 36 | ||||
-rw-r--r-- | src/doc/src/examples/qml-samegame.qdoc | 37 | ||||
-rw-r--r-- | src/doc/src/examples/qml-snake.qdoc | 37 | ||||
-rw-r--r-- | src/doc/src/examples/qml-twitter.qdoc | 37 | ||||
-rw-r--r-- | src/doc/src/examples/qml-webbrowser.qdoc | 39 |
12 files changed, 1491 insertions, 0 deletions
diff --git a/src/doc/src/examples/qml-calculator.qdoc b/src/doc/src/examples/qml-calculator.qdoc new file mode 100644 index 00000000..0bb918c6 --- /dev/null +++ b/src/doc/src/examples/qml-calculator.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \title Calculator + \example demos/declarative/calculator + \depends helper/qmlapplicationviewer + + \brief The Qt Quick Calculator demo shows how to write a simple calculator application in QML and JavaScript. + + \image qml-calculator-example.png +*/ diff --git a/src/doc/src/examples/qml-examples.qdoc b/src/doc/src/examples/qml-examples.qdoc new file mode 100644 index 00000000..3975955a --- /dev/null +++ b/src/doc/src/examples/qml-examples.qdoc @@ -0,0 +1,718 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \title Animation: Basics Example + \example declarative/animation/basics + + This example shows how to create and combine \l{QML Animation and Transitions}{animations} in QML. + + \table + \row + \li \image qml-coloranim-example.png + \row + \li color-animation.qml + \endtable + + \table + \row + \li \image qml-propertyanim-example.png + \row + \li property-animation.qml + \endtable +*/ + +/*! + \title Animation: Behavior Examples + \example declarative/animation/behaviors + + This example shows how to use QML behaviors. + + \image qml-behaviors-example.png +*/ + +/*! + \title Animation: Easing Example + \example declarative/animation/easing + + This example shows the different easing modes available for \l{QML Animation and Transitions}{animations}. + + \image qml-easing-example.png +*/ + +/*! + \title Animation: States Example + \example declarative/animation/states + + These examples show how to use \l{State}{states} and \l{Transition}{transitions}. + + The \c states.qml example shows how an item can change between states, and \c transitions.qml + shows how these state changes can be animated. + + \table + \row + \li \image qml-states-example.png + \row + \li states.qml + \endtable + + \table + \row + \li \image qml-transitions-example.png + \row + \li transitions.qml + \endtable +*/ + +/*! + \title Image Elements: Border Image Example + \example declarative/imageelements/borderimage + + These examples show how to use the BorderImage element. + + \table + \row + \li \image qml-borderimage-example.png + \row + \li borderimage.qml + \endtable + + \table + \row + \li \image qml-borderimage-shadows-example.png + \row + \li shadows.qml + \endtable +*/ + +/*! + \title Image Elements: Image Example + \example declarative/imageelements/image + + This example shows how to use the \l Image element and its \l{Image::fillMode}{fillModes}. + + \image qml-image-example.png +*/ + +/*! + \page declarative-cppextensions-reference.html + \title C++ Extensions: Reference examples + + These examples show how QML can be extended from C++ in various ways. + + The code for these examples is used throughout the \l {Extending QML Functionalities using C++} reference + documentation, which highlights the main principles demonstrated in each example. + + Furthermore, here are additional pages that discuss each example in detail: + + \list + \li \l {declarative/cppextensions/referenceexamples/adding}{Adding Types} + \li \l {declarative/cppextensions/referenceexamples/properties}{Object and List Property Types} + \li \l {declarative/cppextensions/referenceexamples/coercion}{Inheritance and Coercion} + \li \l {declarative/cppextensions/referenceexamples/default}{Default Property} + \li \l {declarative/cppextensions/referenceexamples/grouped}{Grouped Properties} + \li \l {declarative/cppextensions/referenceexamples/attached}{Attached Properties} + \li \l {declarative/cppextensions/referenceexamples/signal}{Signal Support} + \li \l {declarative/cppextensions/referenceexamples/methods}{Methods Support} + \li \l {declarative/cppextensions/referenceexamples/valuesource}{Property Value Source} + \li \l {declarative/cppextensions/referenceexamples/binding}{Binding} + \endlist + + \note These examples all print information to the console to demonstrate the concepts presented. + Ensure that you are able to view the application output when running these examples. + For example, the dbgView tool on Windows can be used to display application output. +*/ + +/*! + \title C++ Extensions: Plugins Example + \example declarative/cppextensions/plugins + + This example shows how to create a C++ plugin extension by subclassing QDeclarativeExtensionPlugin. + + \image qml-plugins-example.png +*/ + +/*! + \title LayoutItem Example + \example declarative/cppextensions/qgraphicslayouts/layoutitem + + This example show how to use the LayoutItem element to integrate QML items into an existing + \l{Graphics View Framework}{Graphics View}-based application. + + \image qml-layoutitem-example.png +*/ +/*! + \title QGraphicsGridLayout Example + \example declarative/cppextensions/qgraphicslayouts/qgraphicsgridlayout + + This example shows how to use QGraphicsGridLayout to lay out QML items. This is + useful if you need to integrate Qt \l{Graphics View Framework}{Graphics View} layouts with + QML. + + \image qml-qgraphicsgridlayout-example.png +*/ +/*! + \title QGraphicsLinearLayout Example + \example declarative/cppextensions/qgraphicslayouts/qgraphicslinearlayout + + This example shows how to use QGraphicsLinearLayout to lay out QML items. This is + useful if you need to integrate Qt \l{Graphics View Framework}{Graphics View} layouts with + QML. + + \image qml-qgraphicslinearlayout-example.png +*/ +/*! + \title C++ Extensions: QGraphicsLayouts examples + \page declarative-cppextensions-qgraphicslayouts.html + + These examples show how to integrate \l{Graphics View Framework}{Graphics View} + layout components with QML: + + \list + \li \l{declarative/cppextensions/qgraphicslayouts/layoutitem}{LayoutItem} + \li \l{declarative/cppextensions/qgraphicslayouts/qgraphicsgridlayout}{QGraphicsGridLayout} + \li \l{declarative/cppextensions/qgraphicslayouts/qgraphicslinearlayout}{QGraphicsLinearLayout} + \endlist + + Also see \l {Integrating QML Code with Existing Qt UI Code} for information on using QML + in Qt applications that use the Graphics View framework or ordinary QWidget-based views. +*/ + +/*! + \title C++ Extensions: QWidgets Example + \example declarative/cppextensions/qwidgets + + This example shows how to embed QWidget-based objects into QML using QGraphicsProxyWidget. + + \image qml-qwidgets-example.png +*/ + +/*! + \title C++ Extensions: Image Provider Example + \example declarative/cppextensions/imageprovider + + This examples shows how to use QDeclarativeImageProvider to serve images + to QML image elements. + + \image qml-imageprovider-example.png +*/ + +/*! + \title C++ Extensions: Network Access Manager Factory Example + \example declarative/cppextensions/networkaccessmanagerfactory + + This example shows how to use QDeclarativeNetworkAccessManagerFactory to create a QNetworkAccessManager + with a proxy. +*/ + +/*! + \title Internationalization Example + \example declarative/i18n + \ingroup internationalization + + This example shows how to enable text translation in QML. + + \image qml-i18n-example.png + + \section1 Introduction + + The QML runtime automatically loads a translation from the i18n subdirectory + of the root QML file, based on the system language. The translations are + held in QM files that must be generated from TS files. + + \section1 Updating Translations + + The \c{.ts} files are created and updated by running: + + \code + lupdate i18n.qml -ts i18n/base.ts + \endcode + + If no translation file exists, one will be created. If a file already exists, + it will be updated to contain the latest strings from the QML file. + + Translations for new languages are created by copying \c{i18n/base.ts} to + \c{i18n/qml_<lang>.ts} The TS files can then be edited with + \l{Qt Linguist Manual}{Qt Linguist}: + + \code + linguist i18n/qml_fr.ts + \endcode + + The run-time translation files are then generated by running: + + \code + lrelease i18n/*.ts + \endcode +*/ + +/*! + \title Right-to-left User Interfaces: Text Alignment Example + \example declarative/righttoleft/textalignment + + This example shows how the horizontal alignment of \l Text, + \l TextInput and \l TextEdit is affected by the reading direction + of the text and by the layout mirrroring. Click on the gray buttons + shown at the bottom of the example to toggle between different + horizontal alignment options. + + \sa {QML Right-to-left User Interfaces} +*/ + +/*! + \title Right-to-left User Interfaces: Layout Direction Example + \example declarative/righttoleft/layoutdirection + + This example shows how to control the horizontal layout direction of + \l Row, \l Grid and \l Flow positioners, and \l ListView and \l GridView + model views. Click on the gray buttons shown at the bottom of the example + to toggle the layout direction of the shown elements. + + \image qml-righttoleft-layoutdirection-example.png + + \sa {QML Right-to-left User Interfaces} +*/ + + +/*! + \title Right-to-left User Interfaces: Layout Mirroring Example + \example declarative/righttoleft/layoutmirroring + + This example shows how to mirror the application layouts + using \l LayoutMirroring attached property. Click on the grey button + shown at the bottom of the example to enable or disable the + layout mirroring. + + \image qml-righttoleft-layoutmirroring-example.png + + \sa {QML Right-to-left User Interfaces} +*/ + +/*! + \title Positioners Example + \example declarative/positioners + + This example shows how to use the positioner elements such as \l Row, \l Column, + \l Grid and \l Flow. + + \image qml-positioners-example.png +*/ + +/*! + \title Key Interaction: Focus Example + \example declarative/keyinteraction/focus + + This example shows how to handle keyboard input and focus in QML. + + \image qml-focus-example.png + + \sa {Keyboard Focus in Qt Quick} +*/ + +/*! + \title Models and Views: AbstractItemModel Example + \example declarative/modelviews/abstractitemmodel + + This example shows how to use a QAbstractItemModel subclass as a model in QML. + + \image qml-abstractitemmodel-example.png +*/ + +/*! + \title Models and Views: GridView Example + \example declarative/modelviews/gridview + + This example shows how to use the GridView element. + + \image qml-gridview-example.png +*/ + +/*! + \title Models and Views: ListView Example + \example declarative/modelviews/listview + + These examples show how to use the ListView element. + + \table + \row + \li \image qml-listview-dynamiclist-example.png + \row + \li dynamiclist.qml + \endtable + + \table + \row + \li \image qml-listview-expandingdelegates-example.png + \row + \li expandingdelegates.qml + \endtable + + \table + \row + \li \image qml-listview-highlight-example.png + \row + \li highlight.qml + \endtable + + \table + \row + \li \image qml-listview-highlightranges-example.png + \row + \li highlightranges.qml + \endtable + + \table + \row + \li \image qml-listview-sections-example.png + \row + \li sections.qml + \endtable +*/ + +/*! + \title Models and Views: PathView Example + \example declarative/modelviews/pathview + + This example shows how to use the PathView element. + + \image qml-pathview-example.png +*/ + +/*! + \title Models and Views: Object ListModel Example + \example declarative/modelviews/objectlistmodel + + This example shows how to use a QList<QObject*> as a model in QML. + + \image qml-objectlistmodel-example.png +*/ + +/*! + \title Models and Views: Package Example + \example declarative/modelviews/package + + This example shows how to use the \l Package element. + + \image qml-package-example.png +*/ + +/*! + \title Models and Views: Parallax Example + \example declarative/modelviews/parallax + + This example shows how to combine and switch between views. + + \image qml-parallax-example.png +*/ + +/*! + \title Models and Views: String ListModel Example + \example declarative/modelviews/stringlistmodel + + This example shows how to use a QStringList as a model in QML. + + \image qml-stringlistmodel-example.png +*/ + +/*! + \title Models and Views: VisualItemModel Example + \example declarative/modelviews/visualitemmodel + + This example shows how to use the VisualItemModel element. + + \image qml-visualitemmodel-example.png +*/ + +/*! + \title Models and Views: WebView Example + \example declarative/modelviews/webview + + These examples show how to use the WebView element. + + \table + \row + \li \image qml-webview-alert-example.png + \row + \li alert.qml + \endtable + + \table + \row + \li \image qml-webview-autosize-example.png + \row + \li autosize.qml + \endtable + + \table + \row + \li \image qml-webview-googlemaps-example.png + \row + \li googlemaps.qml + \endtable + + \table + \row + \li \image qml-webview-inlinehtml-example.png + \row + \li inlinehtml.qml + \endtable + + \table + \row + \li \image qml-webview-newwindows-example.png + \row + \li newwindows.qml + \endtable +*/ + + +/*! + \title Screen Orientation + \example declarative/screenorientation + + This example shows how to implement screen orientation support for your application. +*/ + +/*! + \title SQL Local Storage Example + \example declarative/sqllocalstorage + + This example shows how to use the SQL Local Storage API in QML. +*/ + +/*! + \title Text: Fonts Example + \example declarative/text/fonts + + These examples show how to discover available fonts from QML and manipulate + text in various ways. + + \table + \row + \li \image qml-fonts-availableFonts-example.png + \row + \li availableFonts.qml + \endtable + + \table + \row + \li \image qml-fonts-banner-example.png + \row + \li banner.qml + \endtable + + \table + \row + \li \image qml-fonts-fonts-example.png + \row + \li fonts.qml + \endtable + + \table + \row + \li \image qml-fonts-hello-example.png + \row + \li hello.qml + \endtable +*/ + +/*! + \title Text: Text Selection Example + \example declarative/text/textselection + + This example shows how text selection, copy and paste operations + can be implemented on top of the TextEdit element. + + \image qml-textselection-example.png +*/ + +/*! + \title Threading: Threaded ListModel Example + \example declarative/threading/threadedlistmodel + + This example shows how to use a ListModel from multiple threads using + WorkerScript. +*/ + +/*! + \title Threading: WorkerScript Example + \example declarative/threading/workerscript + + This example shows how to use the WorkerScript element for threading in QML. +*/ + +/*! + \title Toys: Clocks Example + \example declarative/toys/clocks + + This example displays a set of clocks with different times for different cities. + Each clock is created by combining \l Image elements with \l Rotation transforms + and \l SpringAnimation behaviors. + + \image qml-clocks-example.png +*/ + +/*! + \title Toys: Corkboards Example + \example declarative/toys/corkboards + + This example presents a flickable set of interactive corkboards. It is created + through a combination of elements like \l ListModel, \l Repeater and \l TextEdit + together with rotation and scaling transforms, animation and mouse interaction. + + \image qml-corkboards-example.png +*/ + +/*! + \title Toys: Dynamic Scene Example + \example declarative/toys/dynamicscene + + This example presents an interactive drag-and-drop scene. It demonstrates + how to use QML's \l{Dynamic Object Creation} support to dynamically create and + destroy objects. + + \image qml-dynamicscene-example.png +*/ + +/*! + \title Toys: Tic-Tac-Toe Example + \example declarative/toys/tic-tac-toe + + This example presents a simple implementation of Tic Tac Toe. + + \image qml-tic-tac-toe-example.png +*/ + +/*! + \title Toys: TV Tennis Example + \example declarative/toys/tvtennis + + This example shows how to use animation components such as \l SpringAnimation, + \l SequentialAnimation and \l PropertyAction to create a game of TV tennis. + + \image qml-tvtennis-example.png +*/ + +/*! + \title Touch Interaction: MouseArea Example + \example declarative/touchinteraction/mousearea + + This example shows how to use the MouseArea element to access information + about mouse input. + + \image qml-mousearea-example.png +*/ + +/*! + \title UI Components: Dial Control Example + \example declarative/ui-components/dialcontrol + + This example shows how to create a dial-type control. It combines + \l Image elements with \l Rotation transforms and \l SpringAnimation behaviors + to produce an interactive speedometer-type dial. + + \image qml-dialcontrol-example.png +*/ + + +/*! + \title UI Components: Flipable Example + \example declarative/ui-components/flipable + + This example shows how to use the \l Flipable element. + + \image qml-flipable-example.png +*/ + +/*! + \title UI Components: Progress Bars Example + \example declarative/ui-components/progressbar + + This example shows how to create a progress bar. + + \image qml-progressbar-example.png +*/ + +/*! + \title UI Components: Scroll Bar Example + \example declarative/ui-components/scrollbar + + This example shows how to create scroll bars for a \l Flickable element + using the \l {Flickable::visibleArea.xPosition}{Flickable::visibleArea} + properties. + + \image qml-scrollbar-example.png +*/ + +/*! + \title UI Components: Search Box Example + \example declarative/ui-components/searchbox + + This example shows how to combine TextInput, FocusScope and BorderImage + elements to display multiple text input fields. + + \image qml-searchbox-example.png +*/ + +/*! + \title UI Components: Slide Switch Example + \example declarative/ui-components/slideswitch + + This example shows how to create a slide switch control. + + \image qml-slideswitch-example.png +*/ + +/*! + \title UI Components: Spinner Example + \example declarative/ui-components/spinner + + This example shows how to create a spinner-type component using the PathView element. + + \image qml-spinner-example.png +*/ + +/*! + \title UI Components: Tab Widget Example + \example declarative/ui-components/tabwidget + + This example shows how to create a tab widget. It also demonstrates how + \l {Property aliases}{property aliases} and + \l {Introduction to the QML Language#Default Properties}{default properties} can be used to collect and + assemble the child items declared within an \l Item. + + \image qml-tabwidget-example.png +*/ + +/*! + \title XML: XMLHttpRequest Example + \example declarative/xml/xmlhttprequest + + This example shows how to use the \l XmlHttpRequest API in QML. + + \image qml-xmlhttprequest-example.png +*/ diff --git a/src/doc/src/examples/qml-extending.qdoc b/src/doc/src/examples/qml-extending.qdoc new file mode 100644 index 00000000..b36d6568 --- /dev/null +++ b/src/doc/src/examples/qml-extending.qdoc @@ -0,0 +1,303 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\example declarative/cppextensions/referenceexamples/adding +\title Extending QML - Adding Types Example + +\brief The Adding Types Example shows how to add a new element type, \c Person, to QML. + +The \c Person type can be used from QML like this: + +\snippet examples/declarative/cppextensions/referenceexamples/adding/example.qml 0 + +\section1 Declare the Person class + +All QML elements map to C++ types. Here we declare a basic C++ Person class +with the two properties we want accessible on the QML type - name and shoeSize. +Although in this example we use the same name for the C++ class as the QML +element, the C++ class can be named differently, or appear in a namespace. + +\snippet examples/declarative/cppextensions/referenceexamples/adding/person.h 0 + +\section1 Define the Person class + +\snippet examples/declarative/cppextensions/referenceexamples/adding/person.cpp 0 + +The Person class implementation is quite basic. The property accessors simply +return members of the object instance. + +The \c main.cpp file also calls the \c qmlRegisterType() function to +register the \c Person type with QML as a type in the People library version 1.0, +and defines the mapping between the C++ and QML class names. + +\section1 Running the example + +The main.cpp file in the example includes a simple shell application that +loads and runs the QML snippet shown at the beginning of this page. +*/ + +/*! +\example declarative/cppextensions/referenceexamples/properties +\title Extending QML - Object and List Property Types Example + +This example builds on: +\list +\li \l {Extending QML - Adding Types Example} +\endlist + +The Object and List Property Types example shows how to add object and list +properties in QML. This example adds a BirthdayParty element that specifies +a birthday party, consisting of a celebrant and a list of guests. People are +specified using the People QML type built in the previous example. + +\snippet examples/declarative/cppextensions/referenceexamples/properties/example.qml 0 + +\section1 Declare the BirthdayParty + +The BirthdayParty class is declared like this: + +\snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 0 +\snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 1 +\snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 2 +\snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 3 + +The class contains a member to store the celebrant object, and also a +QList<Person *> member. + +In QML, the type of a list properties - and the guests property is a list of +people - are all of type QDeclarativeListProperty<T>. QDeclarativeListProperty is simple value +type that contains a set of function pointers. QML calls these function +pointers whenever it needs to read from, write to or otherwise interact with +the list. In addition to concrete lists like the people list used in this +example, the use of QDeclarativeListProperty allows for "virtual lists" and other advanced +scenarios. + +\section2 Define the BirthdayParty + +The implementation of BirthdayParty property accessors is straight forward. + +\snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.cpp 0 + +\section1 Running the example + +The main.cpp file in the example includes a simple shell application that +loads and runs the QML snippet shown at the beginning of this page. +*/ + +/*! +\example declarative/cppextensions/referenceexamples/coercion +\title Extending QML - Inheritance and Coercion Example + +This example builds on: +\list +\li \l {Extending QML - Object and List Property Types Example} +\li \l {Extending QML - Adding Types Example} +\endlist + +The Inheritance and Coercion Example shows how to use base classes to assign +elements of more than one type to a property. It specializes the Person element +developed in the previous examples into two elements - a \c Boy and a \c Girl. + +\snippet examples/declarative/cppextensions/referenceexamples/coercion/example.qml 0 + +\section1 Declare Boy and Girl + +\snippet examples/declarative/cppextensions/referenceexamples/coercion/person.h 0 + +The Person class remains unaltered in this example and the Boy and Girl C++ +classes are trivial extensions of it. As an example, the inheritance used here +is a little contrived, but in real applications it is likely that the two +extensions would add additional properties or modify the Person classes +behavior. + +\section2 Define People as a base class + +The implementation of the People class itself has not changed since the the +previous example. However, as we have repurposed the People class as a common +base for Boy and Girl, we want to prevent it from being instantiated from QML +directly - an explicit Boy or Girl should be instantiated instead. + +\snippet examples/declarative/cppextensions/referenceexamples/coercion/main.cpp 0 + +While we want to disallow instantiating Person from within QML, it still needs +to be registered with the QML engine, so that it can be used as a property type +and other types can be coerced to it. + +\section2 Define Boy and Girl + +The implementation of Boy and Girl are trivial. + +\snippet examples/declarative/cppextensions/referenceexamples/coercion/person.cpp 1 + +All that is necessary is to implement the constructor, and to register the types +and their QML name with the QML engine. + +\section1 Running the example + +The BirthdayParty element has not changed since the previous example. The +celebrant and guests property still use the People type. + +\snippet examples/declarative/cppextensions/referenceexamples/coercion/birthdayparty.h 0 + +However, as all three types, Person, Boy and Girl, have been registered with the +QML system, on assignment QML automatically (and type-safely) converts the Boy +and Girl objects into a Person. + +The main.cpp file in the example includes a simple shell application that +loads and runs the QML snippet shown at the beginning of this page. +*/ + +/*! +\example declarative/cppextensions/referenceexamples/default +\title Extending QML - Default Property Example + +This example builds on: +\list +\li \l {Extending QML - Inheritance and Coercion Example} +\li \l {Extending QML - Object and List Property Types Example} +\li \l {Extending QML - Adding Types Example} +\endlist + +The Default Property Example is a minor modification of the +\l {Extending QML - Inheritance and Coercion Example} that simplifies the +specification of a BirthdayParty through the use of a default property. + +\snippet examples/declarative/cppextensions/referenceexamples/default/example.qml 0 + +\section1 Declaring the BirthdayParty class + +The only difference between this example and the last, is the addition of the +\c DefaultProperty class info annotation. + +\snippet examples/declarative/cppextensions/referenceexamples/default/birthdayparty.h 0 + +The default property specifies the property to assign to whenever an explicit +property is not specified, in the case of the BirthdayParty element the guest +property. It is purely a syntactic simplification, the behavior is identical +to specifying the property by name, but it can add a more natural feel in many +situations. The default property must be either an object or list property. + +\section1 Running the example + +The main.cpp file in the example includes a simple shell application that +loads and runs the QML snippet shown at the beginning of this page. +*/ + +/*! +\example declarative/cppextensions/referenceexamples/grouped +\title Extending QML - Grouped Properties Example + +This example builds on: +\list +\li \l {Extending QML - Default Property Example} +\li \l {Extending QML - Inheritance and Coercion Example} +\li \l {Extending QML - Object and List Property Types Example} +\li \l {Extending QML - Adding Types Example} +\endlist + +*/ + +/*! +\example declarative/cppextensions/referenceexamples/attached +\title Extending QML - Attached Properties Example + +This example builds on: +\list +\li \l {Extending QML - Grouped Properties Example} +\li \l {Extending QML - Default Property Example} +\li \l {Extending QML - Inheritance and Coercion Example} +\li \l {Extending QML - Object and List Property Types Example} +\li \l {Extending QML - Adding Types Example} +\endlist + +*/ + +/*! +\example declarative/cppextensions/referenceexamples/signal +\title Extending QML - Signal Support Example + +This example builds on: +\list +\li \l {Extending QML - Attached Properties Example} +\li \l {Extending QML - Grouped Properties Example} +\li \l {Extending QML - Default Property Example} +\li \l {Extending QML - Inheritance and Coercion Example} +\li \l {Extending QML - Object and List Property Types Example} +\li \l {Extending QML - Adding Types Example} +\endlist + +*/ + +/*! +\example declarative/cppextensions/referenceexamples/methods +\title Extending QML - Methods Example + +This example builds on: +\list +\li \l {Extending QML - Default Property Example} +\li \l {Extending QML - Inheritance and Coercion Example} +\li \l {Extending QML - Object and List Property Types Example} +\li \l {Extending QML - Adding Types Example} +\endlist + +*/ + +/*! +\example declarative/cppextensions/referenceexamples/valuesource +\title Extending QML - Property Value Source Example + +This example builds on: +\list +\li \l {Extending QML - Signal Support Example} +\li \l {Extending QML - Attached Properties Example} +\li \l {Extending QML - Grouped Properties Example} +\li \l {Extending QML - Default Property Example} +\li \l {Extending QML - Inheritance and Coercion Example} +\li \l {Extending QML - Object and List Property Types Example} +\li \l {Extending QML - Adding Types Example} +\endlist + +*/ + +/*! +\example declarative/cppextensions/referenceexamples/binding +\title Extending QML - Binding Example + +This example builds on: +\list +\li \l {Extending QML - Property Value Source Example} +\li \l {Extending QML - Signal Support Example} +\li \l {Extending QML - Attached Properties Example} +\li \l {Extending QML - Grouped Properties Example} +\li \l {Extending QML - Default Property Example} +\li \l {Extending QML - Inheritance and Coercion Example} +\li \l {Extending QML - Object and List Property Types Example} +\li \l {Extending QML - Adding Types Example} +\endlist + +*/ diff --git a/src/doc/src/examples/qml-flickr.qdoc b/src/doc/src/examples/qml-flickr.qdoc new file mode 100644 index 00000000..52098ada --- /dev/null +++ b/src/doc/src/examples/qml-flickr.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \title Flickr Mobile + \example demos/declarative/flickr + + \brief The Qt Quick Flickr Mobile demo shows how to write a mobile Flickr browser application in QML. + + \depends helper/qmlapplicationviewer + + \image qml-flickr-demo.png +*/ diff --git a/src/doc/src/examples/qml-folderlistmodel.qdoc b/src/doc/src/examples/qml-folderlistmodel.qdoc new file mode 100644 index 00000000..21aa6f64 --- /dev/null +++ b/src/doc/src/examples/qml-folderlistmodel.qdoc @@ -0,0 +1,138 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + +\title FolderListModel - a C++ model plugin +\example src/imports/folderlistmodel +\depends helper/qmlapplicationviewer + +\brief The FolderListModel plugin example shows how to make a C++ model available to QML. + +It presents +a simple file list for a single folder (directory) and allows the presented +folder to be changed. + +\image declarative-folderlistmodel.png The FolderListModel used to choose a QML file + +We do not explain the model implementation in detail, but rather focus on the mechanics of +making the model available to QML. + +\section1 Usage from QML + +The FolderListModel can be used from QML like this: + +\snippet doc/src/snippets/declarative/folderlistmodel.qml 0 + +This displays a list of all subfolders and QML files in the current folder. + +The FolderListModel \c folder property can be set to change the folder that +is currently displayed. + +\section1 Defining the Model + +We are subclassing QAbstractListModel which will allow us to give data to QML and +send notifications when the data changes: + +\snippet src/imports/folderlistmodel/qdeclarativefolderlistmodel.h class begin + +As you see, we also inherit the QDeclarativeParserStatus interface, so that we +can delay initial processing until we have all properties set (via componentComplete() below). + +The first thing to do when devising a new type for QML is to define the properties +you want the type to have: + +\snippet src/imports/folderlistmodel/qdeclarativefolderlistmodel.h class props + +The purposes of each of these should be pretty obvious - in QML we will set the folder +to display (a file: URL), and the kinds of files we want to show in the view of the model. + +Next are the constructor, destructor, and standard QAbstractListModel subclassing requirements: + +\snippet src/imports/folderlistmodel/qdeclarativefolderlistmodel.h abslistmodel + +The data() function is where we provide model values. The rowCount() function +is also a standard part of the QAbstractListModel interface, but we also want to provide +a simpler count property: + +\snippet src/imports/folderlistmodel/qdeclarativefolderlistmodel.h count + +Then we have the functions for the remaining properties which we defined above: + +\snippet src/imports/folderlistmodel/qdeclarativefolderlistmodel.h prop funcs + +Imperative actions upon the model are made available to QML via a Q_INVOKABLE tag on +a normal member function. The isFolder(index) function says whether the value at \e index +is a folder: + +\snippet src/imports/folderlistmodel/qdeclarativefolderlistmodel.h isfolder + +Then we have the QDeclarativeParserStatus interface: + +\snippet src/imports/folderlistmodel/qdeclarativefolderlistmodel.h parserstatus + +Then the NOTIFY function for the folders property. The implementation will emit this +when the folder property is changed. + +\snippet src/imports/folderlistmodel/qdeclarativefolderlistmodel.h notifier + +The class ends with some implementation details: + +\snippet src/imports/folderlistmodel/qdeclarativefolderlistmodel.h class end + +Lastly, the boilerplare to declare the type for QML use: + +\snippet src/imports/folderlistmodel/qdeclarativefolderlistmodel.h qml decl + +\section1 Connecting the Model to QML + +To make this class available to QML, we only need to make a simple subclass of QDeclarativeExtensionPlugin: + +\snippet src/imports/folderlistmodel/plugin.cpp class decl + +and then use the standard Qt plugin export macro: + +\snippet src/imports/folderlistmodel/plugin.cpp plugin export decl + +Finally, in order for QML to connect the "import" statement to our plugin, we list it in the qmldir file: + +\l{src/imports/folderlistmodel/qmldir} + +This qmldir file and the compiled plugin will be installed in \c $QTDIR/imports/Qt/labs/folderlistmodel/ where +the QML engine will find it (since \c $QTDIR/imports is the value of QLibraryInf::libraryPath()). + +\section1 Implementing the Model + +We'll not discuss the model implementation in detail, as it is not specific to QML - any Qt C++ model +can be interfaced to QML. +This implementation is basically just takes the krufty old QDirModel, +which is a tree with lots of detailed roles and re-presents it as a simpler list model where +each item is just a fileName and a filePath (as a file: URL rather than a plain file, since QML +works with URLs for all content). + +\l{src/imports/folderlistmodel/qdeclarativefolderlistmodel.cpp} +*/ diff --git a/src/doc/src/examples/qml-minehunt.qdoc b/src/doc/src/examples/qml-minehunt.qdoc new file mode 100644 index 00000000..c52f6dd5 --- /dev/null +++ b/src/doc/src/examples/qml-minehunt.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \title Minehunt + \example demos/declarative/minehunt + \depends helper/qmlapplicationviewer + + \brief The Qt Quick Minehunt demo shows how to create a simple Minehunt game, using QML for the + UI and C++ for the game logic. + + \image qml-minehunt-demo.png +*/ diff --git a/src/doc/src/examples/qml-photoviewer.qdoc b/src/doc/src/examples/qml-photoviewer.qdoc new file mode 100644 index 00000000..b254c35c --- /dev/null +++ b/src/doc/src/examples/qml-photoviewer.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \title Photo Viewer + \example demos/declarative/photoviewer + \depends helper/qmlapplicationviewer + + \brief The Qt Quick Photo Viewer demo shows how to write a Flickr photo viewer application in QML. + + \image qml-photoviewer-demo.png +*/ diff --git a/src/doc/src/examples/qml-rssnews.qdoc b/src/doc/src/examples/qml-rssnews.qdoc new file mode 100644 index 00000000..fa39db5d --- /dev/null +++ b/src/doc/src/examples/qml-rssnews.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \title RSS News + \example demos/declarative/rssnews + \depends helper/qmlapplicationviewer + + \brief The Qt Quick RSS News demo shows how to write a RSS news reader in QML. + + \image qml-rssnews-demo.png +*/ diff --git a/src/doc/src/examples/qml-samegame.qdoc b/src/doc/src/examples/qml-samegame.qdoc new file mode 100644 index 00000000..c7391911 --- /dev/null +++ b/src/doc/src/examples/qml-samegame.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \title Same Game + \example demos/declarative/samegame + \depends helper/qmlapplicationviewer + + \brief The Qt Quick Same Game demo shows how to write a 'Same Game' game in QML, using Javascript + for all the game logic. + + \image qml-samegame-demo.png +*/ diff --git a/src/doc/src/examples/qml-snake.qdoc b/src/doc/src/examples/qml-snake.qdoc new file mode 100644 index 00000000..cfa1b86f --- /dev/null +++ b/src/doc/src/examples/qml-snake.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \title Snake + \example demos/declarative/snake + \depends helper/qmlapplicationviewer + + \brief The Qt Quick Snake demo shows how to write a Snake game in QML, controlled by the + keyboard as well as the mouse. + + \image qml-snake-demo.png +*/ diff --git a/src/doc/src/examples/qml-twitter.qdoc b/src/doc/src/examples/qml-twitter.qdoc new file mode 100644 index 00000000..da78ac6a --- /dev/null +++ b/src/doc/src/examples/qml-twitter.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \title Twitter Mobile + \example demos/declarative/twitter + \depends helper/qmlapplicationviewer + + \brief The Qt Quick Twitter Mobile demo shows how to write a mobile Twitter search client in QML. + Use it to see what people think about Qt Quick! + + \image qml-twitter-demo.png +*/ diff --git a/src/doc/src/examples/qml-webbrowser.qdoc b/src/doc/src/examples/qml-webbrowser.qdoc new file mode 100644 index 00000000..87fb73fa --- /dev/null +++ b/src/doc/src/examples/qml-webbrowser.qdoc @@ -0,0 +1,39 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \title Qt Quick Web Browser + \example demos/declarative/webbrowser + \depends helper/qmlapplicationviewer + + \brief The Qt Quick Web Browser demo shows how to write a simple web browser in QML by combining the + WebView element with other components including scroll bars, + \l Flickable views and TextInput fields. + + \image qml-webbrowser-demo.png +*/ + |