doc/src/declarative/qtprogrammers.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Free Documentation License
  17 ** Alternatively, this file may be used under the terms of the GNU Free
  18 ** Documentation License version 1.3 as published by the Free Software
  19 ** Foundation and appearing in the file included in the packaging of this
  20 ** file.
  21 **
  22 ** If you have questions regarding the use of this file, please contact
  23 ** Nokia at qt-info@nokia.com.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qtprogrammers.html
  30 \target qtprogrammers
  31 \title QML for Qt Programmers
  32
  33 While QML does not require Qt knowledge to use, if you \e are already familiar with Qt,
  34 much of your knowledge is directly relevant to learning and using QML. Of course,
  35 an application with a UI defined in QML also uses Qt for all the non-UI logic.
  36
  37 \section1 Familiar Concepts
  38
  39 QML provides direct access to the following concepts from Qt:
  40
  41 \list
  42  \o QAction - the \l {QML Basic Types}{action} type
  43  \o QObject signals and slots - available as functions to call in JavaScript
  44  \o QObject properties - available as variables in JavaScript
  45  \o QWidget - QDeclarativeView is a QML-displaying widget
  46  \o Qt models - used directly in data binding (QAbstractItemModel)
  47 \endlist
  48
  49 Qt knowledge is \e required for \l {Extending QML Functionalities using C++},
  50 and also for \l{Integrating QML Code with existing Qt UI code}.
  51
  52 \section1 QML Items compared with QWidgets
  53
  54 QML Items are very similar to QWidgets: they define the look and feel of the user interface. (Note that while QWidgets
  55 haven't traditionally been used to define the look and feel of view delegates, QML Items can be used for this as well.)
  56
  57 There are three structurally different types of QWidget:
  58
  59 \list
  60  \o Simple widgets that are not used as parents (QLabel, QCheckBox, QToolButton, etc.)
  61  \o Parent widgets that are normally used as parents to other widgets (QGroupBox, QStackedWidget, QTabWidget, etc.)
  62  \o Compound widgets that are internally composed of child widgets (QComboBox, QSpinBox, QFileDialog, QTabWidget, etc.)
  63 \endlist
  64
  65 QML Items also serve these purposes. Each is considered separately below.
  66
  67 \section2 Simple Widgets
  68
  69 The most important rule to remember while implementing a new QDeclarativeItem in C++
  70 is that it should not contain any look and feel policies - leave that to the
  71 QML usage of the item.
  72
  73 As an example, imagine you wanted a reusable Button item. If you therefore
  74 decided to write a QDeclarativeItem subclass to implement a button,
  75 just as QToolButton subclasses QWidget for this purpose, following the rule above, your
  76 \c QDeclarativeButton would not have any appearance - just the notions of enabled, triggering, etc.
  77
  78 But there is already an object in Qt that does this: QAction.
  79
  80 QAction is the UI-agnostic essence of QPushButton, QCheckBox, QMenu items, QToolButton,
  81 and other visual widgets that are commonly bound to a QAction.
  82
  83 So, the job of implementing a checkbox abstraction for QML is already done - it's QAction.
  84 The look and feel of an action - the appearance of the button, the transition between states,
  85 and exactly how it respond to mouse, key, or touch input, should all be left for definition
  86 in QML.
  87
  88 It is illustrative to note that QDeclarativeTextEdit is built upon QTextControl,
  89 QDeclarativeWebView is built upon QWebPage, and ListView uses QAbstractItemModel,
  90 just as QTextEdit, QWebView, and QListView are built upon
  91 those same UI-agnostic components.
  92
  93 The encapsulation of the look and feel that QWidgets gives is important, and for this
  94 the QML concept of \l {qdeclarativedocuments.html}{components} serves the same purpose. If you are building a complete
  95 suite of applications which should have a consistent look and feel, you should build
  96 a set of reusable components with the look and feel you desire.
  97
  98 So, to implement your reusable button, you would simply build a QML component.
  99
 100
 101 \section2 Parent Widgets
 102
 103 Parent widgets each provide a generic way to interface to one or more arbitrary other widgets.
 104 A QTabWidget provides an interface to multiple "pages", one of which is visible at any time,
 105 and a mechanism for selecting among them (the QTabBar). A QScrollArea provides scrollbars around
 106 a widget that is otherwise too large to fit in available space.
 107
 108 Nearly all such components can be created directly in QML. Only a few cases
 109 which require very particular event handling, such as Flickable, require C++ implementations.
 110
 111 As an example, imagine you decided to make a generic tab widget item to be used
 112 through your application suite wherever information is in such quantity that it
 113 needs to be divided up into pages.
 114
 115 A significant difference in the parenting concept with QML compare to QWidgets
 116 is that while child items are positioned relative to their parents,
 117 there is no requirement that they be wholly contained ("clipped") to
 118 the parent (although the clipped property of the child Item does allow
 119 this where it is needed).
 120 This difference has rather far-reaching consequences, for example:
 121
 122 \list
 123     \o A shadow or highlight around a widget could be a child of that widget.
 124     \o Particle effects can flow outside the object where they originate.
 125     \o Transitioning animations can "hide" items by visibly moving them beyond the screen bounds.
 126 \endlist
 127
 128
 129 \section2 Compound Widgets
 130
 131 Some widgets provide functionality by composing other widgets as an "implementation detail",
 132 providing a higher level API to the composition. QSpinBox for example is a line edit and some
 133 buttons to increase/decrease the edited value. QFileDialog uses a whole host of widgets to
 134 give the user a way of finding and selecting a file name.
 135
 136 When developing reusable QML Items, you may choose to do the same: build an item composed
 137 of other items you have already defined.
 138
 139 The only caveat when doing this is to consider the possible animations and transitions that
 140 users of the compound item might wish to employ. For example, a spinbox might need to smoothly
 141 transition from an arbitrary Text item, or characters within a Text item, so your spinbox
 142 item would need to be sufficiently flexible to allow such animation.
 143
 144 \section1 QML Items Compared With QGraphicsWidgets
 145
 146 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 layouting 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++.
 147
 148 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 setup for you when you inherit QDeclarativeItem) 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.
 149
 150 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.
 151
 152 Both differences are caused by the different method of interaction. QGraphicsWidget is a QGraphicsObject subclass which makes fluid UI development from C++ easier, and QDeclarativeItem 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 the nothing for QGraphicsWidget, because you need to write your own UI logic into the subclass).
 153
 154 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 QDeclarativeItem subclasses (although you can use QGraphicsWidgets as well). To allow for easier use from C++ make the root item of each C++ component a 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.
 155 */