1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the QtQml module of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** GNU Lesser General Public License Usage
10 ** This file may be used under the terms of the GNU Lesser General Public
11 ** License version 2.1 as published by the Free Software Foundation and
12 ** appearing in the file LICENSE.LGPL included in the packaging of this
13 ** file. Please review the following information to ensure the GNU Lesser
14 ** General Public License version 2.1 requirements will be met:
15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
17 ** In addition, as a special exception, Nokia gives you certain additional
18 ** rights. These rights are described in the Nokia Qt LGPL Exception
19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
21 ** GNU General Public License Usage
22 ** Alternatively, this file may be used under the terms of the GNU General
23 ** Public License version 3.0 as published by the Free Software Foundation
24 ** and appearing in the file LICENSE.GPL included in the packaging of this
25 ** file. Please review the following information to ensure the GNU General
26 ** Public License version 3.0 requirements will be met:
27 ** http://www.gnu.org/copyleft/gpl.html.
30 ** Alternatively, this file may be used in accordance with the terms and
31 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
42 #include "qquickitem.h"
44 #include "qquickwindow.h"
45 #include <QtQml/qjsengine.h>
46 #include "qquickwindow_p.h"
48 #include "qquickevents_p_p.h"
49 #include "qquickscreen_p.h"
51 #include <QtQml/qqmlengine.h>
52 #include <QtQml/qqmlcomponent.h>
53 #include <QtQml/qqmlinfo.h>
54 #include <QtGui/qpen.h>
55 #include <QtGui/qguiapplication.h>
56 #include <QtGui/private/qguiapplication_p.h>
57 #include <QtGui/qinputmethod.h>
58 #include <QtCore/qdebug.h>
59 #include <QtCore/qcoreevent.h>
60 #include <QtCore/qnumeric.h>
62 #include <private/qqmlglobal_p.h>
63 #include <private/qqmlengine_p.h>
64 #include <QtQuick/private/qquickstategroup_p.h>
65 #include <private/qqmlopenmetaobject_p.h>
66 #include <QtQuick/private/qquickstate_p.h>
67 #include <private/qquickitem_p.h>
68 #include <private/qqmlaccessors_p.h>
69 #include <QtQuick/private/qquickaccessibleattached_p.h>
72 # include <QtGui/qcursor.h>
77 // XXX todo Check that elements that create items handle memory correctly after visual ownership change
82 void printFocusTree(QQuickItem *item, QQuickItem *scope = 0, int depth = 1);
83 void printFocusTree(QQuickItem *item, QQuickItem *scope, int depth)
86 << QByteArray(depth, '\t').constData()
87 << (scope && QQuickItemPrivate::get(scope)->subFocusItem == item ? '*' : ' ')
89 << item->hasActiveFocus()
90 << item->isFocusScope()
92 foreach (QQuickItem *child, item->childItems()) {
95 item->isFocusScope() || !scope ? item : scope,
96 item->isFocusScope() || !scope ? depth + 1 : depth);
101 static void QQuickItem_parentNotifier(QObject *o, intptr_t, QQmlNotifier **n)
103 QQuickItemPrivate *d = QQuickItemPrivate::get(static_cast<QQuickItem *>(o));
104 *n = &d->parentNotifier;
107 QML_PRIVATE_ACCESSOR(QQuickItem, QQuickItem *, parent, parentItem)
108 QML_PRIVATE_ACCESSOR(QQuickItem, qreal, x, x)
109 QML_PRIVATE_ACCESSOR(QQuickItem, qreal, y, y)
110 QML_PRIVATE_ACCESSOR(QQuickItem, qreal, width, width)
111 QML_PRIVATE_ACCESSOR(QQuickItem, qreal, height, height)
113 static QQmlAccessors QQuickItem_parent = { QQuickItem_parentRead, QQuickItem_parentNotifier };
114 static QQmlAccessors QQuickItem_x = { QQuickItem_xRead, 0 };
115 static QQmlAccessors QQuickItem_y = { QQuickItem_yRead, 0 };
116 static QQmlAccessors QQuickItem_width = { QQuickItem_widthRead, 0 };
117 static QQmlAccessors QQuickItem_height = { QQuickItem_heightRead, 0 };
119 QML_DECLARE_PROPERTIES(QQuickItem) {
120 { QML_PROPERTY_NAME(parent), 0, &QQuickItem_parent },
121 { QML_PROPERTY_NAME(x), 0, &QQuickItem_x },
122 { QML_PROPERTY_NAME(y), 0, &QQuickItem_y },
123 { QML_PROPERTY_NAME(width), 0, &QQuickItem_width },
124 { QML_PROPERTY_NAME(height), 0, &QQuickItem_height }
127 void QQuickItemPrivate::registerAccessorProperties()
129 QML_DEFINE_PROPERTIES(QQuickItem);
134 \instantiates QQuickTransform
135 \inqmlmodule QtQuick 2
136 \ingroup qtquick-visual-transforms
137 \brief For specifying advanced transformations on Items
139 The Transform type is a base type which cannot be instantiated directly.
140 The following concrete Transform types are available:
148 The Transform types let you create and control advanced transformations that can be configured
149 independently using specialized properties.
151 You can assign any number of Transforms to an \l Item. Each Transform is applied in order,
154 QQuickTransformPrivate::QQuickTransformPrivate()
158 QQuickTransform::QQuickTransform(QObject *parent)
159 : QObject(*(new QQuickTransformPrivate), parent)
163 QQuickTransform::QQuickTransform(QQuickTransformPrivate &dd, QObject *parent)
164 : QObject(dd, parent)
168 QQuickTransform::~QQuickTransform()
170 Q_D(QQuickTransform);
171 for (int ii = 0; ii < d->items.count(); ++ii) {
172 QQuickItemPrivate *p = QQuickItemPrivate::get(d->items.at(ii));
173 p->transforms.removeOne(this);
174 p->dirty(QQuickItemPrivate::Transform);
178 void QQuickTransform::update()
180 Q_D(QQuickTransform);
181 for (int ii = 0; ii < d->items.count(); ++ii) {
182 QQuickItemPrivate *p = QQuickItemPrivate::get(d->items.at(ii));
183 p->dirty(QQuickItemPrivate::Transform);
187 QQuickContents::QQuickContents(QQuickItem *item)
188 : m_item(item), m_x(0), m_y(0), m_width(0), m_height(0)
192 QQuickContents::~QQuickContents()
194 QList<QQuickItem *> children = m_item->childItems();
195 for (int i = 0; i < children.count(); ++i) {
196 QQuickItem *child = children.at(i);
197 QQuickItemPrivate::get(child)->removeItemChangeListener(this, QQuickItemPrivate::Geometry | QQuickItemPrivate::Destroyed);
201 bool QQuickContents::calcHeight(QQuickItem *changed)
204 qreal oldheight = m_height;
208 qreal bottom = oldy + oldheight;
209 qreal y = changed->y();
210 if (y + changed->height() > bottom)
211 bottom = y + changed->height();
215 m_height = bottom - top;
219 QList<QQuickItem *> children = m_item->childItems();
220 for (int i = 0; i < children.count(); ++i) {
221 QQuickItem *child = children.at(i);
222 qreal y = child->y();
223 if (y + child->height() > bottom)
224 bottom = y + child->height();
228 if (!children.isEmpty())
230 m_height = qMax(bottom - top, qreal(0.0));
233 return (m_height != oldheight || m_y != oldy);
236 bool QQuickContents::calcWidth(QQuickItem *changed)
239 qreal oldwidth = m_width;
243 qreal right = oldx + oldwidth;
244 qreal x = changed->x();
245 if (x + changed->width() > right)
246 right = x + changed->width();
250 m_width = right - left;
252 qreal left = FLT_MAX;
254 QList<QQuickItem *> children = m_item->childItems();
255 for (int i = 0; i < children.count(); ++i) {
256 QQuickItem *child = children.at(i);
257 qreal x = child->x();
258 if (x + child->width() > right)
259 right = x + child->width();
263 if (!children.isEmpty())
265 m_width = qMax(right - left, qreal(0.0));
268 return (m_width != oldwidth || m_x != oldx);
271 void QQuickContents::complete()
273 QQuickItemPrivate::get(m_item)->addItemChangeListener(this, QQuickItemPrivate::Children);
275 QList<QQuickItem *> children = m_item->childItems();
276 for (int i = 0; i < children.count(); ++i) {
277 QQuickItem *child = children.at(i);
278 QQuickItemPrivate::get(child)->addItemChangeListener(this, QQuickItemPrivate::Geometry | QQuickItemPrivate::Destroyed);
279 //###what about changes to visibility?
284 void QQuickContents::updateRect()
286 QQuickItemPrivate::get(m_item)->emitChildrenRectChanged(rectF());
289 void QQuickContents::itemGeometryChanged(QQuickItem *changed, const QRectF &newGeometry, const QRectF &oldGeometry)
292 bool wChanged = false;
293 bool hChanged = false;
294 //### we can only pass changed if the left edge has moved left, or the right edge has moved right
295 if (newGeometry.width() != oldGeometry.width() || newGeometry.x() != oldGeometry.x())
296 wChanged = calcWidth(/*changed*/);
297 if (newGeometry.height() != oldGeometry.height() || newGeometry.y() != oldGeometry.y())
298 hChanged = calcHeight(/*changed*/);
299 if (wChanged || hChanged)
303 void QQuickContents::itemDestroyed(QQuickItem *item)
306 QQuickItemPrivate::get(item)->removeItemChangeListener(this, QQuickItemPrivate::Geometry | QQuickItemPrivate::Destroyed);
310 void QQuickContents::itemChildRemoved(QQuickItem *, QQuickItem *item)
313 QQuickItemPrivate::get(item)->removeItemChangeListener(this, QQuickItemPrivate::Geometry | QQuickItemPrivate::Destroyed);
317 void QQuickContents::itemChildAdded(QQuickItem *, QQuickItem *item)
320 QQuickItemPrivate::get(item)->addItemChangeListener(this, QQuickItemPrivate::Geometry | QQuickItemPrivate::Destroyed);
324 QQuickItemKeyFilter::QQuickItemKeyFilter(QQuickItem *item)
325 : m_processPost(false), m_next(0)
327 QQuickItemPrivate *p = item?QQuickItemPrivate::get(item):0;
329 m_next = p->extra.value().keyHandler;
330 p->extra->keyHandler = this;
334 QQuickItemKeyFilter::~QQuickItemKeyFilter()
338 void QQuickItemKeyFilter::keyPressed(QKeyEvent *event, bool post)
340 if (m_next) m_next->keyPressed(event, post);
343 void QQuickItemKeyFilter::keyReleased(QKeyEvent *event, bool post)
345 if (m_next) m_next->keyReleased(event, post);
348 void QQuickItemKeyFilter::inputMethodEvent(QInputMethodEvent *event, bool post)
351 m_next->inputMethodEvent(event, post);
356 QVariant QQuickItemKeyFilter::inputMethodQuery(Qt::InputMethodQuery query) const
358 if (m_next) return m_next->inputMethodQuery(query);
362 void QQuickItemKeyFilter::componentComplete()
364 if (m_next) m_next->componentComplete();
367 \qmltype KeyNavigation
368 \instantiates QQuickKeyNavigationAttached
369 \inqmlmodule QtQuick 2
370 \ingroup qtquick-input
371 \brief Supports key navigation by arrow keys
373 Key-based user interfaces commonly allow the use of arrow keys to navigate between
374 focusable items. The KeyNavigation attached property enables this behavior by providing a
375 convenient way to specify the item that should gain focus when an arrow or tab key is pressed.
377 The following example provides key navigation for a 2x2 grid of items:
379 \snippet qml/keynavigation.qml 0
381 The top-left item initially receives focus by setting \l {Item::}{focus} to
382 \c true. When an arrow key is pressed, the focus will move to the
383 appropriate item, as defined by the value that has been set for
384 the KeyNavigation \l left, \l right, \l up or \l down properties.
386 Note that if a KeyNavigation attached property receives the key press and release
387 events for a requested arrow or tab key, the event is accepted and does not
388 propagate any further.
390 By default, KeyNavigation receives key events after the item to which it is attached.
391 If the item accepts the key event, the KeyNavigation attached property will not
392 receive an event for that key. Setting the \l priority property to
393 \c KeyNavigation.BeforeItem allows the event to be used for key navigation
394 before the item, rather than after.
396 If item to which the focus is switching is not enabled or visible, an attempt will
397 be made to skip this item and focus on the next. This is possible if there are
398 a chain of items with the same KeyNavigation handler. If multiple items in a row are not enabled
399 or visible, they will also be skipped.
401 KeyNavigation will implicitly set the other direction to return focus to this item. So if you set
402 \l left to another item, \l right will be set on that item's KeyNavigation to set focus back to this
403 item. However, if that item's KeyNavigation has had right explicitly set then no change will occur.
404 This means that the above example could have been written, with the same behaviour, without specifing
405 KeyNavigation.right or KeyNavigation.down for any of the items.
407 \sa {Keys}{Keys attached property}
411 \qmlproperty Item QtQuick2::KeyNavigation::left
412 \qmlproperty Item QtQuick2::KeyNavigation::right
413 \qmlproperty Item QtQuick2::KeyNavigation::up
414 \qmlproperty Item QtQuick2::KeyNavigation::down
415 \qmlproperty Item QtQuick2::KeyNavigation::tab
416 \qmlproperty Item QtQuick2::KeyNavigation::backtab
418 These properties hold the item to assign focus to
419 when the left, right, up or down cursor keys, or the
424 \qmlproperty Item QtQuick2::KeyNavigation::tab
425 \qmlproperty Item QtQuick2::KeyNavigation::backtab
427 These properties hold the item to assign focus to
428 when the Tab key or Shift+Tab key combination (Backtab) are pressed.
431 QQuickKeyNavigationAttached::QQuickKeyNavigationAttached(QObject *parent)
432 : QObject(*(new QQuickKeyNavigationAttachedPrivate), parent),
433 QQuickItemKeyFilter(qmlobject_cast<QQuickItem*>(parent))
435 m_processPost = true;
438 QQuickKeyNavigationAttached *
439 QQuickKeyNavigationAttached::qmlAttachedProperties(QObject *obj)
441 return new QQuickKeyNavigationAttached(obj);
444 QQuickItem *QQuickKeyNavigationAttached::left() const
446 Q_D(const QQuickKeyNavigationAttached);
450 void QQuickKeyNavigationAttached::setLeft(QQuickItem *i)
452 Q_D(QQuickKeyNavigationAttached);
457 QQuickKeyNavigationAttached* other =
458 qobject_cast<QQuickKeyNavigationAttached*>(qmlAttachedPropertiesObject<QQuickKeyNavigationAttached>(i));
459 if (other && !other->d_func()->rightSet){
460 other->d_func()->right = qobject_cast<QQuickItem*>(parent());
461 emit other->rightChanged();
466 QQuickItem *QQuickKeyNavigationAttached::right() const
468 Q_D(const QQuickKeyNavigationAttached);
472 void QQuickKeyNavigationAttached::setRight(QQuickItem *i)
474 Q_D(QQuickKeyNavigationAttached);
479 QQuickKeyNavigationAttached* other =
480 qobject_cast<QQuickKeyNavigationAttached*>(qmlAttachedPropertiesObject<QQuickKeyNavigationAttached>(i));
481 if (other && !other->d_func()->leftSet){
482 other->d_func()->left = qobject_cast<QQuickItem*>(parent());
483 emit other->leftChanged();
488 QQuickItem *QQuickKeyNavigationAttached::up() const
490 Q_D(const QQuickKeyNavigationAttached);
494 void QQuickKeyNavigationAttached::setUp(QQuickItem *i)
496 Q_D(QQuickKeyNavigationAttached);
501 QQuickKeyNavigationAttached* other =
502 qobject_cast<QQuickKeyNavigationAttached*>(qmlAttachedPropertiesObject<QQuickKeyNavigationAttached>(i));
503 if (other && !other->d_func()->downSet){
504 other->d_func()->down = qobject_cast<QQuickItem*>(parent());
505 emit other->downChanged();
510 QQuickItem *QQuickKeyNavigationAttached::down() const
512 Q_D(const QQuickKeyNavigationAttached);
516 void QQuickKeyNavigationAttached::setDown(QQuickItem *i)
518 Q_D(QQuickKeyNavigationAttached);
523 QQuickKeyNavigationAttached* other =
524 qobject_cast<QQuickKeyNavigationAttached*>(qmlAttachedPropertiesObject<QQuickKeyNavigationAttached>(i));
525 if (other && !other->d_func()->upSet) {
526 other->d_func()->up = qobject_cast<QQuickItem*>(parent());
527 emit other->upChanged();
532 QQuickItem *QQuickKeyNavigationAttached::tab() const
534 Q_D(const QQuickKeyNavigationAttached);
538 void QQuickKeyNavigationAttached::setTab(QQuickItem *i)
540 Q_D(QQuickKeyNavigationAttached);
545 QQuickKeyNavigationAttached* other =
546 qobject_cast<QQuickKeyNavigationAttached*>(qmlAttachedPropertiesObject<QQuickKeyNavigationAttached>(i));
547 if (other && !other->d_func()->backtabSet) {
548 other->d_func()->backtab = qobject_cast<QQuickItem*>(parent());
549 emit other->backtabChanged();
554 QQuickItem *QQuickKeyNavigationAttached::backtab() const
556 Q_D(const QQuickKeyNavigationAttached);
560 void QQuickKeyNavigationAttached::setBacktab(QQuickItem *i)
562 Q_D(QQuickKeyNavigationAttached);
566 d->backtabSet = true;
567 QQuickKeyNavigationAttached* other =
568 qobject_cast<QQuickKeyNavigationAttached*>(qmlAttachedPropertiesObject<QQuickKeyNavigationAttached>(i));
569 if (other && !other->d_func()->tabSet) {
570 other->d_func()->tab = qobject_cast<QQuickItem*>(parent());
571 emit other->tabChanged();
573 emit backtabChanged();
577 \qmlproperty enumeration QtQuick2::KeyNavigation::priority
579 This property determines whether the keys are processed before
580 or after the attached item's own key handling.
583 \li KeyNavigation.BeforeItem - process the key events before normal
584 item key processing. If the event is used for key navigation, it will be accepted and will not
585 be passed on to the item.
586 \li KeyNavigation.AfterItem (default) - process the key events after normal item key
587 handling. If the item accepts the key event it will not be
588 handled by the KeyNavigation attached property handler.
591 QQuickKeyNavigationAttached::Priority QQuickKeyNavigationAttached::priority() const
593 return m_processPost ? AfterItem : BeforeItem;
596 void QQuickKeyNavigationAttached::setPriority(Priority order)
598 bool processPost = order == AfterItem;
599 if (processPost != m_processPost) {
600 m_processPost = processPost;
601 emit priorityChanged();
605 void QQuickKeyNavigationAttached::keyPressed(QKeyEvent *event, bool post)
607 Q_D(QQuickKeyNavigationAttached);
610 if (post != m_processPost) {
611 QQuickItemKeyFilter::keyPressed(event, post);
616 switch (event->key()) {
618 if (QQuickItem *parentItem = qobject_cast<QQuickItem*>(parent()))
619 mirror = QQuickItemPrivate::get(parentItem)->effectiveLayoutMirror;
620 QQuickItem* leftItem = mirror ? d->right : d->left;
622 setFocusNavigation(leftItem, mirror ? "right" : "left");
627 case Qt::Key_Right: {
628 if (QQuickItem *parentItem = qobject_cast<QQuickItem*>(parent()))
629 mirror = QQuickItemPrivate::get(parentItem)->effectiveLayoutMirror;
630 QQuickItem* rightItem = mirror ? d->left : d->right;
632 setFocusNavigation(rightItem, mirror ? "left" : "right");
639 setFocusNavigation(d->up, "up");
645 setFocusNavigation(d->down, "down");
651 setFocusNavigation(d->tab, "tab");
655 case Qt::Key_Backtab:
657 setFocusNavigation(d->backtab, "backtab");
665 if (!event->isAccepted()) QQuickItemKeyFilter::keyPressed(event, post);
668 void QQuickKeyNavigationAttached::keyReleased(QKeyEvent *event, bool post)
670 Q_D(QQuickKeyNavigationAttached);
673 if (post != m_processPost) {
674 QQuickItemKeyFilter::keyReleased(event, post);
679 switch (event->key()) {
681 if (QQuickItem *parentItem = qobject_cast<QQuickItem*>(parent()))
682 mirror = QQuickItemPrivate::get(parentItem)->effectiveLayoutMirror;
683 if (mirror ? d->right : d->left)
687 if (QQuickItem *parentItem = qobject_cast<QQuickItem*>(parent()))
688 mirror = QQuickItemPrivate::get(parentItem)->effectiveLayoutMirror;
689 if (mirror ? d->left : d->right)
707 case Qt::Key_Backtab:
716 if (!event->isAccepted()) QQuickItemKeyFilter::keyReleased(event, post);
719 void QQuickKeyNavigationAttached::setFocusNavigation(QQuickItem *currentItem, const char *dir)
721 QQuickItem *initialItem = currentItem;
722 bool isNextItem = false;
725 if (currentItem->isVisible() && currentItem->isEnabled()) {
726 currentItem->setFocus(true);
729 qmlAttachedPropertiesObject<QQuickKeyNavigationAttached>(currentItem, false);
731 QQuickItem *tempItem = qvariant_cast<QQuickItem*>(attached->property(dir));
733 currentItem = tempItem;
739 while (currentItem != initialItem && isNextItem);
742 const QQuickKeysAttached::SigMap QQuickKeysAttached::sigMap[] = {
743 { Qt::Key_Left, "leftPressed" },
744 { Qt::Key_Right, "rightPressed" },
745 { Qt::Key_Up, "upPressed" },
746 { Qt::Key_Down, "downPressed" },
747 { Qt::Key_Tab, "tabPressed" },
748 { Qt::Key_Backtab, "backtabPressed" },
749 { Qt::Key_Asterisk, "asteriskPressed" },
750 { Qt::Key_NumberSign, "numberSignPressed" },
751 { Qt::Key_Escape, "escapePressed" },
752 { Qt::Key_Return, "returnPressed" },
753 { Qt::Key_Enter, "enterPressed" },
754 { Qt::Key_Delete, "deletePressed" },
755 { Qt::Key_Space, "spacePressed" },
756 { Qt::Key_Back, "backPressed" },
757 { Qt::Key_Cancel, "cancelPressed" },
758 { Qt::Key_Select, "selectPressed" },
759 { Qt::Key_Yes, "yesPressed" },
760 { Qt::Key_No, "noPressed" },
761 { Qt::Key_Context1, "context1Pressed" },
762 { Qt::Key_Context2, "context2Pressed" },
763 { Qt::Key_Context3, "context3Pressed" },
764 { Qt::Key_Context4, "context4Pressed" },
765 { Qt::Key_Call, "callPressed" },
766 { Qt::Key_Hangup, "hangupPressed" },
767 { Qt::Key_Flip, "flipPressed" },
768 { Qt::Key_Menu, "menuPressed" },
769 { Qt::Key_VolumeUp, "volumeUpPressed" },
770 { Qt::Key_VolumeDown, "volumeDownPressed" },
774 bool QQuickKeysAttached::isConnected(const char *signalName)
776 Q_D(QQuickKeysAttached);
777 int signal_index = d->signalIndex(signalName);
778 return d->isSignalConnected(signal_index);
783 \instantiates QQuickKeysAttached
784 \inqmlmodule QtQuick 2
785 \ingroup qtquick-input
786 \brief Provides key handling to Items
788 All visual primitives support key handling via the Keys
789 attached property. Keys can be handled via the onPressed
790 and onReleased signal properties.
792 The signal properties have a \l KeyEvent parameter, named
793 \e event which contains details of the event. If a key is
794 handled \e event.accepted should be set to true to prevent the
795 event from propagating up the item hierarchy.
797 \section1 Example Usage
799 The following example shows how the general onPressed handler can
800 be used to test for a certain key; in this case, the left cursor
803 \snippet qml/keys/keys-pressed.qml key item
805 Some keys may alternatively be handled via specific signal properties,
806 for example \e onSelectPressed. These handlers automatically set
807 \e event.accepted to true.
809 \snippet qml/keys/keys-handler.qml key item
811 See \l{Qt::Key}{Qt.Key} for the list of keyboard codes.
813 \section1 Key Handling Priorities
815 The Keys attached property can be configured to handle key events
816 before or after the item it is attached to. This makes it possible
817 to intercept events in order to override an item's default behavior,
818 or act as a fallback for keys not handled by the item.
820 If \l priority is Keys.BeforeItem (default) the order of key event processing is:
823 \li Items specified in \c forwardTo
824 \li specific key handlers, e.g. onReturnPressed
825 \li onKeyPress, onKeyRelease handlers
826 \li Item specific key handling, e.g. TextInput key handling
830 If priority is Keys.AfterItem the order of key event processing is:
833 \li Item specific key handling, e.g. TextInput key handling
834 \li Items specified in \c forwardTo
835 \li specific key handlers, e.g. onReturnPressed
836 \li onKeyPress, onKeyRelease handlers
840 If the event is accepted during any of the above steps, key
843 \sa KeyEvent, {KeyNavigation}{KeyNavigation attached property}
847 \qmlproperty bool QtQuick2::Keys::enabled
849 This flags enables key handling if true (default); otherwise
850 no key handlers will be called.
854 \qmlproperty enumeration QtQuick2::Keys::priority
856 This property determines whether the keys are processed before
857 or after the attached item's own key handling.
860 \li Keys.BeforeItem (default) - process the key events before normal
861 item key processing. If the event is accepted it will not
862 be passed on to the item.
863 \li Keys.AfterItem - process the key events after normal item key
864 handling. If the item accepts the key event it will not be
865 handled by the Keys attached property handler.
870 \qmlproperty list<Object> QtQuick2::Keys::forwardTo
872 This property provides a way to forward key presses, key releases, and keyboard input
873 coming from input methods to other items. This can be useful when you want
874 one item to handle some keys (e.g. the up and down arrow keys), and another item to
875 handle other keys (e.g. the left and right arrow keys). Once an item that has been
876 forwarded keys accepts the event it is no longer forwarded to items later in the
879 This example forwards key events to two lists:
890 Keys.forwardTo: [list1, list2]
897 \qmlsignal QtQuick2::Keys::onPressed(KeyEvent event)
899 This handler is called when a key has been pressed. The \a event
900 parameter provides information about the event.
904 \qmlsignal QtQuick2::Keys::onReleased(KeyEvent event)
906 This handler is called when a key has been released. The \a event
907 parameter provides information about the event.
911 \qmlsignal QtQuick2::Keys::onDigit0Pressed(KeyEvent event)
913 This handler is called when the digit '0' has been pressed. The \a event
914 parameter provides information about the event.
918 \qmlsignal QtQuick2::Keys::onDigit1Pressed(KeyEvent event)
920 This handler is called when the digit '1' has been pressed. The \a event
921 parameter provides information about the event.
925 \qmlsignal QtQuick2::Keys::onDigit2Pressed(KeyEvent event)
927 This handler is called when the digit '2' has been pressed. The \a event
928 parameter provides information about the event.
932 \qmlsignal QtQuick2::Keys::onDigit3Pressed(KeyEvent event)
934 This handler is called when the digit '3' has been pressed. The \a event
935 parameter provides information about the event.
939 \qmlsignal QtQuick2::Keys::onDigit4Pressed(KeyEvent event)
941 This handler is called when the digit '4' has been pressed. The \a event
942 parameter provides information about the event.
946 \qmlsignal QtQuick2::Keys::onDigit5Pressed(KeyEvent event)
948 This handler is called when the digit '5' has been pressed. The \a event
949 parameter provides information about the event.
953 \qmlsignal QtQuick2::Keys::onDigit6Pressed(KeyEvent event)
955 This handler is called when the digit '6' has been pressed. The \a event
956 parameter provides information about the event.
960 \qmlsignal QtQuick2::Keys::onDigit7Pressed(KeyEvent event)
962 This handler is called when the digit '7' has been pressed. The \a event
963 parameter provides information about the event.
967 \qmlsignal QtQuick2::Keys::onDigit8Pressed(KeyEvent event)
969 This handler is called when the digit '8' has been pressed. The \a event
970 parameter provides information about the event.
974 \qmlsignal QtQuick2::Keys::onDigit9Pressed(KeyEvent event)
976 This handler is called when the digit '9' has been pressed. The \a event
977 parameter provides information about the event.
981 \qmlsignal QtQuick2::Keys::onLeftPressed(KeyEvent event)
983 This handler is called when the Left arrow has been pressed. The \a event
984 parameter provides information about the event.
988 \qmlsignal QtQuick2::Keys::onRightPressed(KeyEvent event)
990 This handler is called when the Right arrow has been pressed. The \a event
991 parameter provides information about the event.
995 \qmlsignal QtQuick2::Keys::onUpPressed(KeyEvent event)
997 This handler is called when the Up arrow has been pressed. The \a event
998 parameter provides information about the event.
1002 \qmlsignal QtQuick2::Keys::onDownPressed(KeyEvent event)
1004 This handler is called when the Down arrow has been pressed. The \a event
1005 parameter provides information about the event.
1009 \qmlsignal QtQuick2::Keys::onTabPressed(KeyEvent event)
1011 This handler is called when the Tab key has been pressed. The \a event
1012 parameter provides information about the event.
1016 \qmlsignal QtQuick2::Keys::onBacktabPressed(KeyEvent event)
1018 This handler is called when the Shift+Tab key combination (Backtab) has
1019 been pressed. The \a event parameter provides information about the event.
1023 \qmlsignal QtQuick2::Keys::onAsteriskPressed(KeyEvent event)
1025 This handler is called when the Asterisk '*' has been pressed. The \a event
1026 parameter provides information about the event.
1030 \qmlsignal QtQuick2::Keys::onEscapePressed(KeyEvent event)
1032 This handler is called when the Escape key has been pressed. The \a event
1033 parameter provides information about the event.
1037 \qmlsignal QtQuick2::Keys::onReturnPressed(KeyEvent event)
1039 This handler is called when the Return key has been pressed. The \a event
1040 parameter provides information about the event.
1044 \qmlsignal QtQuick2::Keys::onEnterPressed(KeyEvent event)
1046 This handler is called when the Enter key has been pressed. The \a event
1047 parameter provides information about the event.
1051 \qmlsignal QtQuick2::Keys::onDeletePressed(KeyEvent event)
1053 This handler is called when the Delete key has been pressed. The \a event
1054 parameter provides information about the event.
1058 \qmlsignal QtQuick2::Keys::onSpacePressed(KeyEvent event)
1060 This handler is called when the Space key has been pressed. The \a event
1061 parameter provides information about the event.
1065 \qmlsignal QtQuick2::Keys::onBackPressed(KeyEvent event)
1067 This handler is called when the Back key has been pressed. The \a event
1068 parameter provides information about the event.
1072 \qmlsignal QtQuick2::Keys::onCancelPressed(KeyEvent event)
1074 This handler is called when the Cancel key has been pressed. The \a event
1075 parameter provides information about the event.
1079 \qmlsignal QtQuick2::Keys::onSelectPressed(KeyEvent event)
1081 This handler is called when the Select key has been pressed. The \a event
1082 parameter provides information about the event.
1086 \qmlsignal QtQuick2::Keys::onYesPressed(KeyEvent event)
1088 This handler is called when the Yes key has been pressed. The \a event
1089 parameter provides information about the event.
1093 \qmlsignal QtQuick2::Keys::onNoPressed(KeyEvent event)
1095 This handler is called when the No key has been pressed. The \a event
1096 parameter provides information about the event.
1100 \qmlsignal QtQuick2::Keys::onContext1Pressed(KeyEvent event)
1102 This handler is called when the Context1 key has been pressed. The \a event
1103 parameter provides information about the event.
1107 \qmlsignal QtQuick2::Keys::onContext2Pressed(KeyEvent event)
1109 This handler is called when the Context2 key has been pressed. The \a event
1110 parameter provides information about the event.
1114 \qmlsignal QtQuick2::Keys::onContext3Pressed(KeyEvent event)
1116 This handler is called when the Context3 key has been pressed. The \a event
1117 parameter provides information about the event.
1121 \qmlsignal QtQuick2::Keys::onContext4Pressed(KeyEvent event)
1123 This handler is called when the Context4 key has been pressed. The \a event
1124 parameter provides information about the event.
1128 \qmlsignal QtQuick2::Keys::onCallPressed(KeyEvent event)
1130 This handler is called when the Call key has been pressed. The \a event
1131 parameter provides information about the event.
1135 \qmlsignal QtQuick2::Keys::onHangupPressed(KeyEvent event)
1137 This handler is called when the Hangup key has been pressed. The \a event
1138 parameter provides information about the event.
1142 \qmlsignal QtQuick2::Keys::onFlipPressed(KeyEvent event)
1144 This handler is called when the Flip key has been pressed. The \a event
1145 parameter provides information about the event.
1149 \qmlsignal QtQuick2::Keys::onMenuPressed(KeyEvent event)
1151 This handler is called when the Menu key has been pressed. The \a event
1152 parameter provides information about the event.
1156 \qmlsignal QtQuick2::Keys::onVolumeUpPressed(KeyEvent event)
1158 This handler is called when the VolumeUp key has been pressed. The \a event
1159 parameter provides information about the event.
1163 \qmlsignal QtQuick2::Keys::onVolumeDownPressed(KeyEvent event)
1165 This handler is called when the VolumeDown key has been pressed. The \a event
1166 parameter provides information about the event.
1169 QQuickKeysAttached::QQuickKeysAttached(QObject *parent)
1170 : QObject(*(new QQuickKeysAttachedPrivate), parent),
1171 QQuickItemKeyFilter(qmlobject_cast<QQuickItem*>(parent))
1173 Q_D(QQuickKeysAttached);
1174 m_processPost = false;
1175 d->item = qmlobject_cast<QQuickItem*>(parent);
1178 QQuickKeysAttached::~QQuickKeysAttached()
1182 QQuickKeysAttached::Priority QQuickKeysAttached::priority() const
1184 return m_processPost ? AfterItem : BeforeItem;
1187 void QQuickKeysAttached::setPriority(Priority order)
1189 bool processPost = order == AfterItem;
1190 if (processPost != m_processPost) {
1191 m_processPost = processPost;
1192 emit priorityChanged();
1196 void QQuickKeysAttached::componentComplete()
1198 Q_D(QQuickKeysAttached);
1200 for (int ii = 0; ii < d->targets.count(); ++ii) {
1201 QQuickItem *targetItem = d->targets.at(ii);
1202 if (targetItem && (targetItem->flags() & QQuickItem::ItemAcceptsInputMethod)) {
1203 d->item->setFlag(QQuickItem::ItemAcceptsInputMethod);
1210 void QQuickKeysAttached::keyPressed(QKeyEvent *event, bool post)
1212 Q_D(QQuickKeysAttached);
1213 if (post != m_processPost || !d->enabled || d->inPress) {
1215 QQuickItemKeyFilter::keyPressed(event, post);
1219 // first process forwards
1220 if (d->item && d->item->window()) {
1222 for (int ii = 0; ii < d->targets.count(); ++ii) {
1223 QQuickItem *i = d->targets.at(ii);
1224 if (i && i->isVisible()) {
1225 d->item->window()->sendEvent(i, event);
1226 if (event->isAccepted()) {
1235 QQuickKeyEvent ke(*event);
1236 QByteArray keySignal = keyToSignal(event->key());
1237 if (!keySignal.isEmpty()) {
1238 keySignal += "(QQuickKeyEvent*)";
1239 if (isConnected(keySignal)) {
1240 // If we specifically handle a key then default to accepted
1241 ke.setAccepted(true);
1242 int idx = QQuickKeysAttached::staticMetaObject.indexOfSignal(keySignal);
1243 metaObject()->method(idx).invoke(this, Qt::DirectConnection, Q_ARG(QQuickKeyEvent*, &ke));
1246 if (!ke.isAccepted())
1248 event->setAccepted(ke.isAccepted());
1250 if (!event->isAccepted()) QQuickItemKeyFilter::keyPressed(event, post);
1253 void QQuickKeysAttached::keyReleased(QKeyEvent *event, bool post)
1255 Q_D(QQuickKeysAttached);
1256 if (post != m_processPost || !d->enabled || d->inRelease) {
1258 QQuickItemKeyFilter::keyReleased(event, post);
1262 if (d->item && d->item->window()) {
1263 d->inRelease = true;
1264 for (int ii = 0; ii < d->targets.count(); ++ii) {
1265 QQuickItem *i = d->targets.at(ii);
1266 if (i && i->isVisible()) {
1267 d->item->window()->sendEvent(i, event);
1268 if (event->isAccepted()) {
1269 d->inRelease = false;
1274 d->inRelease = false;
1277 QQuickKeyEvent ke(*event);
1279 event->setAccepted(ke.isAccepted());
1281 if (!event->isAccepted()) QQuickItemKeyFilter::keyReleased(event, post);
1284 void QQuickKeysAttached::inputMethodEvent(QInputMethodEvent *event, bool post)
1286 Q_D(QQuickKeysAttached);
1287 if (post == m_processPost && d->item && !d->inIM && d->item->window()) {
1289 for (int ii = 0; ii < d->targets.count(); ++ii) {
1290 QQuickItem *i = d->targets.at(ii);
1291 if (i && i->isVisible() && (i->flags() & QQuickItem::ItemAcceptsInputMethod)) {
1292 d->item->window()->sendEvent(i, event);
1293 if (event->isAccepted()) {
1302 QQuickItemKeyFilter::inputMethodEvent(event, post);
1305 QVariant QQuickKeysAttached::inputMethodQuery(Qt::InputMethodQuery query) const
1307 Q_D(const QQuickKeysAttached);
1309 for (int ii = 0; ii < d->targets.count(); ++ii) {
1310 QQuickItem *i = d->targets.at(ii);
1311 if (i && i->isVisible() && (i->flags() & QQuickItem::ItemAcceptsInputMethod) && i == d->imeItem) {
1312 //### how robust is i == d->imeItem check?
1313 QVariant v = i->inputMethodQuery(query);
1314 if (v.userType() == QVariant::RectF)
1315 v = d->item->mapRectFromItem(i, v.toRectF()); //### cost?
1320 return QQuickItemKeyFilter::inputMethodQuery(query);
1323 QQuickKeysAttached *QQuickKeysAttached::qmlAttachedProperties(QObject *obj)
1325 return new QQuickKeysAttached(obj);
1329 \qmltype LayoutMirroring
1330 \instantiates QQuickLayoutMirroringAttached
1331 \inqmlmodule QtQuick 2
1332 \ingroup qtquick-positioners
1333 \ingroup qml-utility-elements
1334 \brief Property used to mirror layout behavior
1336 The LayoutMirroring attached property is used to horizontally mirror \l {anchor-layout}{Item anchors},
1337 \l{Item Layouts}{positioner} types (such as \l Row and \l Grid)
1338 and views (such as \l GridView and horizontal \l ListView). Mirroring is a visual change: left
1339 anchors become right anchors, and positioner types like \l Grid and \l Row reverse the
1340 horizontal layout of child items.
1342 Mirroring is enabled for an item by setting the \l enabled property to true. By default, this
1343 only affects the item itself; setting the \l childrenInherit property to true propagates the mirroring
1344 behavior to all child items as well. If the \c LayoutMirroring attached property has not been defined
1345 for an item, mirroring is not enabled.
1347 The following example shows mirroring in action. The \l Row below is specified as being anchored
1348 to the left of its parent. However, since mirroring has been enabled, the anchor is horizontally
1349 reversed and it is now anchored to the right. Also, since items in a \l Row are positioned
1350 from left to right by default, they are now positioned from right to left instead, as demonstrated
1351 by the numbering and opacity of the items:
1353 \snippet qml/layoutmirroring.qml 0
1355 \image layoutmirroring.png
1357 Layout mirroring is useful when it is necessary to support both left-to-right and right-to-left
1358 layout versions of an application to target different language areas. The \l childrenInherit
1359 property allows layout mirroring to be applied without manually setting layout configurations
1360 for every item in an application. Keep in mind, however, that mirroring does not affect any
1361 positioning that is defined by the \l Item \l {Item::}{x} coordinate value, so even with
1362 mirroring enabled, it will often be necessary to apply some layout fixes to support the
1363 desired layout direction. Also, it may be necessary to disable the mirroring of individual
1364 child items (by setting \l {enabled}{LayoutMirroring.enabled} to false for such items) if
1365 mirroring is not the desired behavior, or if the child item already implements mirroring in
1368 See \l {Right-to-left User Interfaces} for further details on using \c LayoutMirroring and
1369 other related features to implement right-to-left support for an application.
1373 \qmlproperty bool QtQuick2::LayoutMirroring::enabled
1375 This property holds whether the item's layout is mirrored horizontally. Setting this to true
1376 horizontally reverses \l {anchor-layout}{anchor} settings such that left anchors become right,
1377 and right anchors become left. For \l{Item Layouts}{positioner} types
1378 (such as \l Row and \l Grid) and view types (such as \l {GridView}{GridView} and \l {ListView}{ListView})
1379 this also mirrors the horizontal layout direction of the item.
1381 The default value is false.
1385 \qmlproperty bool QtQuick2::LayoutMirroring::childrenInherit
1387 This property holds whether the \l {enabled}{LayoutMirroring.enabled} value for this item
1388 is inherited by its children.
1390 The default value is false.
1394 QQuickLayoutMirroringAttached::QQuickLayoutMirroringAttached(QObject *parent) : QObject(parent), itemPrivate(0)
1396 if (QQuickItem *item = qobject_cast<QQuickItem*>(parent)) {
1397 itemPrivate = QQuickItemPrivate::get(item);
1398 itemPrivate->extra.value().layoutDirectionAttached = this;
1400 qmlInfo(parent) << tr("LayoutDirection attached property only works with Items");
1403 QQuickLayoutMirroringAttached * QQuickLayoutMirroringAttached::qmlAttachedProperties(QObject *object)
1405 return new QQuickLayoutMirroringAttached(object);
1408 bool QQuickLayoutMirroringAttached::enabled() const
1410 return itemPrivate ? itemPrivate->effectiveLayoutMirror : false;
1413 void QQuickLayoutMirroringAttached::setEnabled(bool enabled)
1418 itemPrivate->isMirrorImplicit = false;
1419 if (enabled != itemPrivate->effectiveLayoutMirror) {
1420 itemPrivate->setLayoutMirror(enabled);
1421 if (itemPrivate->inheritMirrorFromItem)
1422 itemPrivate->resolveLayoutMirror();
1426 void QQuickLayoutMirroringAttached::resetEnabled()
1428 if (itemPrivate && !itemPrivate->isMirrorImplicit) {
1429 itemPrivate->isMirrorImplicit = true;
1430 itemPrivate->resolveLayoutMirror();
1434 bool QQuickLayoutMirroringAttached::childrenInherit() const
1436 return itemPrivate ? itemPrivate->inheritMirrorFromItem : false;
1439 void QQuickLayoutMirroringAttached::setChildrenInherit(bool childrenInherit) {
1440 if (itemPrivate && childrenInherit != itemPrivate->inheritMirrorFromItem) {
1441 itemPrivate->inheritMirrorFromItem = childrenInherit;
1442 itemPrivate->resolveLayoutMirror();
1443 childrenInheritChanged();
1447 void QQuickItemPrivate::resolveLayoutMirror()
1450 if (QQuickItem *parentItem = q->parentItem()) {
1451 QQuickItemPrivate *parentPrivate = QQuickItemPrivate::get(parentItem);
1452 setImplicitLayoutMirror(parentPrivate->inheritedLayoutMirror, parentPrivate->inheritMirrorFromParent);
1454 setImplicitLayoutMirror(isMirrorImplicit ? false : effectiveLayoutMirror, inheritMirrorFromItem);
1458 void QQuickItemPrivate::setImplicitLayoutMirror(bool mirror, bool inherit)
1460 inherit = inherit || inheritMirrorFromItem;
1461 if (!isMirrorImplicit && inheritMirrorFromItem)
1462 mirror = effectiveLayoutMirror;
1463 if (mirror == inheritedLayoutMirror && inherit == inheritMirrorFromParent)
1466 inheritMirrorFromParent = inherit;
1467 inheritedLayoutMirror = inheritMirrorFromParent ? mirror : false;
1469 if (isMirrorImplicit)
1470 setLayoutMirror(inherit ? inheritedLayoutMirror : false);
1471 for (int i = 0; i < childItems.count(); ++i) {
1472 if (QQuickItem *child = qmlobject_cast<QQuickItem *>(childItems.at(i))) {
1473 QQuickItemPrivate *childPrivate = QQuickItemPrivate::get(child);
1474 childPrivate->setImplicitLayoutMirror(inheritedLayoutMirror, inheritMirrorFromParent);
1479 void QQuickItemPrivate::setLayoutMirror(bool mirror)
1481 if (mirror != effectiveLayoutMirror) {
1482 effectiveLayoutMirror = mirror;
1484 QQuickAnchorsPrivate *anchor_d = QQuickAnchorsPrivate::get(_anchors);
1485 anchor_d->fillChanged();
1486 anchor_d->centerInChanged();
1487 anchor_d->updateHorizontalAnchors();
1490 if (extra.isAllocated() && extra->layoutDirectionAttached) {
1491 emit extra->layoutDirectionAttached->enabledChanged();
1496 void QQuickItemPrivate::setAccessibleFlagAndListener()
1499 QQuickItem *item = q;
1501 if (item->d_func()->isAccessible)
1502 break; // already set - grandparents should have the flag set as well.
1504 item->d_func()->isAccessible = true;
1505 item = item->d_func()->parentItem;
1509 void QQuickItemPrivate::updateSubFocusItem(QQuickItem *scope, bool focus)
1514 QQuickItemPrivate *scopePrivate = QQuickItemPrivate::get(scope);
1516 QQuickItem *oldSubFocusItem = scopePrivate->subFocusItem;
1517 // Correct focus chain in scope
1518 if (oldSubFocusItem) {
1519 QQuickItem *sfi = scopePrivate->subFocusItem->parentItem();
1520 while (sfi && sfi != scope) {
1521 QQuickItemPrivate::get(sfi)->subFocusItem = 0;
1522 sfi = sfi->parentItem();
1527 scopePrivate->subFocusItem = q;
1528 QQuickItem *sfi = scopePrivate->subFocusItem->parentItem();
1529 while (sfi && sfi != scope) {
1530 QQuickItemPrivate::get(sfi)->subFocusItem = q;
1531 sfi = sfi->parentItem();
1534 scopePrivate->subFocusItem = 0;
1540 \brief The QQuickItem class provides the most basic of all visual items in QtQuick.
1543 All visual items in Qt Quick inherit from QQuickItem. Although a QQuickItem
1544 instance has no visual appearance, it defines all the attributes that are
1545 common across visual items, such as x and y position, width and height,
1546 \l {Positioning with Anchors}{anchoring} and key handling support.
1548 You can subclass QQuickItem to provide your own custom visual item
1549 that inherits these features.
1551 \section2 Custom Items using Scene Graph
1553 All visual QML items are rendered using the scene graph, a
1554 low-level, high-performance rendering stack, closely tied to
1555 OpenGL. It is possible for subclasses of QQuickItem to add their
1556 own custom content into the scene graph by setting the
1557 QQuickItem::ItemHasContents flag and reimplementing the
1558 QQuickItem::updatePaintNode() function.
1560 \warning It is crucial that OpenGL operations and interaction with
1561 the scene graph happens exclusively on the rendering thread,
1562 primarily during the updatePaintNode() call. The best rule of
1563 thumb is to only use classes with the "QSG" prefix inside the
1564 QQuickItem::updatePaintNode() function.
1566 To read more about how the scene graph rendering works, see
1567 \l{Scene Graph and Rendering}
1569 \section2 Custom Items using QPainter
1571 The QQuickItem provides a subclass, QQuickPaintedItem, which
1572 allows the users to render content using QPainter.
1574 \warning Using QQuickPaintedItem uses an indirect 2D surface to
1575 render its content, either using software rasterization or using
1576 an OpenGL framebuffer object (FBO), so the rendering is a two-step
1577 operation. First rasterize the surface, then draw the
1578 surface. Using scene graph API directly is always significantly
1581 \sa QQuickWindow, QQuickPaintedItem
1586 \instantiates QQuickItem
1588 \inqmlmodule QtQuick 2
1589 \ingroup qtquick-visual
1590 \brief A basic visual QML type
1592 The Item type is the base type for all visual items in Qt Quick.
1594 All visual items in Qt Quick inherit from Item. Although an Item
1595 object has no visual appearance, it defines all the attributes that are
1596 common across visual items, such as x and y position, width and height,
1597 \l {Positioning with Anchors}{anchoring} and key handling support.
1599 The Item type can be useful for grouping several items under a single
1600 root visual item. For example:
1619 fillMode: Image.Tile
1626 \section2 Key Handling
1628 Key handling is available to all Item-based visual types via the \l Keys
1629 attached property. The \e Keys attached property provides basic handlers
1630 such as \l {Keys::}{onPressed} and \l {Keys}{::onReleased}, as well as
1631 handlers for specific keys, such as \l {Keys::}{onSpacePressed}. The
1632 example below assigns \l {Keyboard Focus in Qt Quick}{keyboard focus} to
1633 the item and handles the left key via the general \e onPressed handler
1634 and the return key via the onReturnPressed handler:
1642 if (event.key == Qt.Key_Left) {
1643 console.log("move left");
1644 event.accepted = true;
1647 Keys.onReturnPressed: console.log("Pressed return");
1651 See the \l Keys attached property for detailed documentation.
1653 \section2 Layout Mirroring
1655 Item layouts can be mirrored using the \l LayoutMirroring attached
1656 property. This causes \l{anchors.top}{anchors} to be horizontally
1657 reversed, and also causes items that lay out or position their children
1658 (such as ListView or \l Row) to horizontally reverse the direction of
1661 See LayoutMirroring for more details.
1665 \enum QQuickItem::Flag
1667 This enum type is used to specify various item properties.
1669 \value ItemClipsChildrenToShape Indicates this item should visually clip
1670 its children so that they are rendered only within the boundaries of this
1672 \value ItemAcceptsInputMethod Indicates the item supports text input
1674 \value ItemIsFocusScope Indicates the item is a focus scope. See
1675 \l {Keyboard Focus in Qt Quick} for more information.
1676 \value ItemHasContents Indicates the item has visual content and should be
1677 rendered by the scene graph.
1678 \value ItemAcceptsDrops Indicates the item accepts drag and drop events.
1680 \sa setFlag(), setFlags(), flags()
1684 \enum QQuickItem::ItemChange
1689 \enum QQuickItem::TransformOrigin
1691 Controls the point about which simple transforms like scale apply.
1693 \value TopLeft The top-left corner of the item.
1694 \value Top The center point of the top of the item.
1695 \value TopRight The top-right corner of the item.
1696 \value Left The left most point of the vertical middle.
1697 \value Center The center of the item.
1698 \value Right The right most point of the vertical middle.
1699 \value BottomLeft The bottom-left corner of the item.
1700 \value Bottom The center point of the bottom of the item.
1701 \value BottomRight The bottom-right corner of the item.
1707 \fn void QQuickItem::childrenRectChanged(const QRectF &)
1712 \fn void QQuickItem::baselineOffsetChanged(qreal)
1717 \fn void QQuickItem::stateChanged(const QString &state)
1722 \fn void QQuickItem::parentChanged(QQuickItem *)
1727 \fn void QQuickItem::smoothChanged(bool)
1732 \fn void QQuickItem::antialiasingChanged(bool)
1737 \fn void QQuickItem::clipChanged(bool)
1742 \fn void QQuickItem::transformOriginChanged(TransformOrigin)
1747 \fn void QQuickItem::focusChanged(bool)
1752 \fn void QQuickItem::activeFocusChanged(bool)
1757 \fn void QQuickItem::childrenChanged()
1762 \fn void QQuickItem::opacityChanged()
1767 \fn void QQuickItem::enabledChanged()
1772 \fn void QQuickItem::visibleChanged()
1777 \fn void QQuickItem::visibleChildrenChanged()
1782 \fn void QQuickItem::rotationChanged()
1787 \fn void QQuickItem::scaleChanged()
1792 \fn void QQuickItem::xChanged()
1797 \fn void QQuickItem::yChanged()
1802 \fn void QQuickItem::widthChanged()
1807 \fn void QQuickItem::heightChanged()
1812 \fn void QQuickItem::zChanged()
1817 \fn void QQuickItem::implicitWidthChanged()
1822 \fn void QQuickItem::implicitHeightChanged()
1827 \fn QQuickItem::QQuickItem(QQuickItem *parent)
1829 Constructs a QQuickItem with the given \a parent.
1831 QQuickItem::QQuickItem(QQuickItem* parent)
1832 : QObject(*(new QQuickItemPrivate), parent)
1840 QQuickItem::QQuickItem(QQuickItemPrivate &dd, QQuickItem *parent)
1841 : QObject(dd, parent)
1848 static int qt_item_count = 0;
1850 static void qt_print_item_count()
1852 qDebug("Number of leaked items: %i", qt_item_count);
1858 Destroys the QQuickItem.
1860 QQuickItem::~QQuickItem()
1864 if (qt_item_count < 0)
1865 qDebug("Item destroyed after qt_print_item_count() was called.");
1870 if (d->windowRefCount > 1)
1871 d->windowRefCount = 1; // Make sure window is set to null in next call to derefWindow().
1877 // XXX todo - optimize
1878 while (!d->childItems.isEmpty())
1879 d->childItems.first()->setParentItem(0);
1881 for (int ii = 0; ii < d->changeListeners.count(); ++ii) {
1882 QQuickAnchorsPrivate *anchor = d->changeListeners.at(ii).listener->anchorPrivate();
1884 anchor->clearItem(this);
1888 update item anchors that depended on us unless they are our child (and will also be destroyed),
1889 or our sibling, and our parent is also being destroyed.
1891 for (int ii = 0; ii < d->changeListeners.count(); ++ii) {
1892 QQuickAnchorsPrivate *anchor = d->changeListeners.at(ii).listener->anchorPrivate();
1893 if (anchor && anchor->item && anchor->item->parentItem() && anchor->item->parentItem() != this)
1897 for (int ii = 0; ii < d->changeListeners.count(); ++ii) {
1898 const QQuickItemPrivate::ChangeListener &change = d->changeListeners.at(ii);
1899 if (change.types & QQuickItemPrivate::Destroyed)
1900 change.listener->itemDestroyed(this);
1903 d->changeListeners.clear();
1905 if (d->extra.isAllocated()) {
1906 delete d->extra->contents; d->extra->contents = 0;
1907 delete d->extra->layer; d->extra->layer = 0;
1910 delete d->_anchors; d->_anchors = 0;
1911 delete d->_stateGroup; d->_stateGroup = 0;
1915 \qmlproperty Item QtQuick2::Item::parent
1916 This property holds the visual parent of the item.
1918 \note The concept of the \e {visual parent} differs from that of the
1919 \e {QObject parent}. An item's visual parent may not necessarily be the
1920 same as its object parent. See \l {Concepts - Visual Parent in Qt Quick}
1924 \property QQuickItem::parent
1925 This property holds the visual parent of the item.
1927 \note The concept of the \e {visual parent} differs from that of the
1928 \e {QObject parent}. An item's visual parent may not necessarily be the
1929 same as its object parent. See \l {Concepts - Visual Parent in Qt Quick}
1932 QQuickItem *QQuickItem::parentItem() const
1934 Q_D(const QQuickItem);
1935 return d->parentItem;
1938 void QQuickItem::setParentItem(QQuickItem *parentItem)
1941 if (parentItem == d->parentItem)
1945 QQuickItem *itemAncestor = parentItem->parentItem();
1946 while (itemAncestor != 0) {
1947 if (itemAncestor == this) {
1948 qWarning("QQuickItem::setParentItem: Parent is already part of this items subtree.");
1951 itemAncestor = itemAncestor->parentItem();
1955 d->removeFromDirtyList();
1957 QQuickItem *oldParentItem = d->parentItem;
1958 QQuickItem *scopeFocusedItem = 0;
1960 if (oldParentItem) {
1961 QQuickItemPrivate *op = QQuickItemPrivate::get(oldParentItem);
1963 QQuickItem *scopeItem = 0;
1966 scopeFocusedItem = this;
1967 else if (!isFocusScope() && d->subFocusItem)
1968 scopeFocusedItem = d->subFocusItem;
1970 if (scopeFocusedItem) {
1971 scopeItem = oldParentItem;
1972 while (!scopeItem->isFocusScope() && scopeItem->parentItem())
1973 scopeItem = scopeItem->parentItem();
1975 QQuickWindowPrivate::get(d->window)->clearFocusInScope(scopeItem, scopeFocusedItem,
1976 QQuickWindowPrivate::DontChangeFocusProperty);
1977 if (scopeFocusedItem != this)
1978 QQuickItemPrivate::get(scopeFocusedItem)->updateSubFocusItem(this, true);
1980 QQuickItemPrivate::get(scopeFocusedItem)->updateSubFocusItem(scopeItem, false);
1984 const bool wasVisible = isVisible();
1985 op->removeChild(this);
1987 emit oldParentItem->visibleChildrenChanged();
1989 } else if (d->window) {
1990 QQuickWindowPrivate::get(d->window)->parentlessItems.remove(this);
1993 QQuickWindow *oldParentWindow = oldParentItem ? QQuickItemPrivate::get(oldParentItem)->window : 0;
1994 QQuickWindow *parentWindow = parentItem ? QQuickItemPrivate::get(parentItem)->window : 0;
1995 if (oldParentWindow == parentWindow) {
1996 // Avoid freeing and reallocating resources if the window stays the same.
1997 d->parentItem = parentItem;
1999 if (oldParentWindow)
2001 d->parentItem = parentItem;
2003 d->refWindow(parentWindow);
2006 d->dirty(QQuickItemPrivate::ParentChanged);
2009 QQuickItemPrivate::get(d->parentItem)->addChild(this);
2011 QQuickWindowPrivate::get(d->window)->parentlessItems.insert(this);
2013 d->setEffectiveVisibleRecur(d->calcEffectiveVisible());
2014 d->setEffectiveEnableRecur(0, d->calcEffectiveEnable());
2016 if (d->parentItem) {
2017 if (!scopeFocusedItem) {
2019 scopeFocusedItem = this;
2020 else if (!isFocusScope() && d->subFocusItem)
2021 scopeFocusedItem = d->subFocusItem;
2024 if (scopeFocusedItem) {
2025 // We need to test whether this item becomes scope focused
2026 QQuickItem *scopeItem = d->parentItem;
2027 while (!scopeItem->isFocusScope() && scopeItem->parentItem())
2028 scopeItem = scopeItem->parentItem();
2030 if (QQuickItemPrivate::get(scopeItem)->subFocusItem
2031 || (!scopeItem->isFocusScope() && scopeItem->hasFocus())) {
2032 if (scopeFocusedItem != this)
2033 QQuickItemPrivate::get(scopeFocusedItem)->updateSubFocusItem(this, false);
2034 QQuickItemPrivate::get(scopeFocusedItem)->focus = false;
2035 emit scopeFocusedItem->focusChanged(false);
2038 QQuickWindowPrivate::get(d->window)->setFocusInScope(scopeItem, scopeFocusedItem,
2039 QQuickWindowPrivate::DontChangeFocusProperty);
2041 QQuickItemPrivate::get(scopeFocusedItem)->updateSubFocusItem(scopeItem, true);
2047 d->resolveLayoutMirror();
2049 d->itemChange(ItemParentHasChanged, d->parentItem);
2051 d->parentNotifier.notify();
2052 if (d->isAccessible && d->parentItem) {
2053 d->parentItem->d_func()->setAccessibleFlagAndListener();
2056 emit parentChanged(d->parentItem);
2057 if (isVisible() && d->parentItem)
2058 emit d->parentItem->visibleChildrenChanged();
2062 Moves the specified \a sibling item to the index before this item
2063 within the visual stacking order.
2065 The given \a sibling must be a sibling of this item; that is, they must
2066 have the same immediate \l parent.
2068 \sa {Concepts - Visual Parent in Qt Quick}
2070 void QQuickItem::stackBefore(const QQuickItem *sibling)
2073 if (!sibling || sibling == this || !d->parentItem || d->parentItem != QQuickItemPrivate::get(sibling)->parentItem) {
2074 qWarning("QQuickItem::stackBefore: Cannot stack before %p, which must be a sibling", sibling);
2078 QQuickItemPrivate *parentPrivate = QQuickItemPrivate::get(d->parentItem);
2080 int myIndex = parentPrivate->childItems.lastIndexOf(this);
2081 int siblingIndex = parentPrivate->childItems.lastIndexOf(const_cast<QQuickItem *>(sibling));
2083 Q_ASSERT(myIndex != -1 && siblingIndex != -1);
2085 if (myIndex == siblingIndex - 1)
2088 parentPrivate->childItems.move(myIndex, myIndex < siblingIndex ? siblingIndex - 1 : siblingIndex);
2090 parentPrivate->dirty(QQuickItemPrivate::ChildrenStackingChanged);
2091 parentPrivate->markSortedChildrenDirty(this);
2093 for (int ii = qMin(siblingIndex, myIndex); ii < parentPrivate->childItems.count(); ++ii)
2094 QQuickItemPrivate::get(parentPrivate->childItems.at(ii))->siblingOrderChanged();
2098 Moves the specified \a sibling item to the index after this item
2099 within the visual stacking order.
2101 The given \a sibling must be a sibling of this item; that is, they must
2102 have the same immediate \l parent.
2104 \sa {Concepts - Visual Parent in Qt Quick}
2106 void QQuickItem::stackAfter(const QQuickItem *sibling)
2109 if (!sibling || sibling == this || !d->parentItem || d->parentItem != QQuickItemPrivate::get(sibling)->parentItem) {
2110 qWarning("QQuickItem::stackAfter: Cannot stack after %p, which must be a sibling", sibling);
2114 QQuickItemPrivate *parentPrivate = QQuickItemPrivate::get(d->parentItem);
2116 int myIndex = parentPrivate->childItems.lastIndexOf(this);
2117 int siblingIndex = parentPrivate->childItems.lastIndexOf(const_cast<QQuickItem *>(sibling));
2119 Q_ASSERT(myIndex != -1 && siblingIndex != -1);
2121 if (myIndex == siblingIndex + 1)
2124 parentPrivate->childItems.move(myIndex, myIndex > siblingIndex ? siblingIndex + 1 : siblingIndex);
2126 parentPrivate->dirty(QQuickItemPrivate::ChildrenStackingChanged);
2127 parentPrivate->markSortedChildrenDirty(this);
2129 for (int ii = qMin(myIndex, siblingIndex + 1); ii < parentPrivate->childItems.count(); ++ii)
2130 QQuickItemPrivate::get(parentPrivate->childItems.at(ii))->siblingOrderChanged();
2134 Returns the window in which this item is rendered.
2136 QQuickWindow *QQuickItem::window() const
2138 Q_D(const QQuickItem);
2142 static bool itemZOrder_sort(QQuickItem *lhs, QQuickItem *rhs)
2144 return lhs->z() < rhs->z();
2147 QList<QQuickItem *> QQuickItemPrivate::paintOrderChildItems() const
2149 if (sortedChildItems)
2150 return *sortedChildItems;
2152 // If none of the items have set Z then the paint order list is the same as
2153 // the childItems list. This is by far the most common case.
2155 for (int i = 0; i < childItems.count(); ++i) {
2156 if (QQuickItemPrivate::get(childItems.at(i))->z() != 0.) {
2162 sortedChildItems = new QList<QQuickItem*>(childItems);
2163 qStableSort(sortedChildItems->begin(), sortedChildItems->end(), itemZOrder_sort);
2164 return *sortedChildItems;
2167 sortedChildItems = const_cast<QList<QQuickItem*>*>(&childItems);
2172 void QQuickItemPrivate::addChild(QQuickItem *child)
2176 Q_ASSERT(!childItems.contains(child));
2178 childItems.append(child);
2180 markSortedChildrenDirty(child);
2181 dirty(QQuickItemPrivate::ChildrenChanged);
2183 itemChange(QQuickItem::ItemChildAddedChange, child);
2185 emit q->childrenChanged();
2188 void QQuickItemPrivate::removeChild(QQuickItem *child)
2193 Q_ASSERT(childItems.contains(child));
2194 childItems.removeOne(child);
2195 Q_ASSERT(!childItems.contains(child));
2197 markSortedChildrenDirty(child);
2198 dirty(QQuickItemPrivate::ChildrenChanged);
2200 itemChange(QQuickItem::ItemChildRemovedChange, child);
2202 emit q->childrenChanged();
2205 void QQuickItemPrivate::refWindow(QQuickWindow *c)
2207 // An item needs a window if it is referenced by another item which has a window.
2208 // Typically the item is referenced by a parent, but can also be referenced by a
2209 // ShaderEffect or ShaderEffectSource. 'windowRefCount' counts how many items with
2210 // a window is referencing this item. When the reference count goes from zero to one,
2211 // or one to zero, the window of this item is updated and propagated to the children.
2212 // As long as the reference count stays above zero, the window is unchanged.
2213 // refWindow() increments the reference count.
2214 // derefWindow() decrements the reference count.
2217 Q_ASSERT((window != 0) == (windowRefCount > 0));
2219 if (++windowRefCount > 1) {
2221 qWarning("QQuickItem: Cannot use same item on different windows at the same time.");
2222 return; // Window already set.
2225 Q_ASSERT(window == 0);
2228 if (polishScheduled)
2229 QQuickWindowPrivate::get(window)->itemsToPolish.insert(q);
2232 QQuickWindowPrivate::get(window)->parentlessItems.insert(q);
2234 for (int ii = 0; ii < childItems.count(); ++ii) {
2235 QQuickItem *child = childItems.at(ii);
2236 QQuickItemPrivate::get(child)->refWindow(c);
2241 if (extra.isAllocated() && extra->screenAttached)
2242 extra->screenAttached->windowChanged(c);
2243 itemChange(QQuickItem::ItemSceneChange, c);
2246 void QQuickItemPrivate::derefWindow()
2249 Q_ASSERT((window != 0) == (windowRefCount > 0));
2252 return; // This can happen when destroying recursive shader effect sources.
2254 if (--windowRefCount > 0)
2255 return; // There are still other references, so don't set window to null yet.
2257 q->releaseResources();
2258 removeFromDirtyList();
2259 QQuickWindowPrivate *c = QQuickWindowPrivate::get(window);
2260 if (polishScheduled)
2261 c->itemsToPolish.remove(q);
2262 QMutableHashIterator<int, QQuickItem *> itemTouchMapIt(c->itemForTouchPointId);
2263 while (itemTouchMapIt.hasNext()) {
2264 if (itemTouchMapIt.next().value() == q)
2265 itemTouchMapIt.remove();
2267 if (c->mouseGrabberItem == q)
2268 c->mouseGrabberItem = 0;
2269 #ifndef QT_NO_CURSOR
2270 if (c->cursorItem == q)
2274 c->hoverItems.removeAll(q);
2275 if (itemNodeInstance)
2276 c->cleanup(itemNodeInstance);
2278 c->parentlessItems.remove(q);
2282 itemNodeInstance = 0;
2284 if (extra.isAllocated()) {
2285 extra->opacityNode = 0;
2286 extra->clipNode = 0;
2287 extra->rootNode = 0;
2288 extra->beforePaintNode = 0;
2294 for (int ii = 0; ii < childItems.count(); ++ii) {
2295 QQuickItem *child = childItems.at(ii);
2296 QQuickItemPrivate::get(child)->derefWindow();
2301 if (extra.isAllocated() && extra->screenAttached)
2302 extra->screenAttached->windowChanged(0);
2303 itemChange(QQuickItem::ItemSceneChange, (QQuickWindow *)0);
2308 Returns a transform that maps points from window space into item space.
2310 QTransform QQuickItemPrivate::windowToItemTransform() const
2312 // XXX todo - optimize
2313 return itemToWindowTransform().inverted();
2317 Returns a transform that maps points from item space into window space.
2319 QTransform QQuickItemPrivate::itemToWindowTransform() const
2322 QTransform rv = parentItem?QQuickItemPrivate::get(parentItem)->itemToWindowTransform():QTransform();
2323 itemToParentTransform(rv);
2328 Motifies \a t with this items local transform relative to its parent.
2330 void QQuickItemPrivate::itemToParentTransform(QTransform &t) const
2335 if (!transforms.isEmpty()) {
2337 for (int ii = transforms.count() - 1; ii >= 0; --ii)
2338 transforms.at(ii)->applyTo(&m);
2339 t = m.toTransform();
2342 if (scale() != 1. || rotation() != 0.) {
2343 QPointF tp = computeTransformOrigin();
2344 t.translate(tp.x(), tp.y());
2345 t.scale(scale(), scale());
2346 t.rotate(rotation());
2347 t.translate(-tp.x(), -tp.y());
2352 Returns true if construction of the QML component is complete; otherwise
2355 It is often desirable to delay some processing until the component is
2358 \sa componentComplete()
2360 bool QQuickItem::isComponentComplete() const
2362 Q_D(const QQuickItem);
2363 return d->componentComplete;
2366 QQuickItemPrivate::QQuickItemPrivate()
2371 , heightValid(false)
2372 , baselineOffsetValid(false)
2373 , componentComplete(true)
2376 , hoverEnabled(false)
2378 , antialiasing(false)
2380 , activeFocus(false)
2381 , notifiedFocus(false)
2382 , notifiedActiveFocus(false)
2383 , filtersChildMouseEvents(false)
2384 , explicitVisible(true)
2385 , effectiveVisible(true)
2386 , explicitEnable(true)
2387 , effectiveEnable(true)
2388 , polishScheduled(false)
2389 , inheritedLayoutMirror(false)
2390 , effectiveLayoutMirror(false)
2391 , isMirrorImplicit(true)
2392 , inheritMirrorFromParent(false)
2393 , inheritMirrorFromItem(false)
2394 , isAccessible(false)
2397 , dirtyAttributes(0)
2403 , sortedChildItems(&childItems)
2412 , itemNodeInstance(0)
2418 QQuickItemPrivate::~QQuickItemPrivate()
2420 if (sortedChildItems != &childItems)
2421 delete sortedChildItems;
2424 void QQuickItemPrivate::init(QQuickItem *parent)
2428 static bool atexit_registered = false;
2429 if (!atexit_registered) {
2430 atexit(qt_print_item_count);
2431 atexit_registered = true;
2437 registerAccessorProperties();
2439 baselineOffsetValid = false;
2442 q->setParentItem(parent);
2443 QQuickItemPrivate *parentPrivate = QQuickItemPrivate::get(parent);
2444 setImplicitLayoutMirror(parentPrivate->inheritedLayoutMirror, parentPrivate->inheritMirrorFromParent);
2448 void QQuickItemPrivate::data_append(QQmlListProperty<QObject> *prop, QObject *o)
2453 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2455 if (QQuickItem *item = qmlobject_cast<QQuickItem *>(o)) {
2456 item->setParentItem(that);
2458 if (o->inherits("QGraphicsItem"))
2459 qWarning("Cannot add a QtQuick 1.0 item (%s) into a QtQuick 2.0 scene!", o->metaObject()->className());
2461 // XXX todo - do we really want this behavior?
2467 \qmlproperty list<Object> QtQuick2::Item::data
2470 The data property allows you to freely mix visual children and resources
2471 in an item. If you assign a visual item to the data list it becomes
2472 a child and if you assign any other object type, it is added as a resource.
2496 It should not generally be necessary to refer to the \c data property,
2497 as it is the default property for Item and thus all child items are
2498 automatically assigned to this property.
2501 int QQuickItemPrivate::data_count(QQmlListProperty<QObject> *prop)
2508 QObject *QQuickItemPrivate::data_at(QQmlListProperty<QObject> *prop, int i)
2516 void QQuickItemPrivate::data_clear(QQmlListProperty<QObject> *prop)
2522 QObject *QQuickItemPrivate::resources_at(QQmlListProperty<QObject> *prop, int index)
2524 const QObjectList children = prop->object->children();
2525 if (index < children.count())
2526 return children.at(index);
2531 void QQuickItemPrivate::resources_append(QQmlListProperty<QObject> *prop, QObject *o)
2533 // XXX todo - do we really want this behavior?
2534 o->setParent(prop->object);
2537 int QQuickItemPrivate::resources_count(QQmlListProperty<QObject> *prop)
2539 return prop->object->children().count();
2542 void QQuickItemPrivate::resources_clear(QQmlListProperty<QObject> *prop)
2544 // XXX todo - do we really want this behavior?
2545 const QObjectList children = prop->object->children();
2546 for (int index = 0; index < children.count(); index++)
2547 children.at(index)->setParent(0);
2550 QQuickItem *QQuickItemPrivate::children_at(QQmlListProperty<QQuickItem> *prop, int index)
2552 QQuickItemPrivate *p = QQuickItemPrivate::get(static_cast<QQuickItem *>(prop->object));
2553 if (index >= p->childItems.count() || index < 0)
2556 return p->childItems.at(index);
2559 void QQuickItemPrivate::children_append(QQmlListProperty<QQuickItem> *prop, QQuickItem *o)
2564 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2565 if (o->parentItem() == that)
2566 o->setParentItem(0);
2568 o->setParentItem(that);
2571 int QQuickItemPrivate::children_count(QQmlListProperty<QQuickItem> *prop)
2573 QQuickItemPrivate *p = QQuickItemPrivate::get(static_cast<QQuickItem *>(prop->object));
2574 return p->childItems.count();
2577 void QQuickItemPrivate::children_clear(QQmlListProperty<QQuickItem> *prop)
2579 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2580 QQuickItemPrivate *p = QQuickItemPrivate::get(that);
2581 while (!p->childItems.isEmpty())
2582 p->childItems.at(0)->setParentItem(0);
2585 void QQuickItemPrivate::visibleChildren_append(QQmlListProperty<QQuickItem>*, QQuickItem *self)
2588 qmlInfo(self) << "QQuickItem: visibleChildren property is readonly and cannot be assigned to.";
2591 int QQuickItemPrivate::visibleChildren_count(QQmlListProperty<QQuickItem> *prop)
2593 QQuickItemPrivate *p = QQuickItemPrivate::get(static_cast<QQuickItem *>(prop->object));
2594 int visibleCount = 0;
2595 int c = p->childItems.count();
2597 if (p->childItems.at(c)->isVisible()) visibleCount++;
2600 return visibleCount;
2603 QQuickItem *QQuickItemPrivate::visibleChildren_at(QQmlListProperty<QQuickItem> *prop, int index)
2605 QQuickItemPrivate *p = QQuickItemPrivate::get(static_cast<QQuickItem *>(prop->object));
2606 const int childCount = p->childItems.count();
2607 if (index >= childCount || index < 0)
2610 int visibleCount = -1;
2611 for (int i = 0; i < childCount; i++) {
2612 if (p->childItems.at(i)->isVisible()) visibleCount++;
2613 if (visibleCount == index) return p->childItems.at(i);
2618 int QQuickItemPrivate::transform_count(QQmlListProperty<QQuickTransform> *prop)
2620 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2621 QQuickItemPrivate *p = QQuickItemPrivate::get(that);
2623 return p->transforms.count();
2626 void QQuickTransform::appendToItem(QQuickItem *item)
2628 Q_D(QQuickTransform);
2632 QQuickItemPrivate *p = QQuickItemPrivate::get(item);
2634 if (!d->items.isEmpty() && !p->transforms.isEmpty() && p->transforms.contains(this)) {
2635 p->transforms.removeOne(this);
2636 p->transforms.append(this);
2638 p->transforms.append(this);
2639 d->items.append(item);
2642 p->dirty(QQuickItemPrivate::Transform);
2645 void QQuickTransform::prependToItem(QQuickItem *item)
2647 Q_D(QQuickTransform);
2651 QQuickItemPrivate *p = QQuickItemPrivate::get(item);
2653 if (!d->items.isEmpty() && !p->transforms.isEmpty() && p->transforms.contains(this)) {
2654 p->transforms.removeOne(this);
2655 p->transforms.prepend(this);
2657 p->transforms.prepend(this);
2658 d->items.append(item);
2661 p->dirty(QQuickItemPrivate::Transform);
2664 void QQuickItemPrivate::transform_append(QQmlListProperty<QQuickTransform> *prop, QQuickTransform *transform)
2669 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2670 transform->appendToItem(that);
2673 QQuickTransform *QQuickItemPrivate::transform_at(QQmlListProperty<QQuickTransform> *prop, int idx)
2675 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2676 QQuickItemPrivate *p = QQuickItemPrivate::get(that);
2678 if (idx < 0 || idx >= p->transforms.count())
2681 return p->transforms.at(idx);
2684 void QQuickItemPrivate::transform_clear(QQmlListProperty<QQuickTransform> *prop)
2686 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2687 QQuickItemPrivate *p = QQuickItemPrivate::get(that);
2689 for (int ii = 0; ii < p->transforms.count(); ++ii) {
2690 QQuickTransform *t = p->transforms.at(ii);
2691 QQuickTransformPrivate *tp = QQuickTransformPrivate::get(t);
2692 tp->items.removeOne(that);
2695 p->transforms.clear();
2697 p->dirty(QQuickItemPrivate::Transform);
2701 \qmlproperty AnchorLine QtQuick2::Item::anchors.top
2702 \qmlproperty AnchorLine QtQuick2::Item::anchors.bottom
2703 \qmlproperty AnchorLine QtQuick2::Item::anchors.left
2704 \qmlproperty AnchorLine QtQuick2::Item::anchors.right
2705 \qmlproperty AnchorLine QtQuick2::Item::anchors.horizontalCenter
2706 \qmlproperty AnchorLine QtQuick2::Item::anchors.verticalCenter
2707 \qmlproperty AnchorLine QtQuick2::Item::anchors.baseline
2709 \qmlproperty Item QtQuick2::Item::anchors.fill
2710 \qmlproperty Item QtQuick2::Item::anchors.centerIn
2712 \qmlproperty real QtQuick2::Item::anchors.margins
2713 \qmlproperty real QtQuick2::Item::anchors.topMargin
2714 \qmlproperty real QtQuick2::Item::anchors.bottomMargin
2715 \qmlproperty real QtQuick2::Item::anchors.leftMargin
2716 \qmlproperty real QtQuick2::Item::anchors.rightMargin
2717 \qmlproperty real QtQuick2::Item::anchors.horizontalCenterOffset
2718 \qmlproperty real QtQuick2::Item::anchors.verticalCenterOffset
2719 \qmlproperty real QtQuick2::Item::anchors.baselineOffset
2721 \qmlproperty bool QtQuick2::Item::anchors.alignWhenCentered
2723 Anchors provide a way to position an item by specifying its
2724 relationship with other items.
2726 Margins apply to top, bottom, left, right, and fill anchors.
2727 The \c anchors.margins property can be used to set all of the various margins at once, to the same value.
2728 It will not override a specific margin that has been previously set; to clear an explicit margin
2729 set it's value to \c undefined.
2730 Note that margins are anchor-specific and are not applied if an item does not
2733 Offsets apply for horizontal center, vertical center, and baseline anchors.
2737 \li \image declarative-anchors_example.png
2738 \li Text anchored to Image, horizontally centered and vertically below, with a margin.
2747 anchors.horizontalCenter: pic.horizontalCenter
2748 anchors.top: pic.bottom
2749 anchors.topMargin: 5
2755 \li \image declarative-anchors_example2.png
2757 Left of Text anchored to right of Image, with a margin. The y
2758 property of both defaults to 0.
2768 anchors.left: pic.right
2769 anchors.leftMargin: 5
2776 \c anchors.fill provides a convenient way for one item to have the
2777 same geometry as another item, and is equivalent to connecting all
2778 four directional anchors.
2780 To clear an anchor value, set it to \c undefined.
2782 \c anchors.alignWhenCentered (default true) forces centered anchors to align to a
2783 whole pixel, i.e. if the item being centered has an odd width/height the item
2784 will be positioned on a whole pixel rather than being placed on a half-pixel.
2785 This ensures the item is painted crisply. There are cases where this is not
2786 desirable, for example when rotating the item jitters may be apparent as the
2789 \note You can only anchor an item to siblings or a parent.
2791 For more information see \l {anchor-layout}{Anchor Layouts}.
2793 QQuickAnchors *QQuickItemPrivate::anchors() const
2796 Q_Q(const QQuickItem);
2797 _anchors = new QQuickAnchors(const_cast<QQuickItem *>(q));
2798 if (!componentComplete)
2799 _anchors->classBegin();
2804 void QQuickItemPrivate::siblingOrderChanged()
2807 for (int ii = 0; ii < changeListeners.count(); ++ii) {
2808 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
2809 if (change.types & QQuickItemPrivate::SiblingOrder) {
2810 change.listener->itemSiblingOrderChanged(q);
2815 QQmlListProperty<QObject> QQuickItemPrivate::data()
2817 return QQmlListProperty<QObject>(q_func(), 0, QQuickItemPrivate::data_append,
2818 QQuickItemPrivate::data_count,
2819 QQuickItemPrivate::data_at,
2820 QQuickItemPrivate::data_clear);
2824 \qmlproperty real QtQuick2::Item::childrenRect.x
2825 \qmlproperty real QtQuick2::Item::childrenRect.y
2826 \qmlproperty real QtQuick2::Item::childrenRect.width
2827 \qmlproperty real QtQuick2::Item::childrenRect.height
2829 This property holds the collective position and size of the item's
2832 This property is useful if you need to access the collective geometry
2833 of an item's children in order to correctly size the item.
2836 \property QQuickItem::childrenRect
2838 This property holds the collective position and size of the item's
2841 This property is useful if you need to access the collective geometry
2842 of an item's children in order to correctly size the item.
2844 QRectF QQuickItem::childrenRect()
2847 if (!d->extra.isAllocated() || !d->extra->contents) {
2848 d->extra.value().contents = new QQuickContents(this);
2849 if (d->componentComplete)
2850 d->extra->contents->complete();
2852 return d->extra->contents->rectF();
2856 Returns the children of this item.
2858 QList<QQuickItem *> QQuickItem::childItems() const
2860 Q_D(const QQuickItem);
2861 return d->childItems;
2865 \qmlproperty bool QtQuick2::Item::clip
2866 This property holds whether clipping is enabled. The default clip value is \c false.
2868 If clipping is enabled, an item will clip its own painting, as well
2869 as the painting of its children, to its bounding rectangle.
2871 Non-rectangular clipping regions are not supported for performance reasons.
2874 \property QQuickItem::clip
2875 This property holds whether clipping is enabled. The default clip value is \c false.
2877 If clipping is enabled, an item will clip its own painting, as well
2878 as the painting of its children, to its bounding rectangle. If you set
2879 clipping during an item's paint operation, remember to re-set it to
2880 prevent clipping the rest of your scene.
2882 Non-rectangular clipping regions are not supported for performance reasons.
2884 bool QQuickItem::clip() const
2886 return flags() & ItemClipsChildrenToShape;
2889 void QQuickItem::setClip(bool c)
2894 setFlag(ItemClipsChildrenToShape, c);
2896 emit clipChanged(c);
2901 This function is called to handle this item's changes in
2902 geometry from \a oldGeometry to \a newGeometry. If the two
2903 geometries are the same, it doesn't do anything.
2905 Derived classes must call the base class method within their implementation.
2907 void QQuickItem::geometryChanged(const QRectF &newGeometry, const QRectF &oldGeometry)
2912 QQuickAnchorsPrivate::get(d->_anchors)->updateMe();
2914 bool xChange = (newGeometry.x() != oldGeometry.x());
2915 bool yChange = (newGeometry.y() != oldGeometry.y());
2916 bool widthChange = (newGeometry.width() != oldGeometry.width());
2917 bool heightChange = (newGeometry.height() != oldGeometry.height());
2919 for (int ii = 0; ii < d->changeListeners.count(); ++ii) {
2920 const QQuickItemPrivate::ChangeListener &change = d->changeListeners.at(ii);
2921 if (change.types & QQuickItemPrivate::Geometry) {
2922 if (change.gTypes == QQuickItemPrivate::GeometryChange) {
2923 change.listener->itemGeometryChanged(this, newGeometry, oldGeometry);
2924 } else if ((xChange && (change.gTypes & QQuickItemPrivate::XChange)) ||
2925 (yChange && (change.gTypes & QQuickItemPrivate::YChange)) ||
2926 (widthChange && (change.gTypes & QQuickItemPrivate::WidthChange)) ||
2927 (heightChange && (change.gTypes & QQuickItemPrivate::HeightChange))) {
2928 change.listener->itemGeometryChanged(this, newGeometry, oldGeometry);
2938 emit widthChanged();
2940 emit heightChanged();
2944 Called by the rendering thread, as a result of
2945 QQuickItem::update(), when it is time to sync the state of the QML
2946 objects with the scene graph objects.
2948 The function should return the root of the scene graph subtree for
2949 this item. Most implementations will return a single
2950 QSGGeometryNode containing the visual representation of this item.
2951 \a oldNode is the node that was returned the last time the
2952 function was called.
2955 QSGNode *MyItem::updatePaintNode(QSGNode *node, UpdatePaintNodeData *)
2957 QSGSimpleRectNode *n = static_cast<QSGSimpleRectNode *>(node);
2959 n = new QSGSimpleRectNode();
2960 n->setColor(Qt::red);
2962 n->setRect(boundingRect());
2967 The main thread is blocked while this function is executed so it is safe to read
2968 values from the QQuickItem instance and other objects in the main thread.
2970 If no call to QQuickItem::updatePaintNode() result in actual scene graph
2971 changes, like QSGNode::markDirty() or adding and removing nodes, then
2972 the underlying implementation may decide to not render the scene again as
2973 the visual outcome is identical.
2975 \warning It is crucial that OpenGL operations and interaction with
2976 the scene graph happens exclusively on the rendering thread,
2977 primarily during the QQuickItem::updatePaintNode() call. The best
2978 rule of thumb is to only use classes with the "QSG" prefix inside
2979 the QQuickItem::updatePaintNode() function.
2981 \sa QSGMaterial, QSGSimpleMaterial, QSGGeometryNode, QSGGeometry,
2982 QSGFlatColorMaterial, QSGTextureMaterial, QSGNode::markDirty()
2985 QSGNode *QQuickItem::updatePaintNode(QSGNode *oldNode, UpdatePaintNodeData *)
2992 This function is called when the item's scene graph resources are no longer needed.
2993 It allows items to free its resources, for instance textures, that are not owned by scene graph
2994 nodes. Note that scene graph nodes are managed by QQuickWindow and should not be deleted by
2995 this function. Scene graph resources are no longer needed when the parent is set to null and
2996 the item is not used by any \l ShaderEffect or \l ShaderEffectSource.
2998 This function is called from the main thread. Therefore, resources used by the scene graph
2999 should not be deleted directly, but by calling \l QObject::deleteLater().
3001 \note The item destructor still needs to free its scene graph resources if not already done.
3004 void QQuickItem::releaseResources()
3008 QSGTransformNode *QQuickItemPrivate::createTransformNode()
3010 return new QSGTransformNode;
3014 This function should perform any layout as required for this item.
3016 When polish() is called, the scene graph schedules a polish event for this
3017 item. When the scene graph is ready to render this item, it calls
3018 updatePolish() to do any item layout as required before it renders the
3021 void QQuickItem::updatePolish()
3025 void QQuickItemPrivate::addItemChangeListener(QQuickItemChangeListener *listener, ChangeTypes types)
3027 changeListeners.append(ChangeListener(listener, types));
3030 void QQuickItemPrivate::removeItemChangeListener(QQuickItemChangeListener *listener, ChangeTypes types)
3032 ChangeListener change(listener, types);
3033 changeListeners.removeOne(change);
3036 void QQuickItemPrivate::updateOrAddGeometryChangeListener(QQuickItemChangeListener *listener, GeometryChangeTypes types)
3038 ChangeListener change(listener, types);
3039 int index = changeListeners.find(change);
3041 changeListeners[index].gTypes = change.gTypes; //we may have different GeometryChangeTypes
3043 changeListeners.append(change);
3046 void QQuickItemPrivate::updateOrRemoveGeometryChangeListener(QQuickItemChangeListener *listener,
3047 GeometryChangeTypes types)
3049 ChangeListener change(listener, types);
3050 if (types == NoChange) {
3051 changeListeners.removeOne(change);
3053 int index = changeListeners.find(change);
3055 changeListeners[index].gTypes = change.gTypes; //we may have different GeometryChangeTypes
3060 This event handler can be reimplemented in a subclass to receive key
3061 press events for an item. The event information is provided by the
3064 void QQuickItem::keyPressEvent(QKeyEvent *event)
3070 This event handler can be reimplemented in a subclass to receive key
3071 release events for an item. The event information is provided by the
3074 void QQuickItem::keyReleaseEvent(QKeyEvent *event)
3080 This event handler can be reimplemented in a subclass to receive input
3081 method events for an item. The event information is provided by the
3084 void QQuickItem::inputMethodEvent(QInputMethodEvent *event)
3090 This event handler can be reimplemented in a subclass to receive focus-in
3091 events for an item. The event information is provided by the
3094 void QQuickItem::focusInEvent(QFocusEvent *event)
3096 #ifndef QT_NO_ACCESSIBILITY
3097 QAccessibleEvent ev(this, QAccessible::Focus);
3098 QAccessible::updateAccessibility(&ev);
3103 This event handler can be reimplemented in a subclass to receive focus-out
3104 events for an item. The event information is provided by the
3107 void QQuickItem::focusOutEvent(QFocusEvent *event)
3112 This event handler can be reimplemented in a subclass to receive mouse
3113 press events for an item. The event information is provided by the
3116 void QQuickItem::mousePressEvent(QMouseEvent *event)
3122 This event handler can be reimplemented in a subclass to receive mouse
3123 move events for an item. The event information is provided by the
3126 void QQuickItem::mouseMoveEvent(QMouseEvent *event)
3132 This event handler can be reimplemented in a subclass to receive mouse
3133 release events for an item. The event information is provided by the
3136 void QQuickItem::mouseReleaseEvent(QMouseEvent *event)
3142 This event handler can be reimplemented in a subclass to receive mouse
3143 double-click events for an item. The event information is provided by the
3146 void QQuickItem::mouseDoubleClickEvent(QMouseEvent *)
3151 This event handler can be reimplemented in a subclass to be notified
3152 when a mouse ungrab event has occurred on this item.
3156 void QQuickItem::mouseUngrabEvent()
3162 This event handler can be reimplemented in a subclass to be notified
3163 when a touch ungrab event has occurred on this item.
3165 void QQuickItem::touchUngrabEvent()
3171 This event handler can be reimplemented in a subclass to receive
3172 wheel events for an item. The event information is provided by the
3175 void QQuickItem::wheelEvent(QWheelEvent *event)
3181 This event handler can be reimplemented in a subclass to receive touch
3182 events for an item. The event information is provided by the
3185 void QQuickItem::touchEvent(QTouchEvent *event)
3191 This event handler can be reimplemented in a subclass to receive hover-enter
3192 events for an item. The event information is provided by the
3195 Hover events are only provided if acceptHoverEvents() is true.
3197 void QQuickItem::hoverEnterEvent(QHoverEvent *event)
3203 This event handler can be reimplemented in a subclass to receive hover-move
3204 events for an item. The event information is provided by the
3207 Hover events are only provided if acceptHoverEvents() is true.
3209 void QQuickItem::hoverMoveEvent(QHoverEvent *event)
3215 This event handler can be reimplemented in a subclass to receive hover-leave
3216 events for an item. The event information is provided by the
3219 Hover events are only provided if acceptHoverEvents() is true.
3221 void QQuickItem::hoverLeaveEvent(QHoverEvent *event)
3226 #ifndef QT_NO_DRAGANDDROP
3228 This event handler can be reimplemented in a subclass to receive drag-enter
3229 events for an item. The event information is provided by the
3232 Drag and drop events are only provided if the ItemAcceptsDrops flag
3233 has been set for this item.
3235 \sa Drag, {Drag and Drop}
3237 void QQuickItem::dragEnterEvent(QDragEnterEvent *event)
3243 This event handler can be reimplemented in a subclass to receive drag-move
3244 events for an item. The event information is provided by the
3247 Drag and drop events are only provided if the ItemAcceptsDrops flag
3248 has been set for this item.
3250 \sa Drag, {Drag and Drop}
3252 void QQuickItem::dragMoveEvent(QDragMoveEvent *event)
3258 This event handler can be reimplemented in a subclass to receive drag-leave
3259 events for an item. The event information is provided by the
3262 Drag and drop events are only provided if the ItemAcceptsDrops flag
3263 has been set for this item.
3265 \sa Drag, {Drag and Drop}
3267 void QQuickItem::dragLeaveEvent(QDragLeaveEvent *event)
3273 This event handler can be reimplemented in a subclass to receive drop
3274 events for an item. The event information is provided by the
3277 Drag and drop events are only provided if the ItemAcceptsDrops flag
3278 has been set for this item.
3280 \sa Drag, {Drag and Drop}
3282 void QQuickItem::dropEvent(QDropEvent *event)
3286 #endif // QT_NO_DRAGANDDROP
3289 Reimplement this method to filter the mouse events that are received by
3290 this item's children.
3292 This method will only be called if filtersChildMouseEvents() is true.
3294 Return true if the specified \a event should not be passed onto the
3295 specified child \a item, and false otherwise.
3297 \sa setFiltersChildMouseEvents()
3299 bool QQuickItem::childMouseEventFilter(QQuickItem *item, QEvent *event)
3309 void QQuickItem::windowDeactivateEvent()
3311 foreach (QQuickItem* item, childItems()) {
3312 item->windowDeactivateEvent();
3317 This method is only relevant for input items.
3319 If this item is an input item, this method should be reimplemented to
3320 return the relevant input method flags for the given \a query.
3322 \sa QWidget::inputMethodQuery()
3324 QVariant QQuickItem::inputMethodQuery(Qt::InputMethodQuery query) const
3326 Q_D(const QQuickItem);
3331 v = (bool)(flags() & ItemAcceptsInputMethod);
3334 case Qt::ImCursorRectangle:
3336 case Qt::ImCursorPosition:
3337 case Qt::ImSurroundingText:
3338 case Qt::ImCurrentSelection:
3339 case Qt::ImMaximumTextLength:
3340 case Qt::ImAnchorPosition:
3341 case Qt::ImPreferredLanguage:
3342 if (d->extra.isAllocated() && d->extra->keyHandler)
3343 v = d->extra->keyHandler->inputMethodQuery(query);
3351 QQuickAnchorLine QQuickItemPrivate::left() const
3353 Q_Q(const QQuickItem);
3354 return QQuickAnchorLine(const_cast<QQuickItem *>(q), QQuickAnchorLine::Left);
3357 QQuickAnchorLine QQuickItemPrivate::right() const
3359 Q_Q(const QQuickItem);
3360 return QQuickAnchorLine(const_cast<QQuickItem *>(q), QQuickAnchorLine::Right);
3363 QQuickAnchorLine QQuickItemPrivate::horizontalCenter() const
3365 Q_Q(const QQuickItem);
3366 return QQuickAnchorLine(const_cast<QQuickItem *>(q), QQuickAnchorLine::HCenter);
3369 QQuickAnchorLine QQuickItemPrivate::top() const
3371 Q_Q(const QQuickItem);
3372 return QQuickAnchorLine(const_cast<QQuickItem *>(q), QQuickAnchorLine::Top);
3375 QQuickAnchorLine QQuickItemPrivate::bottom() const
3377 Q_Q(const QQuickItem);
3378 return QQuickAnchorLine(const_cast<QQuickItem *>(q), QQuickAnchorLine::Bottom);
3381 QQuickAnchorLine QQuickItemPrivate::verticalCenter() const
3383 Q_Q(const QQuickItem);
3384 return QQuickAnchorLine(const_cast<QQuickItem *>(q), QQuickAnchorLine::VCenter);
3387 QQuickAnchorLine QQuickItemPrivate::baseline() const
3389 Q_Q(const QQuickItem);
3390 return QQuickAnchorLine(const_cast<QQuickItem *>(q), QQuickAnchorLine::Baseline);
3394 \qmlproperty int QtQuick2::Item::baselineOffset
3396 Specifies the position of the item's baseline in local coordinates.
3398 The baseline of a \l Text item is the imaginary line on which the text
3399 sits. Controls containing text usually set their baseline to the
3400 baseline of their text.
3402 For non-text items, a default baseline offset of 0 is used.
3405 \property QQuickItem::baselineOffset
3407 Specifies the position of the item's baseline in local coordinates.
3409 The baseline of a \l Text item is the imaginary line on which the text
3410 sits. Controls containing text usually set their baseline to the
3411 baseline of their text.
3413 For non-text items, a default baseline offset of 0 is used.
3415 qreal QQuickItem::baselineOffset() const
3417 Q_D(const QQuickItem);
3418 if (d->baselineOffsetValid) {
3419 return d->baselineOffset;
3425 void QQuickItem::setBaselineOffset(qreal offset)
3428 if (offset == d->baselineOffset)
3431 d->baselineOffset = offset;
3432 d->baselineOffsetValid = true;
3434 for (int ii = 0; ii < d->changeListeners.count(); ++ii) {
3435 const QQuickItemPrivate::ChangeListener &change = d->changeListeners.at(ii);
3436 if (change.types & QQuickItemPrivate::Geometry) {
3437 QQuickAnchorsPrivate *anchor = change.listener->anchorPrivate();
3439 anchor->updateVerticalAnchors();
3443 if (d->_anchors && (d->_anchors->usedAnchors() & QQuickAnchors::BaselineAnchor))
3444 QQuickAnchorsPrivate::get(d->_anchors)->updateVerticalAnchors();
3446 emit baselineOffsetChanged(offset);
3451 * Schedules a call to updatePaintNode() for this item.
3453 * The call to QQuickItem::updatePaintNode() will always happen if the
3454 * item is showing in a QQuickWindow.
3456 * Only items which specifies QQuickItem::ItemHasContents are allowed
3457 * to call QQuickItem::update().
3459 void QQuickItem::update()
3462 Q_ASSERT(flags() & ItemHasContents);
3463 d->dirty(QQuickItemPrivate::Content);
3467 Schedules a polish event for this item.
3469 When the scene graph processes the request, it will call updatePolish()
3472 void QQuickItem::polish()
3475 if (!d->polishScheduled) {
3476 d->polishScheduled = true;
3478 QQuickWindowPrivate *p = QQuickWindowPrivate::get(d->window);
3479 bool maybeupdate = p->itemsToPolish.isEmpty();
3480 p->itemsToPolish.insert(this);
3481 if (maybeupdate) d->window->maybeUpdate();
3487 \qmlmethod object QtQuick2::Item::mapFromItem(Item item, real x, real y)
3488 \qmlmethod object QtQuick2::Item::mapFromItem(Item item, real x, real y, real width, real height)
3490 Maps the point (\a x, \a y) or rect (\a x, \a y, \a width, \a height), which is in \a
3491 item's coordinate system, to this item's coordinate system, and returns an object with \c x and
3492 \c y (and optionally \c width and \c height) properties matching the mapped coordinate.
3494 If \a item is a \c null value, this maps the point or rect from the coordinate system of
3500 void QQuickItem::mapFromItem(QQmlV8Function *args) const
3502 if (args->Length() != 0) {
3503 v8::Local<v8::Value> item = (*args)[0];
3504 QV8Engine *engine = args->engine();
3506 QQuickItem *itemObj = 0;
3507 if (!item->IsNull())
3508 itemObj = qobject_cast<QQuickItem*>(engine->toQObject(item));
3510 if (!itemObj && !item->IsNull()) {
3511 qmlInfo(this) << "mapFromItem() given argument \"" << engine->toString(item->ToString())
3512 << "\" which is neither null nor an Item";
3516 v8::Local<v8::Object> rv = v8::Object::New();
3517 args->returnValue(rv);
3519 qreal x = (args->Length() > 1)?(*args)[1]->NumberValue():0;
3520 qreal y = (args->Length() > 2)?(*args)[2]->NumberValue():0;
3522 if (args->Length() > 3) {
3523 qreal w = (*args)[3]->NumberValue();
3524 qreal h = (args->Length() > 4)?(*args)[4]->NumberValue():0;
3526 QRectF r = mapRectFromItem(itemObj, QRectF(x, y, w, h));
3528 rv->Set(v8::String::New("x"), v8::Number::New(r.x()));
3529 rv->Set(v8::String::New("y"), v8::Number::New(r.y()));
3530 rv->Set(v8::String::New("width"), v8::Number::New(r.width()));
3531 rv->Set(v8::String::New("height"), v8::Number::New(r.height()));
3533 QPointF p = mapFromItem(itemObj, QPointF(x, y));
3535 rv->Set(v8::String::New("x"), v8::Number::New(p.x()));
3536 rv->Set(v8::String::New("y"), v8::Number::New(p.y()));
3544 QTransform QQuickItem::itemTransform(QQuickItem *other, bool *ok) const
3546 Q_D(const QQuickItem);
3548 // XXX todo - we need to be able to handle common parents better and detect
3552 QTransform t = d->itemToWindowTransform();
3553 if (other) t *= QQuickItemPrivate::get(other)->windowToItemTransform();
3559 \qmlmethod object QtQuick2::Item::mapToItem(Item item, real x, real y)
3560 \qmlmethod object QtQuick2::Item::mapToItem(Item item, real x, real y, real width, real height)
3562 Maps the point (\a x, \a y) or rect (\a x, \a y, \a width, \a height), which is in this
3563 item's coordinate system, to \a item's coordinate system, and returns an object with \c x and
3564 \c y (and optionally \c width and \c height) properties matching the mapped coordinate.
3566 If \a item is a \c null value, this maps the point or rect to the coordinate system of the
3572 void QQuickItem::mapToItem(QQmlV8Function *args) const
3574 if (args->Length() != 0) {
3575 v8::Local<v8::Value> item = (*args)[0];
3576 QV8Engine *engine = args->engine();
3578 QQuickItem *itemObj = 0;
3579 if (!item->IsNull())
3580 itemObj = qobject_cast<QQuickItem*>(engine->toQObject(item));
3582 if (!itemObj && !item->IsNull()) {
3583 qmlInfo(this) << "mapToItem() given argument \"" << engine->toString(item->ToString())
3584 << "\" which is neither null nor an Item";
3588 v8::Local<v8::Object> rv = v8::Object::New();
3589 args->returnValue(rv);
3591 qreal x = (args->Length() > 1)?(*args)[1]->NumberValue():0;
3592 qreal y = (args->Length() > 2)?(*args)[2]->NumberValue():0;
3594 if (args->Length() > 3) {
3595 qreal w = (*args)[3]->NumberValue();
3596 qreal h = (args->Length() > 4)?(*args)[4]->NumberValue():0;
3598 QRectF r = mapRectToItem(itemObj, QRectF(x, y, w, h));
3600 rv->Set(v8::String::New("x"), v8::Number::New(r.x()));
3601 rv->Set(v8::String::New("y"), v8::Number::New(r.y()));
3602 rv->Set(v8::String::New("width"), v8::Number::New(r.width()));
3603 rv->Set(v8::String::New("height"), v8::Number::New(r.height()));
3605 QPointF p = mapToItem(itemObj, QPointF(x, y));
3607 rv->Set(v8::String::New("x"), v8::Number::New(p.x()));
3608 rv->Set(v8::String::New("y"), v8::Number::New(p.y()));
3614 \qmlmethod QtQuick2::Item::forceActiveFocus()
3616 Forces active focus on the item.
3618 This method sets focus on the item and ensures that all ancestor
3619 FocusScope objects in the object hierarchy are also given \l focus.
3624 Forces active focus on the item.
3626 This method sets focus on the item and ensures that all ancestor
3627 FocusScope objects in the object hierarchy are also given \l focus.
3631 void QQuickItem::forceActiveFocus()
3634 QQuickItem *parent = parentItem();
3636 if (parent->flags() & QQuickItem::ItemIsFocusScope) {
3637 parent->setFocus(true);
3639 parent = parent->parentItem();
3644 \qmlmethod QtQuick2::Item::childAt(real x, real y)
3646 Returns the first visible child item found at point (\a x, \a y) within
3647 the coordinate system of this item.
3649 Returns \c null if there is no such item.
3652 Returns the first visible child item found at point (\a x, \a y) within
3653 the coordinate system of this item.
3655 Returns 0 if there is no such item.
3657 QQuickItem *QQuickItem::childAt(qreal x, qreal y) const
3659 // XXX todo - should this include transform etc.?
3660 const QList<QQuickItem *> children = childItems();
3661 for (int i = children.count()-1; i >= 0; --i) {
3662 QQuickItem *child = children.at(i);
3663 if (child->isVisible() && child->x() <= x
3664 && child->x() + child->width() >= x
3666 && child->y() + child->height() >= y)
3672 QQmlListProperty<QObject> QQuickItemPrivate::resources()
3674 return QQmlListProperty<QObject>(q_func(), 0, QQuickItemPrivate::resources_append,
3675 QQuickItemPrivate::resources_count,
3676 QQuickItemPrivate::resources_at,
3677 QQuickItemPrivate::resources_clear);
3681 \qmlproperty list<Item> QtQuick2::Item::children
3682 \qmlproperty list<Object> QtQuick2::Item::resources
3684 The children property contains the list of visual children of this item.
3685 The resources property contains non-visual resources that you want to
3688 It is not generally necessary to refer to these properties when adding
3689 child items or resources, as the default \l data property will
3690 automatically assign child objects to the \c children and \c resources
3691 properties as appropriate. See the \l data documentation for details.
3694 \property QQuickItem::children
3698 \fn void QQuickItem::childrenChanged()
3701 QQmlListProperty<QQuickItem> QQuickItemPrivate::children()
3703 return QQmlListProperty<QQuickItem>(q_func(), 0, QQuickItemPrivate::children_append,
3704 QQuickItemPrivate::children_count,
3705 QQuickItemPrivate::children_at,
3706 QQuickItemPrivate::children_clear);
3711 \qmlproperty real QtQuick2::Item::visibleChildren
3712 This read-only property lists all of the item's children that are currently visible.
3713 Note that a child's visibility may have changed explicitly, or because the visibility
3714 of this (it's parent) item or another grandparent changed.
3717 \property QQuickItem::visibleChildren
3721 \fn void QQuickItem::visibleChildrenChanged()
3724 QQmlListProperty<QQuickItem> QQuickItemPrivate::visibleChildren()
3726 return QQmlListProperty<QQuickItem>(q_func(), 0, QQuickItemPrivate::visibleChildren_append,
3727 QQuickItemPrivate::visibleChildren_count,
3728 QQuickItemPrivate::visibleChildren_at);
3733 \qmlproperty list<State> QtQuick2::Item::states
3735 This property holds the list of possible states for this item. To change
3736 the state of this item, set the \l state property to one of these states,
3737 or set the \l state property to an empty string to revert the item to its
3740 This property is specified as a list of \l State objects. For example,
3741 below is an item with "red_color" and "blue_color" states:
3748 width: 100; height: 100
3753 PropertyChanges { target: root; color: "red" }
3757 PropertyChanges { target: root; color: "blue" }
3763 See \l{Qt Quick States} and \l{Animation and Transitions in Qt Quick} for
3764 more details on using states and transitions.
3769 \property QQuickItem::states
3772 QQmlListProperty<QQuickState> QQuickItemPrivate::states()
3774 return _states()->statesProperty();
3778 \qmlproperty list<Transition> QtQuick2::Item::transitions
3780 This property holds the list of transitions for this item. These define the
3781 transitions to be applied to the item whenever it changes its \l state.
3783 This property is specified as a list of \l Transition objects. For example:
3800 See \l{Qt Quick States} and \l{Animation and Transitions in Qt Quick} for
3801 more details on using states and transitions.
3806 \property QQuickItem::transitions
3809 QQmlListProperty<QQuickTransition> QQuickItemPrivate::transitions()
3811 return _states()->transitionsProperty();
3814 QString QQuickItemPrivate::state() const
3819 return _stateGroup->state();
3822 void QQuickItemPrivate::setState(const QString &state)
3824 _states()->setState(state);
3828 \qmlproperty string QtQuick2::Item::state
3830 This property holds the name of the current state of the item.
3832 If the item is in its default state — that is, no explicit state has been
3833 set — then this property holds an empty string. Likewise, you can return
3834 an item to its default state by setting this property to an empty string.
3836 \sa {Qt Quick States}
3839 \property QQuickItem::state
3841 This property holds the name of the current state of the item.
3843 If the item is in its default state — that is, no explicit state has been
3844 set — then this property holds an empty string. Likewise, you can return
3845 an item to its default state by setting this property to an empty string.
3847 \sa {Qt Quick States}
3849 QString QQuickItem::state() const
3851 Q_D(const QQuickItem);
3855 void QQuickItem::setState(const QString &state)
3862 \qmlproperty list<Transform> QtQuick2::Item::transform
3863 This property holds the list of transformations to apply.
3865 For more information see \l Transform.
3868 \property QQuickItem::transform
3871 QQmlListProperty<QQuickTransform> QQuickItem::transform()
3873 return QQmlListProperty<QQuickTransform>(this, 0, QQuickItemPrivate::transform_append,
3874 QQuickItemPrivate::transform_count,
3875 QQuickItemPrivate::transform_at,
3876 QQuickItemPrivate::transform_clear);
3881 Derived classes should call the base class method before adding their own action to
3882 perform at classBegin.
3884 void QQuickItem::classBegin()
3887 d->componentComplete = false;
3889 d->_stateGroup->classBegin();
3891 d->_anchors->classBegin();
3892 if (d->extra.isAllocated() && d->extra->layer)
3893 d->extra->layer->classBegin();
3898 Derived classes should call the base class method before adding their own actions to
3899 perform at componentComplete.
3901 void QQuickItem::componentComplete()
3904 d->componentComplete = true;
3906 d->_stateGroup->componentComplete();
3908 d->_anchors->componentComplete();
3909 QQuickAnchorsPrivate::get(d->_anchors)->updateOnComplete();
3912 if (d->extra.isAllocated() && d->extra->layer)
3913 d->extra->layer->componentComplete();
3915 if (d->extra.isAllocated() && d->extra->keyHandler)
3916 d->extra->keyHandler->componentComplete();
3918 if (d->extra.isAllocated() && d->extra->contents)
3919 d->extra->contents->complete();
3921 if (d->window && d->dirtyAttributes) {
3922 d->addToDirtyList();
3923 QQuickWindowPrivate::get(d->window)->dirtyItem(this);
3927 QQuickStateGroup *QQuickItemPrivate::_states()
3931 _stateGroup = new QQuickStateGroup;
3932 if (!componentComplete)
3933 _stateGroup->classBegin();
3934 qmlobject_connect(_stateGroup, QQuickStateGroup, SIGNAL(stateChanged(QString)),
3935 q, QQuickItem, SIGNAL(stateChanged(QString)))
3941 QPointF QQuickItemPrivate::computeTransformOrigin() const
3945 case QQuickItem::TopLeft:
3946 return QPointF(0, 0);
3947 case QQuickItem::Top:
3948 return QPointF(width / 2., 0);
3949 case QQuickItem::TopRight:
3950 return QPointF(width, 0);
3951 case QQuickItem::Left:
3952 return QPointF(0, height / 2.);
3953 case QQuickItem::Center:
3954 return QPointF(width / 2., height / 2.);
3955 case QQuickItem::Right:
3956 return QPointF(width, height / 2.);
3957 case QQuickItem::BottomLeft:
3958 return QPointF(0, height);
3959 case QQuickItem::Bottom:
3960 return QPointF(width / 2., height);
3961 case QQuickItem::BottomRight:
3962 return QPointF(width, height);
3966 void QQuickItemPrivate::transformChanged()
3968 if (extra.isAllocated() && extra->layer)
3969 extra->layer->updateMatrix();
3972 void QQuickItemPrivate::deliverKeyEvent(QKeyEvent *e)
3976 Q_ASSERT(e->isAccepted());
3977 if (extra.isAllocated() && extra->keyHandler) {
3978 if (e->type() == QEvent::KeyPress)
3979 extra->keyHandler->keyPressed(e, false);
3981 extra->keyHandler->keyReleased(e, false);
3983 if (e->isAccepted())
3989 if (e->type() == QEvent::KeyPress)
3990 q->keyPressEvent(e);
3992 q->keyReleaseEvent(e);
3994 if (e->isAccepted())
3997 if (extra.isAllocated() && extra->keyHandler) {
4000 if (e->type() == QEvent::KeyPress)
4001 extra->keyHandler->keyPressed(e, true);
4003 extra->keyHandler->keyReleased(e, true);
4007 void QQuickItemPrivate::deliverInputMethodEvent(QInputMethodEvent *e)
4011 Q_ASSERT(e->isAccepted());
4012 if (extra.isAllocated() && extra->keyHandler) {
4013 extra->keyHandler->inputMethodEvent(e, false);
4015 if (e->isAccepted())
4021 q->inputMethodEvent(e);
4023 if (e->isAccepted())
4026 if (extra.isAllocated() && extra->keyHandler) {
4029 extra->keyHandler->inputMethodEvent(e, true);
4033 void QQuickItemPrivate::deliverFocusEvent(QFocusEvent *e)
4037 if (e->type() == QEvent::FocusIn) {
4040 q->focusOutEvent(e);
4044 void QQuickItemPrivate::deliverMouseEvent(QMouseEvent *e)
4048 Q_ASSERT(e->isAccepted());
4050 switch (e->type()) {
4052 Q_ASSERT(!"Unknown event type");
4053 case QEvent::MouseMove:
4054 q->mouseMoveEvent(e);
4056 case QEvent::MouseButtonPress:
4057 q->mousePressEvent(e);
4059 case QEvent::MouseButtonRelease:
4060 q->mouseReleaseEvent(e);
4062 case QEvent::MouseButtonDblClick:
4063 q->mouseDoubleClickEvent(e);
4068 void QQuickItemPrivate::deliverWheelEvent(QWheelEvent *e)
4074 void QQuickItemPrivate::deliverTouchEvent(QTouchEvent *e)
4080 void QQuickItemPrivate::deliverHoverEvent(QHoverEvent *e)
4083 switch (e->type()) {
4085 Q_ASSERT(!"Unknown event type");
4086 case QEvent::HoverEnter:
4087 q->hoverEnterEvent(e);
4089 case QEvent::HoverLeave:
4090 q->hoverLeaveEvent(e);
4092 case QEvent::HoverMove:
4093 q->hoverMoveEvent(e);
4098 #ifndef QT_NO_DRAGANDDROP
4099 void QQuickItemPrivate::deliverDragEvent(QEvent *e)
4102 switch (e->type()) {
4104 Q_ASSERT(!"Unknown event type");
4105 case QEvent::DragEnter:
4106 q->dragEnterEvent(static_cast<QDragEnterEvent *>(e));
4108 case QEvent::DragLeave:
4109 q->dragLeaveEvent(static_cast<QDragLeaveEvent *>(e));
4111 case QEvent::DragMove:
4112 q->dragMoveEvent(static_cast<QDragMoveEvent *>(e));
4115 q->dropEvent(static_cast<QDropEvent *>(e));
4119 #endif // QT_NO_DRAGANDDROP
4124 void QQuickItem::itemChange(ItemChange change, const ItemChangeData &value)
4131 Notify input method on updated query values if needed. \a indicates changed attributes.
4133 void QQuickItem::updateInputMethod(Qt::InputMethodQueries queries)
4135 if (hasActiveFocus())
4136 qApp->inputMethod()->update(queries);
4140 // XXX todo - do we want/need this anymore?
4141 QRectF QQuickItem::boundingRect() const
4143 Q_D(const QQuickItem);
4144 return QRectF(0, 0, d->width, d->height);
4148 QRectF QQuickItem::clipRect() const
4150 Q_D(const QQuickItem);
4151 return QRectF(0, 0, d->width, d->height);
4155 \qmlproperty enumeration QtQuick2::Item::transformOrigin
4156 This property holds the origin point around which scale and rotation transform.
4158 Nine transform origins are available, as shown in the image below.
4159 The default transform origin is \c Item.Center.
4161 \image declarative-transformorigin.png
4163 This example rotates an image around its bottom-right corner.
4166 source: "myimage.png"
4167 transformOrigin: Item.BottomRight
4172 To set an arbitrary transform origin point use the \l Scale or \l Rotation
4173 transform types with \l transform.
4176 \property QQuickItem::transformOrigin
4177 This property holds the origin point around which scale and rotation transform.
4179 Nine transform origins are available, as shown in the image below.
4180 The default transform origin is \c Item.Center.
4182 \image declarative-transformorigin.png
4184 QQuickItem::TransformOrigin QQuickItem::transformOrigin() const
4186 Q_D(const QQuickItem);
4190 void QQuickItem::setTransformOrigin(TransformOrigin origin)
4193 if (origin == d->origin())
4196 d->extra.value().origin = origin;
4197 d->dirty(QQuickItemPrivate::TransformOrigin);
4199 emit transformOriginChanged(d->origin());
4203 \property QQuickItem::transformOriginPoint
4209 QPointF QQuickItem::transformOriginPoint() const
4211 Q_D(const QQuickItem);
4212 if (d->extra.isAllocated() && !d->extra->userTransformOriginPoint.isNull())
4213 return d->extra->userTransformOriginPoint;
4214 return d->computeTransformOrigin();
4220 void QQuickItem::setTransformOriginPoint(const QPointF &point)
4223 if (d->extra.value().userTransformOriginPoint == point)
4226 d->extra->userTransformOriginPoint = point;
4227 d->dirty(QQuickItemPrivate::TransformOrigin);
4231 \qmlproperty real QtQuick2::Item::z
4233 Sets the stacking order of sibling items. By default the stacking order is 0.
4235 Items with a higher stacking value are drawn on top of siblings with a
4236 lower stacking order. Items with the same stacking value are drawn
4237 bottom up in the order they appear. Items with a negative stacking
4238 value are drawn under their parent's content.
4240 The following example shows the various effects of stacking order.
4244 \li \image declarative-item_stacking1.png
4245 \li Same \c z - later children above earlier children:
4250 width: 100; height: 100
4254 x: 50; y: 50; width: 100; height: 100
4259 \li \image declarative-item_stacking2.png
4260 \li Higher \c z on top:
4266 width: 100; height: 100
4270 x: 50; y: 50; width: 100; height: 100
4275 \li \image declarative-item_stacking3.png
4276 \li Same \c z - children above parents:
4281 width: 100; height: 100
4284 x: 50; y: 50; width: 100; height: 100
4290 \li \image declarative-item_stacking4.png
4291 \li Lower \c z below:
4296 width: 100; height: 100
4300 x: 50; y: 50; width: 100; height: 100
4308 \qmlproperty real QtQuick2::Item::z
4310 Sets the stacking order of sibling items. By default the stacking order is 0.
4312 Items with a higher stacking value are drawn on top of siblings with a
4313 lower stacking order. Items with the same stacking value are drawn
4314 bottom up in the order they appear. Items with a negative stacking
4315 value are drawn under their parent's content.
4317 The following example shows the various effects of stacking order.
4321 \li \image declarative-item_stacking1.png
4322 \li Same \c z - later children above earlier children:
4327 width: 100; height: 100
4331 x: 50; y: 50; width: 100; height: 100
4336 \li \image declarative-item_stacking2.png
4337 \li Higher \c z on top:
4343 width: 100; height: 100
4347 x: 50; y: 50; width: 100; height: 100
4352 \li \image declarative-item_stacking3.png
4353 \li Same \c z - children above parents:
4358 width: 100; height: 100
4361 x: 50; y: 50; width: 100; height: 100
4367 \li \image declarative-item_stacking4.png
4368 \li Lower \c z below:
4373 width: 100; height: 100
4377 x: 50; y: 50; width: 100; height: 100
4384 qreal QQuickItem::z() const
4386 Q_D(const QQuickItem);
4390 void QQuickItem::setZ(qreal v)
4396 d->extra.value().z = v;
4398 d->dirty(QQuickItemPrivate::ZValue);
4399 if (d->parentItem) {
4400 QQuickItemPrivate::get(d->parentItem)->dirty(QQuickItemPrivate::ChildrenStackingChanged);
4401 QQuickItemPrivate::get(d->parentItem)->markSortedChildrenDirty(this);
4406 if (d->extra.isAllocated() && d->extra->layer)
4407 d->extra->layer->updateZ();
4411 \qmlproperty real QtQuick2::Item::rotation
4412 This property holds the rotation of the item in degrees clockwise around
4413 its transformOrigin.
4415 The default value is 0 degrees (that is, no rotation).
4419 \li \image declarative-rotation.png
4424 width: 100; height: 100
4427 x: 25; y: 25; width: 50; height: 50
4434 \sa transform, Rotation
4437 \property QQuickItem::rotation
4438 This property holds the rotation of the item in degrees clockwise around
4439 its transformOrigin.
4441 The default value is 0 degrees (that is, no rotation).
4445 \li \image declarative-rotation.png
4450 width: 100; height: 100
4453 x: 25; y: 25; width: 50; height: 50
4460 \sa transform, Rotation
4462 qreal QQuickItem::rotation() const
4464 Q_D(const QQuickItem);
4465 return d->rotation();
4468 void QQuickItem::setRotation(qreal r)
4471 if (d->rotation() == r)
4474 d->extra.value().rotation = r;
4476 d->dirty(QQuickItemPrivate::BasicTransform);
4478 d->itemChange(ItemRotationHasChanged, r);
4480 emit rotationChanged();
4484 \qmlproperty real QtQuick2::Item::scale
4485 This property holds the scale factor for this item.
4487 A scale of less than 1.0 causes the item to be rendered at a smaller
4488 size, and a scale greater than 1.0 renders the item at a larger size.
4489 A negative scale causes the item to be mirrored when rendered.
4491 The default value is 1.0.
4493 Scaling is applied from the transformOrigin.
4497 \li \image declarative-scale.png
4504 width: 100; height: 100
4508 width: 25; height: 25
4513 x: 25; y: 25; width: 50; height: 50
4520 \sa transform, Scale
4523 \property QQuickItem::scale
4524 This property holds the scale factor for this item.
4526 A scale of less than 1.0 causes the item to be rendered at a smaller
4527 size, and a scale greater than 1.0 renders the item at a larger size.
4528 A negative scale causes the item to be mirrored when rendered.
4530 The default value is 1.0.
4532 Scaling is applied from the transformOrigin.
4536 \li \image declarative-scale.png
4543 width: 100; height: 100
4547 width: 25; height: 25
4552 x: 25; y: 25; width: 50; height: 50
4559 \sa transform, Scale
4561 qreal QQuickItem::scale() const
4563 Q_D(const QQuickItem);
4567 void QQuickItem::setScale(qreal s)
4570 if (d->scale() == s)
4573 d->extra.value().scale = s;
4575 d->dirty(QQuickItemPrivate::BasicTransform);
4577 emit scaleChanged();
4581 \qmlproperty real QtQuick2::Item::opacity
4583 This property holds the opacity of the item. Opacity is specified as a
4584 number between 0.0 (fully transparent) and 1.0 (fully opaque). The default
4587 When this property is set, the specified opacity is also applied
4588 individually to child items. This may have an unintended effect in some
4589 circumstances. For example in the second set of rectangles below, the red
4590 rectangle has specified an opacity of 0.5, which affects the opacity of
4591 its blue child rectangle even though the child has not specified an opacity.
4595 \li \image declarative-item_opacity1.png
4601 width: 100; height: 100
4604 x: 50; y: 50; width: 100; height: 100
4610 \li \image declarative-item_opacity2.png
4617 width: 100; height: 100
4620 x: 50; y: 50; width: 100; height: 100
4627 Changing an item's opacity does not affect whether the item receives user
4628 input events. (In contrast, setting \l visible property to \c false stops
4629 mouse events, and setting the \l enabled property to \c false stops mouse
4630 and keyboard events, and also removes active focus from the item.)
4635 \property QQuickItem::opacity
4637 This property holds the opacity of the item. Opacity is specified as a
4638 number between 0.0 (fully transparent) and 1.0 (fully opaque). The default
4641 When this property is set, the specified opacity is also applied
4642 individually to child items. This may have an unintended effect in some
4643 circumstances. For example in the second set of rectangles below, the red
4644 rectangle has specified an opacity of 0.5, which affects the opacity of
4645 its blue child rectangle even though the child has not specified an opacity.
4649 \li \image declarative-item_opacity1.png
4655 width: 100; height: 100
4658 x: 50; y: 50; width: 100; height: 100
4664 \li \image declarative-item_opacity2.png
4671 width: 100; height: 100
4674 x: 50; y: 50; width: 100; height: 100
4681 Changing an item's opacity does not affect whether the item receives user
4682 input events. (In contrast, setting \l visible property to \c false stops
4683 mouse events, and setting the \l enabled property to \c false stops mouse
4684 and keyboard events, and also removes active focus from the item.)
4688 qreal QQuickItem::opacity() const
4690 Q_D(const QQuickItem);
4691 return d->opacity();
4694 void QQuickItem::setOpacity(qreal o)
4697 if (d->opacity() == o)
4700 d->extra.value().opacity = o;
4702 d->dirty(QQuickItemPrivate::OpacityValue);
4704 d->itemChange(ItemOpacityHasChanged, o);
4706 emit opacityChanged();
4710 \qmlproperty bool QtQuick2::Item::visible
4712 This property holds whether the item is visible. By default this is true.
4714 Setting this property directly affects the \c visible value of child
4715 items. When set to \c false, the \c visible values of all child items also
4716 become \c false. When set to \c true, the \c visible values of child items
4717 are returned to \c true, unless they have explicitly been set to \c false.
4719 (Because of this flow-on behavior, using the \c visible property may not
4720 have the intended effect if a property binding should only respond to
4721 explicit property changes. In such cases it may be better to use the
4722 \l opacity property instead.)
4724 If this property is set to \c false, the item will no longer receive mouse
4725 events, but will continue to receive key events and will retain the keyboard
4726 \l focus if it has been set. (In contrast, setting the \l enabled property
4727 to \c false stops both mouse and keyboard events, and also removes focus
4730 \note This property's value is only affected by changes to this property or
4731 the parent's \c visible property. It does not change, for example, if this
4732 item moves off-screen, or if the \l opacity changes to 0.
4734 \sa opacity, enabled
4737 \property QQuickItem::visible
4739 This property holds whether the item is visible. By default this is true.
4741 Setting this property directly affects the \c visible value of child
4742 items. When set to \c false, the \c visible values of all child items also
4743 become \c false. When set to \c true, the \c visible values of child items
4744 are returned to \c true, unless they have explicitly been set to \c false.
4746 (Because of this flow-on behavior, using the \c visible property may not
4747 have the intended effect if a property binding should only respond to
4748 explicit property changes. In such cases it may be better to use the
4749 \l opacity property instead.)
4751 If this property is set to \c false, the item will no longer receive mouse
4752 events, but will continue to receive key events and will retain the keyboard
4753 \l focus if it has been set. (In contrast, setting the \l enabled property
4754 to \c false stops both mouse and keyboard events, and also removes focus
4757 \note This property's value is only affected by changes to this property or
4758 the parent's \c visible property. It does not change, for example, if this
4759 item moves off-screen, or if the \l opacity changes to 0.
4761 \sa opacity, enabled
4763 bool QQuickItem::isVisible() const
4765 Q_D(const QQuickItem);
4766 return d->effectiveVisible;
4769 void QQuickItem::setVisible(bool v)
4772 if (v == d->explicitVisible)
4775 d->explicitVisible = v;
4777 d->dirty(QQuickItemPrivate::Visible);
4779 const bool childVisibilityChanged = d->setEffectiveVisibleRecur(d->calcEffectiveVisible());
4780 if (childVisibilityChanged && d->parentItem)
4781 emit d->parentItem->visibleChildrenChanged(); // signal the parent, not this!
4785 \qmlproperty bool QtQuick2::Item::enabled
4787 This property holds whether the item receives mouse and keyboard events.
4788 By default this is true.
4790 Setting this property directly affects the \c enabled value of child
4791 items. When set to \c false, the \c enabled values of all child items also
4792 become \c false. When set to \c true, the \c enabled values of child items
4793 are returned to \c true, unless they have explicitly been set to \c false.
4795 Setting this property to \c false automatically causes \l activeFocus to be
4796 set to \c false, and this item will longer receive keyboard events.
4801 \property QQuickItem::enabled
4803 This property holds whether the item receives mouse and keyboard events.
4804 By default this is true.
4806 Setting this property directly affects the \c enabled value of child
4807 items. When set to \c false, the \c enabled values of all child items also
4808 become \c false. When set to \c true, the \c enabled values of child items
4809 are returned to \c true, unless they have explicitly been set to \c false.
4811 Setting this property to \c false automatically causes \l activeFocus to be
4812 set to \c false, and this item will longer receive keyboard events.
4816 bool QQuickItem::isEnabled() const
4818 Q_D(const QQuickItem);
4819 return d->effectiveEnable;
4822 void QQuickItem::setEnabled(bool e)
4825 if (e == d->explicitEnable)
4828 d->explicitEnable = e;
4830 QQuickItem *scope = parentItem();
4831 while (scope && !scope->isFocusScope())
4832 scope = scope->parentItem();
4834 d->setEffectiveEnableRecur(scope, d->calcEffectiveEnable());
4837 bool QQuickItemPrivate::calcEffectiveVisible() const
4839 // XXX todo - Should the effective visible of an element with no parent just be the current
4840 // effective visible? This would prevent pointless re-processing in the case of an element
4841 // moving to/from a no-parent situation, but it is different from what graphics view does.
4842 return explicitVisible && (!parentItem || QQuickItemPrivate::get(parentItem)->effectiveVisible);
4845 bool QQuickItemPrivate::setEffectiveVisibleRecur(bool newEffectiveVisible)
4849 if (newEffectiveVisible && !explicitVisible) {
4850 // This item locally overrides visibility
4851 return false; // effective visibility didn't change
4854 if (newEffectiveVisible == effectiveVisible) {
4855 // No change necessary
4856 return false; // effective visibility didn't change
4859 effectiveVisible = newEffectiveVisible;
4861 if (parentItem) QQuickItemPrivate::get(parentItem)->dirty(ChildrenStackingChanged);
4864 QQuickWindowPrivate *windowPriv = QQuickWindowPrivate::get(window);
4865 if (windowPriv->mouseGrabberItem == q)
4869 bool childVisibilityChanged = false;
4870 for (int ii = 0; ii < childItems.count(); ++ii)
4871 childVisibilityChanged |= QQuickItemPrivate::get(childItems.at(ii))->setEffectiveVisibleRecur(newEffectiveVisible);
4873 itemChange(QQuickItem::ItemVisibleHasChanged, effectiveVisible);
4874 #ifndef QT_NO_ACCESSIBILITY
4876 QAccessibleEvent ev(q, effectiveVisible ? QAccessible::ObjectShow : QAccessible::ObjectHide);
4877 QAccessible::updateAccessibility(&ev);
4880 emit q->visibleChanged();
4881 if (childVisibilityChanged)
4882 emit q->visibleChildrenChanged();
4884 return true; // effective visibility DID change
4887 bool QQuickItemPrivate::calcEffectiveEnable() const
4889 // XXX todo - Should the effective enable of an element with no parent just be the current
4890 // effective enable? This would prevent pointless re-processing in the case of an element
4891 // moving to/from a no-parent situation, but it is different from what graphics view does.
4892 return explicitEnable && (!parentItem || QQuickItemPrivate::get(parentItem)->effectiveEnable);
4895 void QQuickItemPrivate::setEffectiveEnableRecur(QQuickItem *scope, bool newEffectiveEnable)
4899 if (newEffectiveEnable && !explicitEnable) {
4900 // This item locally overrides enable
4904 if (newEffectiveEnable == effectiveEnable) {
4905 // No change necessary
4909 effectiveEnable = newEffectiveEnable;
4912 QQuickWindowPrivate *windowPriv = QQuickWindowPrivate::get(window);
4913 if (windowPriv->mouseGrabberItem == q)
4915 if (scope && !effectiveEnable && activeFocus) {
4916 windowPriv->clearFocusInScope(
4917 scope, q, QQuickWindowPrivate::DontChangeFocusProperty | QQuickWindowPrivate::DontChangeSubFocusItem);
4921 for (int ii = 0; ii < childItems.count(); ++ii) {
4922 QQuickItemPrivate::get(childItems.at(ii))->setEffectiveEnableRecur(
4923 (flags & QQuickItem::ItemIsFocusScope) && scope ? q : scope, newEffectiveEnable);
4926 if (window && scope && effectiveEnable && focus) {
4927 QQuickWindowPrivate::get(window)->setFocusInScope(
4928 scope, q, QQuickWindowPrivate::DontChangeFocusProperty | QQuickWindowPrivate::DontChangeSubFocusItem);
4931 emit q->enabledChanged();
4934 QString QQuickItemPrivate::dirtyToString() const
4936 #define DIRTY_TO_STRING(value) if (dirtyAttributes & value) { \
4937 if (!rv.isEmpty()) \
4938 rv.append(QLatin1String("|")); \
4939 rv.append(QLatin1String(#value)); \
4942 // QString rv = QLatin1String("0x") + QString::number(dirtyAttributes, 16);
4945 DIRTY_TO_STRING(TransformOrigin);
4946 DIRTY_TO_STRING(Transform);
4947 DIRTY_TO_STRING(BasicTransform);
4948 DIRTY_TO_STRING(Position);
4949 DIRTY_TO_STRING(Size);
4950 DIRTY_TO_STRING(ZValue);
4951 DIRTY_TO_STRING(Content);
4952 DIRTY_TO_STRING(Smooth);
4953 DIRTY_TO_STRING(OpacityValue);
4954 DIRTY_TO_STRING(ChildrenChanged);
4955 DIRTY_TO_STRING(ChildrenStackingChanged);
4956 DIRTY_TO_STRING(ParentChanged);
4957 DIRTY_TO_STRING(Clip);
4958 DIRTY_TO_STRING(Window);
4959 DIRTY_TO_STRING(EffectReference);
4960 DIRTY_TO_STRING(Visible);
4961 DIRTY_TO_STRING(HideReference);
4962 DIRTY_TO_STRING(Antialiasing);
4967 void QQuickItemPrivate::dirty(DirtyType type)
4970 if (type & (TransformOrigin | Transform | BasicTransform | Position | Size))
4973 if (!(dirtyAttributes & type) || (window && !prevDirtyItem)) {
4974 dirtyAttributes |= type;
4975 if (window && componentComplete) {
4977 QQuickWindowPrivate::get(window)->dirtyItem(q);
4982 void QQuickItemPrivate::addToDirtyList()
4987 if (!prevDirtyItem) {
4988 Q_ASSERT(!nextDirtyItem);
4990 QQuickWindowPrivate *p = QQuickWindowPrivate::get(window);
4991 nextDirtyItem = p->dirtyItemList;
4992 if (nextDirtyItem) QQuickItemPrivate::get(nextDirtyItem)->prevDirtyItem = &nextDirtyItem;
4993 prevDirtyItem = &p->dirtyItemList;
4994 p->dirtyItemList = q;
4997 Q_ASSERT(prevDirtyItem);
5000 void QQuickItemPrivate::removeFromDirtyList()
5002 if (prevDirtyItem) {
5003 if (nextDirtyItem) QQuickItemPrivate::get(nextDirtyItem)->prevDirtyItem = prevDirtyItem;
5004 *prevDirtyItem = nextDirtyItem;
5008 Q_ASSERT(!prevDirtyItem);
5009 Q_ASSERT(!nextDirtyItem);
5012 void QQuickItemPrivate::refFromEffectItem(bool hide)
5014 ++extra.value().effectRefCount;
5015 if (1 == extra->effectRefCount) {
5016 dirty(EffectReference);
5017 if (parentItem) QQuickItemPrivate::get(parentItem)->dirty(ChildrenStackingChanged);
5020 if (++extra->hideRefCount == 1)
5021 dirty(HideReference);
5025 void QQuickItemPrivate::derefFromEffectItem(bool unhide)
5027 Q_ASSERT(extra->effectRefCount);
5028 --extra->effectRefCount;
5029 if (0 == extra->effectRefCount) {
5030 dirty(EffectReference);
5031 if (parentItem) QQuickItemPrivate::get(parentItem)->dirty(ChildrenStackingChanged);
5034 if (--extra->hideRefCount == 0)
5035 dirty(HideReference);
5039 void QQuickItemPrivate::setCulled(bool cull)
5045 if ((cull && ++extra.value().hideRefCount == 1) || (!cull && --extra.value().hideRefCount == 0))
5046 dirty(HideReference);
5049 void QQuickItemPrivate::itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &data)
5053 case QQuickItem::ItemChildAddedChange:
5054 q->itemChange(change, data);
5055 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5056 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5057 if (change.types & QQuickItemPrivate::Children) {
5058 change.listener->itemChildAdded(q, data.item);
5062 case QQuickItem::ItemChildRemovedChange:
5063 q->itemChange(change, data);
5064 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5065 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5066 if (change.types & QQuickItemPrivate::Children) {
5067 change.listener->itemChildRemoved(q, data.item);
5071 case QQuickItem::ItemSceneChange:
5072 q->itemChange(change, data);
5074 case QQuickItem::ItemVisibleHasChanged:
5075 q->itemChange(change, data);
5076 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5077 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5078 if (change.types & QQuickItemPrivate::Visibility) {
5079 change.listener->itemVisibilityChanged(q);
5083 case QQuickItem::ItemParentHasChanged:
5084 q->itemChange(change, data);
5085 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5086 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5087 if (change.types & QQuickItemPrivate::Parent) {
5088 change.listener->itemParentChanged(q, data.item);
5092 case QQuickItem::ItemOpacityHasChanged:
5093 q->itemChange(change, data);
5094 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5095 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5096 if (change.types & QQuickItemPrivate::Opacity) {
5097 change.listener->itemOpacityChanged(q);
5101 case QQuickItem::ItemActiveFocusHasChanged:
5102 q->itemChange(change, data);
5104 case QQuickItem::ItemRotationHasChanged:
5105 q->itemChange(change, data);
5106 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5107 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5108 if (change.types & QQuickItemPrivate::Rotation) {
5109 change.listener->itemRotationChanged(q);
5117 \qmlproperty bool QtQuick2::Item::smooth
5119 Primarily used in image based items to decide if the item should use smooth
5120 sampling or not. Smooth sampling is performed using linear interpolation, while
5121 non-smooth is performed using nearest neighbor.
5123 In Qt Quick 2.0, this property has minimal impact on performance.
5128 \property QQuickItem::smooth
5129 \brief Specifies whether the item is smoothed or not
5131 Primarily used in image based items to decide if the item should use smooth
5132 sampling or not. Smooth sampling is performed using linear interpolation, while
5133 non-smooth is performed using nearest neighbor.
5135 In Qt Quick 2.0, this property has minimal impact on performance.
5139 bool QQuickItem::smooth() const
5141 Q_D(const QQuickItem);
5144 void QQuickItem::setSmooth(bool smooth)
5147 if (d->smooth == smooth)
5151 d->dirty(QQuickItemPrivate::Smooth);
5153 emit smoothChanged(smooth);
5157 \qmlproperty bool QtQuick2::Item::antialiasing
5159 Primarily used in Rectangle and image based elements to decide if the item should
5160 use antialiasing or not. Items with antialiasing enabled require more memory and
5161 are potentially slower to render.
5163 The default is false.
5166 \property QQuickItem::antialiasing
5167 \brief Specifies whether the item is antialiased or not
5169 Primarily used in Rectangle and image based elements to decide if the item should
5170 use antialiasing or not. Items with antialiasing enabled require more memory and
5171 are potentially slower to render.
5173 The default is false.
5175 bool QQuickItem::antialiasing() const
5177 Q_D(const QQuickItem);
5178 return d->antialiasing;
5180 void QQuickItem::setAntialiasing(bool antialiasing)
5183 if (d->antialiasing == antialiasing)
5186 d->antialiasing = antialiasing;
5187 d->dirty(QQuickItemPrivate::Antialiasing);
5189 emit antialiasingChanged(antialiasing);
5193 Returns the item flags for this item.
5197 QQuickItem::Flags QQuickItem::flags() const
5199 Q_D(const QQuickItem);
5200 return (QQuickItem::Flags)d->flags;
5204 Enables the specified \a flag for this item if \a enabled is true;
5205 if \a enabled is false, the flag is disabled.
5207 These provide various hints for the item; for example, the
5208 ItemClipsChildrenToShape flag indicates that all children of this
5209 item should be clipped to fit within the item area.
5211 void QQuickItem::setFlag(Flag flag, bool enabled)
5215 setFlags((Flags)(d->flags | (quint32)flag));
5217 setFlags((Flags)(d->flags & ~(quint32)flag));
5221 Enables the specified \a flags for this item.
5225 void QQuickItem::setFlags(Flags flags)
5229 if ((flags & ItemIsFocusScope) != (d->flags & ItemIsFocusScope)) {
5230 if (flags & ItemIsFocusScope && !d->childItems.isEmpty() && d->window) {
5231 qWarning("QQuickItem: Cannot set FocusScope once item has children and is in a window.");
5232 flags &= ~ItemIsFocusScope;
5233 } else if (d->flags & ItemIsFocusScope) {
5234 qWarning("QQuickItem: Cannot unset FocusScope flag.");
5235 flags |= ItemIsFocusScope;
5239 if ((flags & ItemClipsChildrenToShape ) != (d->flags & ItemClipsChildrenToShape))
5240 d->dirty(QQuickItemPrivate::Clip);
5246 \qmlproperty real QtQuick2::Item::x
5247 \qmlproperty real QtQuick2::Item::y
5248 \qmlproperty real QtQuick2::Item::width
5249 \qmlproperty real QtQuick2::Item::height
5251 Defines the item's position and size.
5253 The (x,y) position is relative to the \l parent.
5256 Item { x: 100; y: 100; width: 100; height: 100 }
5260 \property QQuickItem::x
5262 Defines the item's x position relative to its parent.
5265 \property QQuickItem::y
5267 Defines the item's y position relative to its parent.
5269 qreal QQuickItem::x() const
5271 Q_D(const QQuickItem);
5275 qreal QQuickItem::y() const
5277 Q_D(const QQuickItem);
5282 \property QQuickItem::pos
5288 QPointF QQuickItem::pos() const
5290 Q_D(const QQuickItem);
5291 return QPointF(d->x, d->y);
5294 void QQuickItem::setX(qreal v)
5303 d->dirty(QQuickItemPrivate::Position);
5305 geometryChanged(QRectF(x(), y(), width(), height()),
5306 QRectF(oldx, y(), width(), height()));
5309 void QQuickItem::setY(qreal v)
5318 d->dirty(QQuickItemPrivate::Position);
5320 geometryChanged(QRectF(x(), y(), width(), height()),
5321 QRectF(x(), oldy, width(), height()));
5327 void QQuickItem::setPos(const QPointF &pos)
5330 if (QPointF(d->x, d->y) == pos)
5339 d->dirty(QQuickItemPrivate::Position);
5341 geometryChanged(QRectF(x(), y(), width(), height()),
5342 QRectF(oldx, oldy, width(), height()));
5346 \property QQuickItem::width
5348 This property holds the width of this item.
5350 qreal QQuickItem::width() const
5352 Q_D(const QQuickItem);
5356 void QQuickItem::setWidth(qreal w)
5362 d->widthValid = true;
5366 qreal oldWidth = d->width;
5369 d->dirty(QQuickItemPrivate::Size);
5371 geometryChanged(QRectF(x(), y(), width(), height()),
5372 QRectF(x(), y(), oldWidth, height()));
5375 void QQuickItem::resetWidth()
5378 d->widthValid = false;
5379 setImplicitWidth(implicitWidth());
5382 void QQuickItemPrivate::implicitWidthChanged()
5385 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5386 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5387 if (change.types & QQuickItemPrivate::ImplicitWidth) {
5388 change.listener->itemImplicitWidthChanged(q);
5391 emit q->implicitWidthChanged();
5394 qreal QQuickItemPrivate::getImplicitWidth() const
5396 return implicitWidth;
5399 Returns the width of the item that is implied by other properties that determine the content.
5401 qreal QQuickItem::implicitWidth() const
5403 Q_D(const QQuickItem);
5404 return d->getImplicitWidth();
5408 \qmlproperty real QtQuick2::Item::implicitWidth
5409 \qmlproperty real QtQuick2::Item::implicitHeight
5411 Defines the natural width or height of the Item if no \l width or \l height is specified.
5413 The default implicit size for most items is 0x0, however some items have an inherent
5414 implicit size which cannot be overridden, e.g. Image, Text.
5416 Setting the implicit size is useful for defining components that have a preferred size
5417 based on their content, for example:
5424 property alias icon: image.source
5425 property alias label: text.text
5426 implicitWidth: text.implicitWidth + image.implicitWidth
5427 implicitHeight: Math.max(text.implicitHeight, image.implicitHeight)
5432 anchors.left: image.right; anchors.right: parent.right
5433 anchors.verticalCenter: parent.verticalCenter
5438 \b Note: using implicitWidth of Text or TextEdit and setting the width explicitly
5439 incurs a performance penalty as the text must be laid out twice.
5442 \property QQuickItem::implicitWidth
5443 \property QQuickItem::implicitHeight
5445 Defines the natural width or height of the Item if no \l width or \l height is specified.
5447 The default implicit size for most items is 0x0, however some items have an inherent
5448 implicit size which cannot be overridden, e.g. Image, Text.
5450 Setting the implicit size is useful for defining components that have a preferred size
5451 based on their content, for example:
5458 property alias icon: image.source
5459 property alias label: text.text
5460 implicitWidth: text.implicitWidth + image.implicitWidth
5461 implicitHeight: Math.max(text.implicitHeight, image.implicitHeight)
5466 anchors.left: image.right; anchors.right: parent.right
5467 anchors.verticalCenter: parent.verticalCenter
5472 \b Note: using implicitWidth of Text or TextEdit and setting the width explicitly
5473 incurs a performance penalty as the text must be laid out twice.
5475 void QQuickItem::setImplicitWidth(qreal w)
5478 bool changed = w != d->implicitWidth;
5479 d->implicitWidth = w;
5480 if (d->width == w || widthValid()) {
5482 d->implicitWidthChanged();
5483 if (d->width == w || widthValid())
5488 qreal oldWidth = d->width;
5491 d->dirty(QQuickItemPrivate::Size);
5493 geometryChanged(QRectF(x(), y(), width(), height()),
5494 QRectF(x(), y(), oldWidth, height()));
5497 d->implicitWidthChanged();
5501 Returns whether the width property has been set explicitly.
5503 bool QQuickItem::widthValid() const
5505 Q_D(const QQuickItem);
5506 return d->widthValid;
5510 \property QQuickItem::height
5512 This property holds the height of this item.
5514 qreal QQuickItem::height() const
5516 Q_D(const QQuickItem);
5520 void QQuickItem::setHeight(qreal h)
5526 d->heightValid = true;
5530 qreal oldHeight = d->height;
5533 d->dirty(QQuickItemPrivate::Size);
5535 geometryChanged(QRectF(x(), y(), width(), height()),
5536 QRectF(x(), y(), width(), oldHeight));
5539 void QQuickItem::resetHeight()
5542 d->heightValid = false;
5543 setImplicitHeight(implicitHeight());
5546 void QQuickItemPrivate::implicitHeightChanged()
5549 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5550 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5551 if (change.types & QQuickItemPrivate::ImplicitHeight) {
5552 change.listener->itemImplicitHeightChanged(q);
5555 emit q->implicitHeightChanged();
5558 qreal QQuickItemPrivate::getImplicitHeight() const
5560 return implicitHeight;
5563 qreal QQuickItem::implicitHeight() const
5565 Q_D(const QQuickItem);
5566 return d->getImplicitHeight();
5569 void QQuickItem::setImplicitHeight(qreal h)
5572 bool changed = h != d->implicitHeight;
5573 d->implicitHeight = h;
5574 if (d->height == h || heightValid()) {
5576 d->implicitHeightChanged();
5577 if (d->height == h || heightValid())
5582 qreal oldHeight = d->height;
5585 d->dirty(QQuickItemPrivate::Size);
5587 geometryChanged(QRectF(x(), y(), width(), height()),
5588 QRectF(x(), y(), width(), oldHeight));
5591 d->implicitHeightChanged();
5597 void QQuickItem::setImplicitSize(qreal w, qreal h)
5600 bool wChanged = w != d->implicitWidth;
5601 bool hChanged = h != d->implicitHeight;
5603 d->implicitWidth = w;
5604 d->implicitHeight = h;
5608 if (d->width == w || widthValid()) {
5610 d->implicitWidthChanged();
5611 wDone = d->width == w || widthValid();
5614 if (d->height == h || heightValid()) {
5616 d->implicitHeightChanged();
5617 hDone = d->height == h || heightValid();
5623 qreal oldWidth = d->width;
5624 qreal oldHeight = d->height;
5630 d->dirty(QQuickItemPrivate::Size);
5632 geometryChanged(QRectF(x(), y(), width(), height()),
5633 QRectF(x(), y(), oldWidth, oldHeight));
5635 if (!wDone && wChanged)
5636 d->implicitWidthChanged();
5637 if (!hDone && hChanged)
5638 d->implicitHeightChanged();
5642 Returns whether the height property has been set explicitly.
5644 bool QQuickItem::heightValid() const
5646 Q_D(const QQuickItem);
5647 return d->heightValid;
5653 void QQuickItem::setSize(const QSizeF &size)
5656 d->heightValid = true;
5657 d->widthValid = true;
5659 if (QSizeF(d->width, d->height) == size)
5662 qreal oldHeight = d->height;
5663 qreal oldWidth = d->width;
5664 d->height = size.height();
5665 d->width = size.width();
5667 d->dirty(QQuickItemPrivate::Size);
5669 geometryChanged(QRectF(x(), y(), width(), height()),
5670 QRectF(x(), y(), oldWidth, oldHeight));
5674 \qmlproperty bool QtQuick2::Item::activeFocus
5676 This read-only property indicates whether the item has active focus.
5678 If activeFocus is true, either this item is the one that currently
5679 receives keyboard input, or it is a FocusScope ancestor of the item
5680 that currently receives keyboard input.
5682 Usually, activeFocus is gained by setting \l focus on an item and its
5683 enclosing FocusScope objects. In the following example, the \c input
5684 and \c focusScope objects will have active focus, while the root
5685 rectangle object will not.
5691 width: 100; height: 100
5705 \sa focus, {Keyboard Focus in Qt Quick}
5708 \property QQuickItem::activeFocus
5710 This read-only property indicates whether the item has active focus.
5712 If activeFocus is true, either this item is the one that currently
5713 receives keyboard input, or it is a FocusScope ancestor of the item
5714 that currently receives keyboard input.
5716 Usually, activeFocus is gained by setting \l focus on an item and its
5717 enclosing FocusScope objects. In the following example, the \c input
5718 and \c focusScope objects will have active focus, while the root
5719 rectangle object will not.
5725 width: 100; height: 100
5738 \sa focus, {Keyboard Focus in Qt Quick}
5740 bool QQuickItem::hasActiveFocus() const
5742 Q_D(const QQuickItem);
5743 return d->activeFocus;
5747 \qmlproperty bool QtQuick2::Item::focus
5749 This property holds whether the item has focus within the enclosing
5750 FocusScope. If true, this item will gain active focus when the
5751 enclosing FocusScope gains active focus.
5753 In the following example, \c input will be given active focus when
5754 \c scope gains active focus:
5760 width: 100; height: 100
5773 For the purposes of this property, the scene as a whole is assumed
5774 to act like a focus scope. On a practical level, that means the
5775 following QML will give active focus to \c input on startup.
5779 width: 100; height: 100
5788 \sa activeFocus, {Keyboard Focus in Qt Quick}
5791 \property QQuickItem::focus
5793 This property holds whether the item has focus within the enclosing
5794 FocusScope. If true, this item will gain active focus when the
5795 enclosing FocusScope gains active focus.
5797 In the following example, \c input will be given active focus when
5798 \c scope gains active focus:
5804 width: 100; height: 100
5817 For the purposes of this property, the scene as a whole is assumed
5818 to act like a focus scope. On a practical level, that means the
5819 following QML will give active focus to \c input on startup.
5823 width: 100; height: 100
5832 \sa activeFocus, {Keyboard Focus in Qt Quick}
5834 bool QQuickItem::hasFocus() const
5836 Q_D(const QQuickItem);
5840 void QQuickItem::setFocus(bool focus)
5843 if (d->focus == focus)
5846 if (d->window || d->parentItem) {
5847 // Need to find our nearest focus scope
5848 QQuickItem *scope = parentItem();
5849 while (scope && !scope->isFocusScope() && scope->parentItem())
5850 scope = scope->parentItem();
5853 QQuickWindowPrivate::get(d->window)->setFocusInScope(scope, this);
5855 QQuickWindowPrivate::get(d->window)->clearFocusInScope(scope, this);
5857 // do the focus changes from setFocusInScope/clearFocusInScope that are
5858 // unrelated to a window
5859 QVarLengthArray<QQuickItem *, 20> changed;
5860 QQuickItem *oldSubFocusItem = QQuickItemPrivate::get(scope)->subFocusItem;
5861 if (oldSubFocusItem) {
5862 QQuickItemPrivate::get(oldSubFocusItem)->updateSubFocusItem(scope, false);
5863 QQuickItemPrivate::get(oldSubFocusItem)->focus = false;
5864 changed << oldSubFocusItem;
5865 } else if (!scope->isFocusScope() && scope->hasFocus()) {
5866 QQuickItemPrivate::get(scope)->focus = false;
5869 d->updateSubFocusItem(scope, focus);
5873 emit focusChanged(focus);
5875 QQuickWindowPrivate::notifyFocusChangesRecur(changed.data(), changed.count() - 1);
5878 QVarLengthArray<QQuickItem *, 20> changed;
5879 QQuickItem *oldSubFocusItem = d->subFocusItem;
5880 if (!isFocusScope() && oldSubFocusItem) {
5881 QQuickItemPrivate::get(oldSubFocusItem)->updateSubFocusItem(this, false);
5882 QQuickItemPrivate::get(oldSubFocusItem)->focus = false;
5883 changed << oldSubFocusItem;
5888 emit focusChanged(focus);
5890 QQuickWindowPrivate::notifyFocusChangesRecur(changed.data(), changed.count() - 1);
5895 Returns true if this item is a focus scope, and false otherwise.
5897 bool QQuickItem::isFocusScope() const
5899 return flags() & ItemIsFocusScope;
5903 If this item is a focus scope, this returns the item in its focus chain
5904 that currently has focus.
5906 Returns 0 if this item is not a focus scope.
5908 QQuickItem *QQuickItem::scopedFocusItem() const
5910 Q_D(const QQuickItem);
5911 if (!isFocusScope())
5914 return d->subFocusItem;
5918 Returns the mouse buttons accepted by this item.
5920 The default value is Qt::NoButton; that is, no mouse buttons are accepted.
5922 If an item does not accept the mouse button for a particular mouse event,
5923 the mouse event will not be delivered to the item and will be delivered
5924 to the next item in the item hierarchy instead.
5926 Qt::MouseButtons QQuickItem::acceptedMouseButtons() const
5928 Q_D(const QQuickItem);
5929 return d->acceptedMouseButtons();
5933 Sets the mouse buttons accepted by this item to \a buttons.
5935 void QQuickItem::setAcceptedMouseButtons(Qt::MouseButtons buttons)
5938 if (buttons & Qt::LeftButton)
5941 d->extra.clearFlag();
5943 buttons &= ~Qt::LeftButton;
5944 if (buttons || d->extra.isAllocated())
5945 d->extra.value().acceptedMouseButtons = buttons;
5949 Returns whether mouse events of this item's children should be filtered
5952 \sa setFiltersChildMouseEvents(), childMouseEventFilter()
5954 bool QQuickItem::filtersChildMouseEvents() const
5956 Q_D(const QQuickItem);
5957 return d->filtersChildMouseEvents;
5961 Sets whether mouse events of this item's children should be filtered
5964 If \a filter is true, childMouseEventFilter() will be called when
5965 a mouse event is triggered for a child item.
5967 \sa filtersChildMouseEvents()
5969 void QQuickItem::setFiltersChildMouseEvents(bool filter)
5972 d->filtersChildMouseEvents = filter;
5978 bool QQuickItem::isUnderMouse() const
5980 Q_D(const QQuickItem);
5984 QPointF cursorPos = QGuiApplicationPrivate::lastCursorPosition;
5985 return contains(mapFromScene(d->window->mapFromGlobal(cursorPos.toPoint())));
5989 Returns whether hover events are accepted by this item.
5991 The default value is false.
5993 If this is false, then the item will not receive any hover events through
5994 the hoverEnterEvent(), hoverMoveEvent() and hoverLeaveEvent() functions.
5996 bool QQuickItem::acceptHoverEvents() const
5998 Q_D(const QQuickItem);
5999 return d->hoverEnabled;
6003 If \a enabled is true, this sets the item to accept hover events;
6004 otherwise, hover events are not accepted by this item.
6006 \sa acceptHoverEvents()
6008 void QQuickItem::setAcceptHoverEvents(bool enabled)
6011 d->hoverEnabled = enabled;
6014 #ifndef QT_NO_CURSOR
6018 Returns the cursor shape for this item.
6020 The mouse cursor will assume this shape when it is over this
6021 item, unless an override cursor is set.
6022 See the \l{Qt::CursorShape}{list of predefined cursor objects} for a
6023 range of useful shapes.
6025 If no cursor shape has been set this returns a cursor with the Qt::ArrowCursor shape, however
6026 another cursor shape may be displayed if an overlapping item has a valid cursor.
6028 \sa setCursor(), unsetCursor()
6031 QCursor QQuickItem::cursor() const
6033 Q_D(const QQuickItem);
6034 return d->extra.isAllocated()
6040 Sets the \a cursor shape for this item.
6042 \sa cursor(), unsetCursor()
6045 void QQuickItem::setCursor(const QCursor &cursor)
6049 Qt::CursorShape oldShape = d->extra.isAllocated() ? d->extra->cursor.shape() : Qt::ArrowCursor;
6051 if (oldShape != cursor.shape() || oldShape >= Qt::LastCursor || cursor.shape() >= Qt::LastCursor) {
6052 d->extra.value().cursor = cursor;
6054 QQuickWindowPrivate *windowPrivate = QQuickWindowPrivate::get(d->window);
6055 if (windowPrivate->cursorItem == this)
6056 d->window->setCursor(cursor);
6060 if (!d->hasCursor) {
6061 d->hasCursor = true;
6063 QPointF pos = d->window->mapFromGlobal(QGuiApplicationPrivate::lastCursorPosition.toPoint());
6064 if (contains(mapFromScene(pos)))
6065 QQuickWindowPrivate::get(d->window)->updateCursor(pos);
6071 Clears the cursor shape for this item.
6073 \sa cursor(), setCursor()
6076 void QQuickItem::unsetCursor()
6081 d->hasCursor = false;
6082 if (d->extra.isAllocated())
6083 d->extra->cursor = QCursor();
6086 QQuickWindowPrivate *windowPrivate = QQuickWindowPrivate::get(d->window);
6087 if (windowPrivate->cursorItem == this) {
6088 QPointF pos = d->window->mapFromGlobal(QGuiApplicationPrivate::lastCursorPosition.toPoint());
6089 windowPrivate->updateCursor(pos);
6097 Grabs the mouse input.
6099 This item will receive all mouse events until ungrabMouse() is called.
6101 \warning This function should be used with caution.
6103 void QQuickItem::grabMouse()
6108 QQuickWindowPrivate *windowPriv = QQuickWindowPrivate::get(d->window);
6109 if (windowPriv->mouseGrabberItem == this)
6112 QQuickItem *oldGrabber = windowPriv->mouseGrabberItem;
6113 windowPriv->mouseGrabberItem = this;
6115 QEvent ev(QEvent::UngrabMouse);
6116 d->window->sendEvent(oldGrabber, &ev);
6121 Releases the mouse grab following a call to grabMouse().
6123 void QQuickItem::ungrabMouse()
6128 QQuickWindowPrivate *windowPriv = QQuickWindowPrivate::get(d->window);
6129 if (windowPriv->mouseGrabberItem != this) {
6130 qWarning("QQuickItem::ungrabMouse(): Item is not the mouse grabber.");
6134 windowPriv->mouseGrabberItem = 0;
6136 QEvent ev(QEvent::UngrabMouse);
6137 d->window->sendEvent(this, &ev);
6142 Returns whether mouse input should exclusively remain with this item.
6144 \sa setKeepMouseGrab()
6146 bool QQuickItem::keepMouseGrab() const
6148 Q_D(const QQuickItem);
6149 return d->keepMouse;
6153 Sets whether the mouse input should remain exclusively with this item.
6155 This is useful for items that wish to grab and keep mouse
6156 interaction following a predefined gesture. For example,
6157 an item that is interested in horizontal mouse movement
6158 may set keepMouseGrab to true once a threshold has been
6159 exceeded. Once keepMouseGrab has been set to true, filtering
6160 items will not react to mouse events.
6162 If \a keep is false, a filtering item may steal the grab. For example,
6163 \l Flickable may attempt to steal a mouse grab if it detects that the
6164 user has begun to move the viewport.
6168 void QQuickItem::setKeepMouseGrab(bool keep)
6171 d->keepMouse = keep;
6175 Grabs the touch points specified by \a ids.
6177 These touch points will be owned by the item until
6178 they are released. Alternatively, the grab can be stolen
6179 by a filtering item like Flickable. Use setKeepTouchGrab()
6180 to prevent the grab from being stolen.
6182 \sa ungrabTouchPoints(), setKeepTouchGrab()
6184 void QQuickItem::grabTouchPoints(const QVector<int> &ids)
6189 QQuickWindowPrivate *windowPriv = QQuickWindowPrivate::get(d->window);
6191 QSet<QQuickItem*> ungrab;
6192 for (int i = 0; i < ids.count(); ++i) {
6193 QQuickItem *oldGrabber = windowPriv->itemForTouchPointId.value(ids.at(i));
6194 if (oldGrabber == this)
6197 windowPriv->itemForTouchPointId[ids.at(i)] = this;
6199 ungrab.insert(oldGrabber);
6201 foreach (QQuickItem *oldGrabber, ungrab)
6202 oldGrabber->touchUngrabEvent();
6206 Ungrabs the touch points owned by this item.
6208 \sa grabTouchPoints()
6210 void QQuickItem::ungrabTouchPoints()
6215 QQuickWindowPrivate *windowPriv = QQuickWindowPrivate::get(d->window);
6217 QMutableHashIterator<int, QQuickItem*> i(windowPriv->itemForTouchPointId);
6218 while (i.hasNext()) {
6220 if (i.value() == this)
6227 Returns whether the touch points grabbed by this item should exclusively
6228 remain with this item.
6230 \sa setKeepTouchGrab(), keepMouseGrab()
6232 bool QQuickItem::keepTouchGrab() const
6234 Q_D(const QQuickItem);
6235 return d->keepTouch;
6239 Sets whether the touch points grabbed by this item should remain
6240 exclusively with this item.
6242 This is useful for items that wish to grab and keep specific touch
6243 points following a predefined gesture. For example,
6244 an item that is interested in horizontal touch point movement
6245 may set setKeepTouchGrab to true once a threshold has been
6246 exceeded. Once setKeepTouchGrab has been set to true, filtering
6247 items will not react to the relevant touch points.
6249 If \a keep is false, a filtering item may steal the grab. For example,
6250 \l Flickable may attempt to steal a touch point grab if it detects that the
6251 user has begun to move the viewport.
6253 \sa keepTouchGrab(), setKeepMouseGrab()
6255 void QQuickItem::setKeepTouchGrab(bool keep)
6258 d->keepTouch = keep;
6262 Returns true if this item contains \a point, which is in local coordinates;
6263 returns false otherwise.
6265 This function can be overwritten in order to handle point collisions in items
6266 with custom shapes. The default implementation checks if the point is inside
6267 the item's bounding rect.
6269 Note that this method is generally used to check whether the item is under the mouse cursor,
6270 and for that reason, the implementation of this function should be as light-weight
6273 bool QQuickItem::contains(const QPointF &point) const
6275 Q_D(const QQuickItem);
6276 return QRectF(0, 0, d->width, d->height).contains(point);
6280 Maps the given \a point in this item's coordinate system to the equivalent
6281 point within \a item's coordinate system, and returns the mapped
6284 If \a item is 0, this maps \a point to the coordinate system of the
6287 \sa {Concepts - Visual Coordinates in Qt Quick}
6289 QPointF QQuickItem::mapToItem(const QQuickItem *item, const QPointF &point) const
6291 QPointF p = mapToScene(point);
6293 p = item->mapFromScene(p);
6298 Maps the given \a point in this item's coordinate system to the equivalent
6299 point within the scene's coordinate system, and returns the mapped
6302 \sa {Concepts - Visual Coordinates in Qt Quick}
6304 QPointF QQuickItem::mapToScene(const QPointF &point) const
6306 Q_D(const QQuickItem);
6307 return d->itemToWindowTransform().map(point);
6311 Maps the given \a rect in this item's coordinate system to the equivalent
6312 rectangular area within \a item's coordinate system, and returns the mapped
6315 If \a item is 0, this maps \a rect to the coordinate system of the
6318 \sa {Concepts - Visual Coordinates in Qt Quick}
6320 QRectF QQuickItem::mapRectToItem(const QQuickItem *item, const QRectF &rect) const
6322 Q_D(const QQuickItem);
6323 QTransform t = d->itemToWindowTransform();
6325 t *= QQuickItemPrivate::get(item)->windowToItemTransform();
6326 return t.mapRect(rect);
6330 Maps the given \a rect in this item's coordinate system to the equivalent
6331 rectangular area within the scene's coordinate system, and returns the mapped
6334 \sa {Concepts - Visual Coordinates in Qt Quick}
6336 QRectF QQuickItem::mapRectToScene(const QRectF &rect) const
6338 Q_D(const QQuickItem);
6339 return d->itemToWindowTransform().mapRect(rect);
6343 Maps the given \a point in \a item's coordinate system to the equivalent
6344 point within this item's coordinate system, and returns the mapped
6347 If \a item is 0, this maps \a point from the coordinate system of the
6350 \sa {Concepts - Visual Coordinates in Qt Quick}
6352 QPointF QQuickItem::mapFromItem(const QQuickItem *item, const QPointF &point) const
6354 QPointF p = item?item->mapToScene(point):point;
6355 return mapFromScene(p);
6359 Maps the given \a point in the scene's coordinate system to the equivalent
6360 point within this item's coordinate system, and returns the mapped
6363 \sa {Concepts - Visual Coordinates in Qt Quick}
6365 QPointF QQuickItem::mapFromScene(const QPointF &point) const
6367 Q_D(const QQuickItem);
6368 return d->windowToItemTransform().map(point);
6372 Maps the given \a rect in \a item's coordinate system to the equivalent
6373 rectangular area within this item's coordinate system, and returns the mapped
6376 If \a item is 0, this maps \a rect from the coordinate system of the
6379 \sa {Concepts - Visual Coordinates in Qt Quick}
6381 QRectF QQuickItem::mapRectFromItem(const QQuickItem *item, const QRectF &rect) const
6383 Q_D(const QQuickItem);
6384 QTransform t = item?QQuickItemPrivate::get(item)->itemToWindowTransform():QTransform();
6385 t *= d->windowToItemTransform();
6386 return t.mapRect(rect);
6390 Maps the given \a rect in the scene's coordinate system to the equivalent
6391 rectangular area within this item's coordinate system, and returns the mapped
6394 \sa {Concepts - Visual Coordinates in Qt Quick}
6396 QRectF QQuickItem::mapRectFromScene(const QRectF &rect) const
6398 Q_D(const QQuickItem);
6399 return d->windowToItemTransform().mapRect(rect);
6403 \property QQuickItem::anchors
6408 \property QQuickItem::left
6413 \property QQuickItem::right
6418 \property QQuickItem::horizontalCenter
6423 \property QQuickItem::top
6428 \property QQuickItem::bottom
6433 \property QQuickItem::verticalCenter
6438 \property QQuickItem::baseline
6443 \property QQuickItem::data
6448 \property QQuickItem::resources
6455 bool QQuickItem::event(QEvent *ev)
6458 if (ev->type() == QEvent::PolishRequest) {
6460 d->polishScheduled = false;
6464 return QObject::event(ev);
6467 if (ev->type() == QEvent::InputMethodQuery) {
6468 QInputMethodQueryEvent *query = static_cast<QInputMethodQueryEvent *>(ev);
6469 Qt::InputMethodQueries queries = query->queries();
6470 for (uint i = 0; i < 32; ++i) {
6471 Qt::InputMethodQuery q = (Qt::InputMethodQuery)(int)(queries & (1<<i));
6473 QVariant v = inputMethodQuery(q);
6474 query->setValue(q, v);
6479 } else if (ev->type() == QEvent::InputMethod) {
6480 inputMethodEvent(static_cast<QInputMethodEvent *>(ev));
6483 return QObject::event(ev);
6486 #ifndef QT_NO_DEBUG_STREAM
6487 QDebug operator<<(QDebug debug, QQuickItem *item)
6490 debug << "QQuickItem(0)";
6494 debug << item->metaObject()->className() << "(this =" << ((void*)item)
6495 << ", name=" << item->objectName()
6496 << ", parent =" << ((void*)item->parentItem())
6497 << ", geometry =" << QRectF(item->pos(), QSizeF(item->width(), item->height()))
6498 << ", z =" << item->z() << ')';
6503 qint64 QQuickItemPrivate::consistentTime = -1;
6504 void QQuickItemPrivate::setConsistentTime(qint64 t)
6509 class QElapsedTimerConsistentTimeHack
6513 t1 = QQuickItemPrivate::consistentTime;
6517 return QQuickItemPrivate::consistentTime - t1;
6520 qint64 val = QQuickItemPrivate::consistentTime - t1;
6521 t1 = QQuickItemPrivate::consistentTime;
6531 void QQuickItemPrivate::start(QElapsedTimer &t)
6533 if (QQuickItemPrivate::consistentTime == -1)
6536 ((QElapsedTimerConsistentTimeHack*)&t)->start();
6539 qint64 QQuickItemPrivate::elapsed(QElapsedTimer &t)
6541 if (QQuickItemPrivate::consistentTime == -1)
6544 return ((QElapsedTimerConsistentTimeHack*)&t)->elapsed();
6547 qint64 QQuickItemPrivate::restart(QElapsedTimer &t)
6549 if (QQuickItemPrivate::consistentTime == -1)
6552 return ((QElapsedTimerConsistentTimeHack*)&t)->restart();
6556 \fn bool QQuickItem::isTextureProvider() const
6558 Returns true if this item is a texture provider. The default
6559 implementation returns false.
6561 This function can be called from any thread.
6564 bool QQuickItem::isTextureProvider() const
6566 Q_D(const QQuickItem);
6567 return d->extra.isAllocated() && d->extra->layer && d->extra->layer->effectSource() ?
6568 d->extra->layer->effectSource()->isTextureProvider() : false;
6572 \fn QSGTextureProvider *QQuickItem::textureProvider() const
6574 Returns the texture provider for an item. The default implementation
6577 This function may only be called on the rendering thread.
6580 QSGTextureProvider *QQuickItem::textureProvider() const
6582 Q_D(const QQuickItem);
6583 return d->extra.isAllocated() && d->extra->layer && d->extra->layer->effectSource() ?
6584 d->extra->layer->effectSource()->textureProvider() : 0;
6588 \property QQuickItem::layer
6591 QQuickItemLayer *QQuickItemPrivate::layer() const
6593 if (!extra.isAllocated() || !extra->layer) {
6594 extra.value().layer = new QQuickItemLayer(const_cast<QQuickItem *>(q_func()));
6595 if (!componentComplete)
6596 extra->layer->classBegin();
6598 return extra->layer;
6601 QQuickItemLayer::QQuickItemLayer(QQuickItem *item)
6606 , m_componentComplete(true)
6607 , m_wrapMode(QQuickShaderEffectSource::ClampToEdge)
6608 , m_format(QQuickShaderEffectSource::RGBA)
6610 , m_effectComponent(0)
6616 QQuickItemLayer::~QQuickItemLayer()
6618 delete m_effectSource;
6623 \qmlproperty bool QtQuick2::Item::layer.enabled
6625 Holds whether the item is layered or not. Layering is disabled by default.
6627 A layered item is rendered into an offscreen surface and cached until
6628 it is changed. Enabling layering for complex QML item hierarchies can
6629 sometimes be an optimization.
6631 None of the other layer properties have any effect when the layer
6634 void QQuickItemLayer::setEnabled(bool e)
6639 if (m_componentComplete) {
6646 emit enabledChanged(e);
6649 void QQuickItemLayer::classBegin()
6651 Q_ASSERT(!m_effectSource);
6652 Q_ASSERT(!m_effect);
6653 m_componentComplete = false;
6656 void QQuickItemLayer::componentComplete()
6658 Q_ASSERT(!m_componentComplete);
6659 m_componentComplete = true;
6664 void QQuickItemLayer::activate()
6666 Q_ASSERT(!m_effectSource);
6667 m_effectSource = new QQuickShaderEffectSource();
6669 QQuickItem *parentItem = m_item->parentItem();
6671 m_effectSource->setParentItem(parentItem);
6672 m_effectSource->stackAfter(m_item);
6675 m_effectSource->setSourceItem(m_item);
6676 m_effectSource->setHideSource(true);
6677 m_effectSource->setSmooth(m_smooth);
6678 m_effectSource->setTextureSize(m_size);
6679 m_effectSource->setSourceRect(m_sourceRect);
6680 m_effectSource->setMipmap(m_mipmap);
6681 m_effectSource->setWrapMode(m_wrapMode);
6682 m_effectSource->setFormat(m_format);
6684 if (m_effectComponent)
6687 m_effectSource->setVisible(m_item->isVisible() && !m_effect);
6694 QQuickItemPrivate *id = QQuickItemPrivate::get(m_item);
6695 id->addItemChangeListener(this, QQuickItemPrivate::Geometry | QQuickItemPrivate::Opacity | QQuickItemPrivate::Parent | QQuickItemPrivate::Visibility | QQuickItemPrivate::SiblingOrder);
6698 void QQuickItemLayer::deactivate()
6700 Q_ASSERT(m_effectSource);
6702 if (m_effectComponent)
6705 delete m_effectSource;
6708 QQuickItemPrivate *id = QQuickItemPrivate::get(m_item);
6709 id->removeItemChangeListener(this, QQuickItemPrivate::Geometry | QQuickItemPrivate::Opacity | QQuickItemPrivate::Parent | QQuickItemPrivate::Visibility | QQuickItemPrivate::SiblingOrder);
6712 void QQuickItemLayer::activateEffect()
6714 Q_ASSERT(m_effectSource);
6715 Q_ASSERT(m_effectComponent);
6716 Q_ASSERT(!m_effect);
6718 QObject *created = m_effectComponent->beginCreate(m_effectComponent->creationContext());
6719 m_effect = qobject_cast<QQuickItem *>(created);
6721 qWarning("Item: layer.effect is not a QML Item.");
6722 m_effectComponent->completeCreate();
6726 QQuickItem *parentItem = m_item->parentItem();
6728 m_effect->setParentItem(parentItem);
6729 m_effect->stackAfter(m_effectSource);
6731 m_effect->setVisible(m_item->isVisible());
6732 m_effect->setProperty(m_name, qVariantFromValue<QObject *>(m_effectSource));
6733 m_effectComponent->completeCreate();
6736 void QQuickItemLayer::deactivateEffect()
6738 Q_ASSERT(m_effectSource);
6739 Q_ASSERT(m_effectComponent);
6747 \qmlproperty Component QtQuick2::Item::layer.effect
6749 Holds the effect that is applied to this layer.
6751 The effect is typically a \l ShaderEffect component, although any \l Item component can be
6752 assigned. The effect should have a source texture property with a name matching \l layer.samplerName.
6754 \sa layer.samplerName
6757 void QQuickItemLayer::setEffect(QQmlComponent *component)
6759 if (component == m_effectComponent)
6762 bool updateNeeded = false;
6763 if (m_effectSource && m_effectComponent) {
6765 updateNeeded = true;
6768 m_effectComponent = component;
6770 if (m_effectSource && m_effectComponent) {
6772 updateNeeded = true;
6780 m_effectSource->setVisible(m_item->isVisible() && !m_effect);
6783 emit effectChanged(component);
6788 \qmlproperty bool QtQuick2::Item::layer.mipmap
6790 If this property is true, mipmaps are generated for the texture.
6792 \note Some OpenGL ES 2 implementations do not support mipmapping of
6793 non-power-of-two textures.
6796 void QQuickItemLayer::setMipmap(bool mipmap)
6798 if (mipmap == m_mipmap)
6803 m_effectSource->setMipmap(m_mipmap);
6805 emit mipmapChanged(mipmap);
6810 \qmlproperty enumeration QtQuick2::Item::layer.format
6812 This property defines the internal OpenGL format of the texture.
6813 Modifying this property makes most sense when the \a layer.effect is also
6814 specified. Depending on the OpenGL implementation, this property might
6815 allow you to save some texture memory.
6818 \li ShaderEffectSource.Alpha - GL_ALPHA
6819 \li ShaderEffectSource.RGB - GL_RGB
6820 \li ShaderEffectSource.RGBA - GL_RGBA
6823 \note Some OpenGL implementations do not support the GL_ALPHA format.
6826 void QQuickItemLayer::setFormat(QQuickShaderEffectSource::Format f)
6833 m_effectSource->setFormat(m_format);
6835 emit formatChanged(m_format);
6840 \qmlproperty enumeration QtQuick2::Item::layer.sourceRect
6842 This property defines the rectangular area of the item that should be
6843 rendered into the texture. The source rectangle can be larger than
6844 the item itself. If the rectangle is null, which is the default,
6845 then the whole item is rendered to the texture.
6848 void QQuickItemLayer::setSourceRect(const QRectF &sourceRect)
6850 if (sourceRect == m_sourceRect)
6852 m_sourceRect = sourceRect;
6855 m_effectSource->setSourceRect(m_sourceRect);
6857 emit sourceRectChanged(sourceRect);
6861 \qmlproperty bool QtQuick2::Item::layer.smooth
6863 Holds whether the layer is smoothly transformed.
6866 void QQuickItemLayer::setSmooth(bool s)
6873 m_effectSource->setSmooth(m_smooth);
6875 emit smoothChanged(s);
6879 \qmlproperty size QtQuick2::Item::layer.textureSize
6881 This property holds the requested pixel size of the layers texture. If it is empty,
6882 which is the default, the size of the item is used.
6884 \note Some platforms have a limit on how small framebuffer objects can be,
6885 which means the actual texture size might be larger than the requested
6889 void QQuickItemLayer::setSize(const QSize &size)
6896 m_effectSource->setTextureSize(size);
6898 emit sizeChanged(size);
6902 \qmlproperty enumeration QtQuick2::Item::layer.wrapMode
6904 This property defines the OpenGL wrap modes associated with the texture.
6905 Modifying this property makes most sense when the \a layer.effect is
6909 \li ShaderEffectSource.ClampToEdge - GL_CLAMP_TO_EDGE both horizontally and vertically
6910 \li ShaderEffectSource.RepeatHorizontally - GL_REPEAT horizontally, GL_CLAMP_TO_EDGE vertically
6911 \li ShaderEffectSource.RepeatVertically - GL_CLAMP_TO_EDGE horizontally, GL_REPEAT vertically
6912 \li ShaderEffectSource.Repeat - GL_REPEAT both horizontally and vertically
6915 \note Some OpenGL ES 2 implementations do not support the GL_REPEAT
6916 wrap mode with non-power-of-two textures.
6919 void QQuickItemLayer::setWrapMode(QQuickShaderEffectSource::WrapMode mode)
6921 if (mode == m_wrapMode)
6926 m_effectSource->setWrapMode(m_wrapMode);
6928 emit wrapModeChanged(mode);
6932 \qmlproperty string QtQuick2::Item::layer.samplerName
6934 Holds the name of the effect's source texture property.
6936 This value must match the name of the effect's source texture property
6937 so that the Item can pass the layer's offscreen surface to the effect correctly.
6939 \sa layer.effect, ShaderEffect
6942 void QQuickItemLayer::setName(const QByteArray &name) {
6946 m_effect->setProperty(m_name, QVariant());
6947 m_effect->setProperty(name, qVariantFromValue<QObject *>(m_effectSource));
6950 emit nameChanged(name);
6953 void QQuickItemLayer::itemOpacityChanged(QQuickItem *item)
6959 void QQuickItemLayer::itemGeometryChanged(QQuickItem *, const QRectF &, const QRectF &)
6964 void QQuickItemLayer::itemParentChanged(QQuickItem *item, QQuickItem *parent)
6967 Q_ASSERT(item == m_item);
6968 Q_ASSERT(parent != m_effectSource);
6969 Q_ASSERT(parent == 0 || parent != m_effect);
6971 m_effectSource->setParentItem(parent);
6973 m_effectSource->stackAfter(m_item);
6976 m_effect->setParentItem(parent);
6978 m_effect->stackAfter(m_effectSource);
6982 void QQuickItemLayer::itemSiblingOrderChanged(QQuickItem *)
6984 m_effectSource->stackAfter(m_item);
6986 m_effect->stackAfter(m_effectSource);
6989 void QQuickItemLayer::itemVisibilityChanged(QQuickItem *)
6991 QQuickItem *l = m_effect ? (QQuickItem *) m_effect : (QQuickItem *) m_effectSource;
6993 l->setVisible(m_item->isVisible());
6996 void QQuickItemLayer::updateZ()
6998 if (!m_componentComplete || !m_enabled)
7000 QQuickItem *l = m_effect ? (QQuickItem *) m_effect : (QQuickItem *) m_effectSource;
7002 l->setZ(m_item->z());
7005 void QQuickItemLayer::updateOpacity()
7007 QQuickItem *l = m_effect ? (QQuickItem *) m_effect : (QQuickItem *) m_effectSource;
7009 l->setOpacity(m_item->opacity());
7012 void QQuickItemLayer::updateGeometry()
7014 QQuickItem *l = m_effect ? (QQuickItem *) m_effect : (QQuickItem *) m_effectSource;
7016 QRectF bounds = m_item->clipRect();
7017 l->setWidth(bounds.width());
7018 l->setHeight(bounds.height());
7019 l->setX(bounds.x() + m_item->x());
7020 l->setY(bounds.y() + m_item->y());
7023 void QQuickItemLayer::updateMatrix()
7025 // Called directly from transformChanged(), so needs some extra
7027 if (!m_componentComplete || !m_enabled)
7029 QQuickItem *l = m_effect ? (QQuickItem *) m_effect : (QQuickItem *) m_effectSource;
7031 QQuickItemPrivate *ld = QQuickItemPrivate::get(l);
7032 l->setScale(m_item->scale());
7033 l->setRotation(m_item->rotation());
7034 ld->transforms = QQuickItemPrivate::get(m_item)->transforms;
7035 if (ld->origin() != QQuickItemPrivate::get(m_item)->origin())
7036 ld->extra.value().origin = QQuickItemPrivate::get(m_item)->origin();
7037 ld->dirty(QQuickItemPrivate::Transform);
7040 QQuickItemPrivate::ExtraData::ExtraData()
7041 : z(0), scale(1), rotation(0), opacity(1),
7042 contents(0), screenAttached(0), layoutDirectionAttached(0),
7043 keyHandler(0), layer(0), effectRefCount(0), hideRefCount(0),
7044 opacityNode(0), clipNode(0), rootNode(0), beforePaintNode(0),
7045 acceptedMouseButtons(0), origin(QQuickItem::Center)
7051 #include <moc_qquickitem.cpp>