diff options
Diffstat (limited to 'doc/src/qml/qtprogrammers.qdoc')
| -rw-r--r-- | doc/src/qml/qtprogrammers.qdoc | 197 |
1 files changed, 0 insertions, 197 deletions
diff --git a/doc/src/qml/qtprogrammers.qdoc b/doc/src/qml/qtprogrammers.qdoc deleted file mode 100644 index fd47d9bf58..0000000000 --- a/doc/src/qml/qtprogrammers.qdoc +++ /dev/null @@ -1,197 +0,0 @@ -/**************************************************************************** -** -** 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. -*/ |