1 /****************************************************************************
3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the QtDeclarative module of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** GNU Lesser General Public License Usage
11 ** This file may be used under the terms of the GNU Lesser General Public
12 ** License version 2.1 as published by the Free Software Foundation and
13 ** appearing in the file LICENSE.LGPL included in the packaging of this
14 ** file. Please review the following information to ensure the GNU Lesser
15 ** General Public License version 2.1 requirements will be met:
16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
18 ** In addition, as a special exception, Nokia gives you certain additional
19 ** rights. These rights are described in the Nokia Qt LGPL Exception
20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
22 ** GNU General Public License Usage
23 ** Alternatively, this file may be used under the terms of the GNU General
24 ** Public License version 3.0 as published by the Free Software Foundation
25 ** and appearing in the file LICENSE.GPL included in the packaging of this
26 ** file. Please review the following information to ensure the GNU General
27 ** Public License version 3.0 requirements will be met:
28 ** http://www.gnu.org/copyleft/gpl.html.
31 ** Alternatively, this file may be used in accordance with the terms and
32 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
42 #include "qquickitem.h"
44 #include "qquickcanvas.h"
45 #include <QtDeclarative/qjsengine.h>
46 #include "qquickcanvas_p.h"
48 #include "qquickevents_p_p.h"
49 #include "qquickscreen_p.h"
51 #include <QtDeclarative/qdeclarativeengine.h>
52 #include <QtDeclarative/qdeclarativecomponent.h>
53 #include <QtDeclarative/qdeclarativeinfo.h>
54 #include <QtGui/qpen.h>
55 #include <QtGui/qcursor.h>
56 #include <QtGui/qguiapplication.h>
57 #include <QtGui/qinputpanel.h>
58 #include <QtCore/qdebug.h>
59 #include <QtCore/qcoreevent.h>
60 #include <QtCore/qnumeric.h>
62 #include <private/qdeclarativeengine_p.h>
63 #include <QtQuick/private/qdeclarativestategroup_p.h>
64 #include <private/qdeclarativeopenmetaobject_p.h>
65 #include <QtQuick/private/qdeclarativestate_p.h>
66 #include <private/qlistmodelinterface_p.h>
67 #include <private/qquickitem_p.h>
68 #include <private/qdeclarativeaccessors_p.h>
72 // XXX todo Check that elements that create items handle memory correctly after visual ownership change
76 static void QQuickItem_parentNotifier(QObject *o, intptr_t, QDeclarativeNotifier **n)
78 QQuickItemPrivate *d = QQuickItemPrivate::get(static_cast<QQuickItem *>(o));
79 *n = &d->parentNotifier;
82 QML_PRIVATE_ACCESSOR(QQuickItem, QQuickItem *, parent, parentItem)
83 QML_PRIVATE_ACCESSOR(QQuickItem, qreal, x, x)
84 QML_PRIVATE_ACCESSOR(QQuickItem, qreal, y, y)
85 QML_PRIVATE_ACCESSOR(QQuickItem, qreal, width, width)
86 QML_PRIVATE_ACCESSOR(QQuickItem, qreal, height, height)
88 static QDeclarativeAccessors QQuickItem_parent = { QQuickItem_parentRead, QQuickItem_parentNotifier };
89 static QDeclarativeAccessors QQuickItem_x = { QQuickItem_xRead, 0 };
90 static QDeclarativeAccessors QQuickItem_y = { QQuickItem_yRead, 0 };
91 static QDeclarativeAccessors QQuickItem_width = { QQuickItem_widthRead, 0 };
92 static QDeclarativeAccessors QQuickItem_height = { QQuickItem_heightRead, 0 };
94 QML_DECLARE_PROPERTIES(QQuickItem) {
95 { QML_PROPERTY_NAME(parent), 0, &QQuickItem_parent },
96 { QML_PROPERTY_NAME(x), 0, &QQuickItem_x },
97 { QML_PROPERTY_NAME(y), 0, &QQuickItem_y },
98 { QML_PROPERTY_NAME(width), 0, &QQuickItem_width },
99 { QML_PROPERTY_NAME(height), 0, &QQuickItem_height }
102 void QQuickItemPrivate::registerAccessorProperties()
104 QML_DEFINE_PROPERTIES(QQuickItem);
108 \qmlclass Transform QQuickTransform
109 \inqmlmodule QtQuick 2
110 \ingroup qml-transform-elements
111 \brief The Transform elements provide a way of building advanced transformations on Items.
113 The Transform element is a base type which cannot be instantiated directly.
114 The following concrete Transform types are available:
122 The Transform elements let you create and control advanced transformations that can be configured
123 independently using specialized properties.
125 You can assign any number of Transform elements to an \l Item. Each Transform is applied in order,
130 \qmlclass Translate QQuickTranslate
131 \inqmlmodule QtQuick 2
132 \ingroup qml-transform-elements
133 \brief The Translate object provides a way to move an Item without changing its x or y properties.
135 The Translate object provides independent control over position in addition to the Item's x and y properties.
137 The following example moves the Y axis of the \l Rectangle elements while still allowing the \l Row element
138 to lay the items out as if they had not been transformed:
144 width: 100; height: 100
146 transform: Translate { y: 20 }
149 width: 100; height: 100
151 transform: Translate { y: -20 }
160 \qmlproperty real QtQuick2::Translate::x
162 The translation along the X axis.
166 \qmlproperty real QtQuick2::Translate::y
168 The translation along the Y axis.
172 \qmlclass Scale QQuickScale
173 \inqmlmodule QtQuick 2
174 \ingroup qml-transform-elements
175 \brief The Scale element provides a way to scale an Item.
177 The Scale element gives more control over scaling than using \l Item's \l{Item::scale}{scale} property. Specifically,
178 it allows a different scale for the x and y axes, and allows the scale to be relative to an
181 The following example scales the X axis of the Rectangle, relative to its interior point 25, 25:
184 width: 100; height: 100
186 transform: Scale { origin.x: 25; origin.y: 25; xScale: 3}
190 \sa Rotation, Translate
194 \qmlproperty real QtQuick2::Scale::origin.x
195 \qmlproperty real QtQuick2::Scale::origin.y
197 The point that the item is scaled from (i.e., the point that stays fixed relative to the parent as
198 the rest of the item grows). By default the origin is 0, 0.
202 \qmlproperty real QtQuick2::Scale::xScale
204 The scaling factor for the X axis.
208 \qmlproperty real QtQuick2::Scale::yScale
210 The scaling factor for the Y axis.
214 \qmlclass Rotation QQuickRotation
215 \inqmlmodule QtQuick 2
216 \ingroup qml-transform-elements
217 \brief The Rotation object provides a way to rotate an Item.
219 The Rotation object gives more control over rotation than using \l Item's \l{Item::rotation}{rotation} property.
220 Specifically, it allows (z axis) rotation to be relative to an arbitrary point.
222 The following example rotates a Rectangle around its interior point 25, 25:
225 width: 100; height: 100
227 transform: Rotation { origin.x: 25; origin.y: 25; angle: 45}
231 Rotation also provides a way to specify 3D-like rotations for Items. For these types of
232 rotations you must specify the axis to rotate around in addition to the origin point.
234 The following example shows various 3D-like rotations applied to an \l Image.
235 \snippet doc/src/snippets/declarative/rotation.qml 0
237 \image axisrotation.png
239 \sa {declarative/ui-components/dialcontrol}{Dial Control example}, {declarative/toys/clocks}{Clocks example}
243 \qmlproperty real QtQuick2::Rotation::origin.x
244 \qmlproperty real QtQuick2::Rotation::origin.y
246 The origin point of the rotation (i.e., the point that stays fixed relative to the parent as
247 the rest of the item rotates). By default the origin is 0, 0.
251 \qmlproperty real QtQuick2::Rotation::axis.x
252 \qmlproperty real QtQuick2::Rotation::axis.y
253 \qmlproperty real QtQuick2::Rotation::axis.z
255 The axis to rotate around. For simple (2D) rotation around a point, you do not need to specify an axis,
256 as the default axis is the z axis (\c{ axis { x: 0; y: 0; z: 1 } }).
258 For a typical 3D-like rotation you will usually specify both the origin and the axis.
260 \image 3d-rotation-axis.png
264 \qmlproperty real QtQuick2::Rotation::angle
266 The angle to rotate, in degrees clockwise.
269 QQuickTransformPrivate::QQuickTransformPrivate()
273 QQuickTransform::QQuickTransform(QObject *parent)
274 : QObject(*(new QQuickTransformPrivate), parent)
278 QQuickTransform::QQuickTransform(QQuickTransformPrivate &dd, QObject *parent)
279 : QObject(dd, parent)
283 QQuickTransform::~QQuickTransform()
285 Q_D(QQuickTransform);
286 for (int ii = 0; ii < d->items.count(); ++ii) {
287 QQuickItemPrivate *p = QQuickItemPrivate::get(d->items.at(ii));
288 p->transforms.removeOne(this);
289 p->dirty(QQuickItemPrivate::Transform);
293 void QQuickTransform::update()
295 Q_D(QQuickTransform);
296 for (int ii = 0; ii < d->items.count(); ++ii) {
297 QQuickItemPrivate *p = QQuickItemPrivate::get(d->items.at(ii));
298 p->dirty(QQuickItemPrivate::Transform);
302 QQuickContents::QQuickContents(QQuickItem *item)
303 : m_item(item), m_x(0), m_y(0), m_width(0), m_height(0)
307 QQuickContents::~QQuickContents()
309 QList<QQuickItem *> children = m_item->childItems();
310 for (int i = 0; i < children.count(); ++i) {
311 QQuickItem *child = children.at(i);
312 QQuickItemPrivate::get(child)->removeItemChangeListener(this, QQuickItemPrivate::Geometry | QQuickItemPrivate::Destroyed);
316 bool QQuickContents::calcHeight(QQuickItem *changed)
319 qreal oldheight = m_height;
323 qreal bottom = oldy + oldheight;
324 qreal y = changed->y();
325 if (y + changed->height() > bottom)
326 bottom = y + changed->height();
330 m_height = bottom - top;
334 QList<QQuickItem *> children = m_item->childItems();
335 for (int i = 0; i < children.count(); ++i) {
336 QQuickItem *child = children.at(i);
337 qreal y = child->y();
338 if (y + child->height() > bottom)
339 bottom = y + child->height();
343 if (!children.isEmpty())
345 m_height = qMax(bottom - top, qreal(0.0));
348 return (m_height != oldheight || m_y != oldy);
351 bool QQuickContents::calcWidth(QQuickItem *changed)
354 qreal oldwidth = m_width;
358 qreal right = oldx + oldwidth;
359 qreal x = changed->x();
360 if (x + changed->width() > right)
361 right = x + changed->width();
365 m_width = right - left;
367 qreal left = FLT_MAX;
369 QList<QQuickItem *> children = m_item->childItems();
370 for (int i = 0; i < children.count(); ++i) {
371 QQuickItem *child = children.at(i);
372 qreal x = child->x();
373 if (x + child->width() > right)
374 right = x + child->width();
378 if (!children.isEmpty())
380 m_width = qMax(right - left, qreal(0.0));
383 return (m_width != oldwidth || m_x != oldx);
386 void QQuickContents::complete()
388 QQuickItemPrivate::get(m_item)->addItemChangeListener(this, QQuickItemPrivate::Children);
390 QList<QQuickItem *> children = m_item->childItems();
391 for (int i = 0; i < children.count(); ++i) {
392 QQuickItem *child = children.at(i);
393 QQuickItemPrivate::get(child)->addItemChangeListener(this, QQuickItemPrivate::Geometry | QQuickItemPrivate::Destroyed);
394 //###what about changes to visibility?
399 void QQuickContents::updateRect()
401 QQuickItemPrivate::get(m_item)->emitChildrenRectChanged(rectF());
404 void QQuickContents::itemGeometryChanged(QQuickItem *changed, const QRectF &newGeometry, const QRectF &oldGeometry)
407 bool wChanged = false;
408 bool hChanged = false;
409 //### we can only pass changed if the left edge has moved left, or the right edge has moved right
410 if (newGeometry.width() != oldGeometry.width() || newGeometry.x() != oldGeometry.x())
411 wChanged = calcWidth(/*changed*/);
412 if (newGeometry.height() != oldGeometry.height() || newGeometry.y() != oldGeometry.y())
413 hChanged = calcHeight(/*changed*/);
414 if (wChanged || hChanged)
418 void QQuickContents::itemDestroyed(QQuickItem *item)
421 QQuickItemPrivate::get(item)->removeItemChangeListener(this, QQuickItemPrivate::Geometry | QQuickItemPrivate::Destroyed);
425 void QQuickContents::itemChildRemoved(QQuickItem *, QQuickItem *item)
428 QQuickItemPrivate::get(item)->removeItemChangeListener(this, QQuickItemPrivate::Geometry | QQuickItemPrivate::Destroyed);
432 void QQuickContents::itemChildAdded(QQuickItem *, QQuickItem *item)
435 QQuickItemPrivate::get(item)->addItemChangeListener(this, QQuickItemPrivate::Geometry | QQuickItemPrivate::Destroyed);
439 QQuickItemKeyFilter::QQuickItemKeyFilter(QQuickItem *item)
440 : m_processPost(false), m_next(0)
442 QQuickItemPrivate *p = item?QQuickItemPrivate::get(item):0;
444 m_next = p->keyHandler;
445 p->keyHandler = this;
449 QQuickItemKeyFilter::~QQuickItemKeyFilter()
453 void QQuickItemKeyFilter::keyPressed(QKeyEvent *event, bool post)
455 if (m_next) m_next->keyPressed(event, post);
458 void QQuickItemKeyFilter::keyReleased(QKeyEvent *event, bool post)
460 if (m_next) m_next->keyReleased(event, post);
463 void QQuickItemKeyFilter::inputMethodEvent(QInputMethodEvent *event, bool post)
466 m_next->inputMethodEvent(event, post);
471 QVariant QQuickItemKeyFilter::inputMethodQuery(Qt::InputMethodQuery query) const
473 if (m_next) return m_next->inputMethodQuery(query);
477 void QQuickItemKeyFilter::componentComplete()
479 if (m_next) m_next->componentComplete();
482 \qmlclass KeyNavigation QQuickKeyNavigationAttached
483 \inqmlmodule QtQuick 2
484 \ingroup qml-basic-interaction-elements
485 \brief The KeyNavigation attached property supports key navigation by arrow keys.
487 Key-based user interfaces commonly allow the use of arrow keys to navigate between
488 focusable items. The KeyNavigation attached property enables this behavior by providing a
489 convenient way to specify the item that should gain focus when an arrow or tab key is pressed.
491 The following example provides key navigation for a 2x2 grid of items:
493 \snippet doc/src/snippets/declarative/keynavigation.qml 0
495 The top-left item initially receives focus by setting \l {Item::}{focus} to
496 \c true. When an arrow key is pressed, the focus will move to the
497 appropriate item, as defined by the value that has been set for
498 the KeyNavigation \l left, \l right, \l up or \l down properties.
500 Note that if a KeyNavigation attached property receives the key press and release
501 events for a requested arrow or tab key, the event is accepted and does not
502 propagate any further.
504 By default, KeyNavigation receives key events after the item to which it is attached.
505 If the item accepts the key event, the KeyNavigation attached property will not
506 receive an event for that key. Setting the \l priority property to
507 \c KeyNavigation.BeforeItem allows the event to be used for key navigation
508 before the item, rather than after.
510 If item to which the focus is switching is not enabled or visible, an attempt will
511 be made to skip this item and focus on the next. This is possible if there are
512 a chain of items with the same KeyNavigation handler. If multiple items in a row are not enabled
513 or visible, they will also be skipped.
515 KeyNavigation will implicitly set the other direction to return focus to this item. So if you set
516 \l left to another item, \l right will be set on that item's KeyNavigation to set focus back to this
517 item. However, if that item's KeyNavigation has had right explicitly set then no change will occur.
518 This means that the above example could have been written, with the same behaviour, without specifing
519 KeyNavigation.right or KeyNavigation.down for any of the items.
521 \sa {Keys}{Keys attached property}
525 \qmlproperty Item QtQuick2::KeyNavigation::left
526 \qmlproperty Item QtQuick2::KeyNavigation::right
527 \qmlproperty Item QtQuick2::KeyNavigation::up
528 \qmlproperty Item QtQuick2::KeyNavigation::down
529 \qmlproperty Item QtQuick2::KeyNavigation::tab
530 \qmlproperty Item QtQuick2::KeyNavigation::backtab
532 These properties hold the item to assign focus to
533 when the left, right, up or down cursor keys, or the
538 \qmlproperty Item QtQuick2::KeyNavigation::tab
539 \qmlproperty Item QtQuick2::KeyNavigation::backtab
541 These properties hold the item to assign focus to
542 when the Tab key or Shift+Tab key combination (Backtab) are pressed.
545 QQuickKeyNavigationAttached::QQuickKeyNavigationAttached(QObject *parent)
546 : QObject(*(new QQuickKeyNavigationAttachedPrivate), parent),
547 QQuickItemKeyFilter(qobject_cast<QQuickItem*>(parent))
549 m_processPost = true;
552 QQuickKeyNavigationAttached *
553 QQuickKeyNavigationAttached::qmlAttachedProperties(QObject *obj)
555 return new QQuickKeyNavigationAttached(obj);
558 QQuickItem *QQuickKeyNavigationAttached::left() const
560 Q_D(const QQuickKeyNavigationAttached);
564 void QQuickKeyNavigationAttached::setLeft(QQuickItem *i)
566 Q_D(QQuickKeyNavigationAttached);
571 QQuickKeyNavigationAttached* other =
572 qobject_cast<QQuickKeyNavigationAttached*>(qmlAttachedPropertiesObject<QQuickKeyNavigationAttached>(i));
573 if (other && !other->d_func()->rightSet){
574 other->d_func()->right = qobject_cast<QQuickItem*>(parent());
575 emit other->rightChanged();
580 QQuickItem *QQuickKeyNavigationAttached::right() const
582 Q_D(const QQuickKeyNavigationAttached);
586 void QQuickKeyNavigationAttached::setRight(QQuickItem *i)
588 Q_D(QQuickKeyNavigationAttached);
593 QQuickKeyNavigationAttached* other =
594 qobject_cast<QQuickKeyNavigationAttached*>(qmlAttachedPropertiesObject<QQuickKeyNavigationAttached>(i));
595 if (other && !other->d_func()->leftSet){
596 other->d_func()->left = qobject_cast<QQuickItem*>(parent());
597 emit other->leftChanged();
602 QQuickItem *QQuickKeyNavigationAttached::up() const
604 Q_D(const QQuickKeyNavigationAttached);
608 void QQuickKeyNavigationAttached::setUp(QQuickItem *i)
610 Q_D(QQuickKeyNavigationAttached);
615 QQuickKeyNavigationAttached* other =
616 qobject_cast<QQuickKeyNavigationAttached*>(qmlAttachedPropertiesObject<QQuickKeyNavigationAttached>(i));
617 if (other && !other->d_func()->downSet){
618 other->d_func()->down = qobject_cast<QQuickItem*>(parent());
619 emit other->downChanged();
624 QQuickItem *QQuickKeyNavigationAttached::down() const
626 Q_D(const QQuickKeyNavigationAttached);
630 void QQuickKeyNavigationAttached::setDown(QQuickItem *i)
632 Q_D(QQuickKeyNavigationAttached);
637 QQuickKeyNavigationAttached* other =
638 qobject_cast<QQuickKeyNavigationAttached*>(qmlAttachedPropertiesObject<QQuickKeyNavigationAttached>(i));
639 if (other && !other->d_func()->upSet) {
640 other->d_func()->up = qobject_cast<QQuickItem*>(parent());
641 emit other->upChanged();
646 QQuickItem *QQuickKeyNavigationAttached::tab() const
648 Q_D(const QQuickKeyNavigationAttached);
652 void QQuickKeyNavigationAttached::setTab(QQuickItem *i)
654 Q_D(QQuickKeyNavigationAttached);
659 QQuickKeyNavigationAttached* other =
660 qobject_cast<QQuickKeyNavigationAttached*>(qmlAttachedPropertiesObject<QQuickKeyNavigationAttached>(i));
661 if (other && !other->d_func()->backtabSet) {
662 other->d_func()->backtab = qobject_cast<QQuickItem*>(parent());
663 emit other->backtabChanged();
668 QQuickItem *QQuickKeyNavigationAttached::backtab() const
670 Q_D(const QQuickKeyNavigationAttached);
674 void QQuickKeyNavigationAttached::setBacktab(QQuickItem *i)
676 Q_D(QQuickKeyNavigationAttached);
680 d->backtabSet = true;
681 QQuickKeyNavigationAttached* other =
682 qobject_cast<QQuickKeyNavigationAttached*>(qmlAttachedPropertiesObject<QQuickKeyNavigationAttached>(i));
683 if (other && !other->d_func()->tabSet) {
684 other->d_func()->tab = qobject_cast<QQuickItem*>(parent());
685 emit other->tabChanged();
687 emit backtabChanged();
691 \qmlproperty enumeration QtQuick2::KeyNavigation::priority
693 This property determines whether the keys are processed before
694 or after the attached item's own key handling.
697 \o KeyNavigation.BeforeItem - process the key events before normal
698 item key processing. If the event is used for key navigation, it will be accepted and will not
699 be passed on to the item.
700 \o KeyNavigation.AfterItem (default) - process the key events after normal item key
701 handling. If the item accepts the key event it will not be
702 handled by the KeyNavigation attached property handler.
705 QQuickKeyNavigationAttached::Priority QQuickKeyNavigationAttached::priority() const
707 return m_processPost ? AfterItem : BeforeItem;
710 void QQuickKeyNavigationAttached::setPriority(Priority order)
712 bool processPost = order == AfterItem;
713 if (processPost != m_processPost) {
714 m_processPost = processPost;
715 emit priorityChanged();
719 void QQuickKeyNavigationAttached::keyPressed(QKeyEvent *event, bool post)
721 Q_D(QQuickKeyNavigationAttached);
724 if (post != m_processPost) {
725 QQuickItemKeyFilter::keyPressed(event, post);
730 switch (event->key()) {
732 if (QQuickItem *parentItem = qobject_cast<QQuickItem*>(parent()))
733 mirror = QQuickItemPrivate::get(parentItem)->effectiveLayoutMirror;
734 QQuickItem* leftItem = mirror ? d->right : d->left;
736 setFocusNavigation(leftItem, mirror ? "right" : "left");
741 case Qt::Key_Right: {
742 if (QQuickItem *parentItem = qobject_cast<QQuickItem*>(parent()))
743 mirror = QQuickItemPrivate::get(parentItem)->effectiveLayoutMirror;
744 QQuickItem* rightItem = mirror ? d->left : d->right;
746 setFocusNavigation(rightItem, mirror ? "left" : "right");
753 setFocusNavigation(d->up, "up");
759 setFocusNavigation(d->down, "down");
765 setFocusNavigation(d->tab, "tab");
769 case Qt::Key_Backtab:
771 setFocusNavigation(d->backtab, "backtab");
779 if (!event->isAccepted()) QQuickItemKeyFilter::keyPressed(event, post);
782 void QQuickKeyNavigationAttached::keyReleased(QKeyEvent *event, bool post)
784 Q_D(QQuickKeyNavigationAttached);
787 if (post != m_processPost) {
788 QQuickItemKeyFilter::keyReleased(event, post);
793 switch (event->key()) {
795 if (QQuickItem *parentItem = qobject_cast<QQuickItem*>(parent()))
796 mirror = QQuickItemPrivate::get(parentItem)->effectiveLayoutMirror;
797 if (mirror ? d->right : d->left)
801 if (QQuickItem *parentItem = qobject_cast<QQuickItem*>(parent()))
802 mirror = QQuickItemPrivate::get(parentItem)->effectiveLayoutMirror;
803 if (mirror ? d->left : d->right)
821 case Qt::Key_Backtab:
830 if (!event->isAccepted()) QQuickItemKeyFilter::keyReleased(event, post);
833 void QQuickKeyNavigationAttached::setFocusNavigation(QQuickItem *currentItem, const char *dir)
835 QQuickItem *initialItem = currentItem;
836 bool isNextItem = false;
839 if (currentItem->isVisible() && currentItem->isEnabled()) {
840 currentItem->setFocus(true);
843 qmlAttachedPropertiesObject<QQuickKeyNavigationAttached>(currentItem, false);
845 QQuickItem *tempItem = qvariant_cast<QQuickItem*>(attached->property(dir));
847 currentItem = tempItem;
853 while (currentItem != initialItem && isNextItem);
856 const QQuickKeysAttached::SigMap QQuickKeysAttached::sigMap[] = {
857 { Qt::Key_Left, "leftPressed" },
858 { Qt::Key_Right, "rightPressed" },
859 { Qt::Key_Up, "upPressed" },
860 { Qt::Key_Down, "downPressed" },
861 { Qt::Key_Tab, "tabPressed" },
862 { Qt::Key_Backtab, "backtabPressed" },
863 { Qt::Key_Asterisk, "asteriskPressed" },
864 { Qt::Key_NumberSign, "numberSignPressed" },
865 { Qt::Key_Escape, "escapePressed" },
866 { Qt::Key_Return, "returnPressed" },
867 { Qt::Key_Enter, "enterPressed" },
868 { Qt::Key_Delete, "deletePressed" },
869 { Qt::Key_Space, "spacePressed" },
870 { Qt::Key_Back, "backPressed" },
871 { Qt::Key_Cancel, "cancelPressed" },
872 { Qt::Key_Select, "selectPressed" },
873 { Qt::Key_Yes, "yesPressed" },
874 { Qt::Key_No, "noPressed" },
875 { Qt::Key_Context1, "context1Pressed" },
876 { Qt::Key_Context2, "context2Pressed" },
877 { Qt::Key_Context3, "context3Pressed" },
878 { Qt::Key_Context4, "context4Pressed" },
879 { Qt::Key_Call, "callPressed" },
880 { Qt::Key_Hangup, "hangupPressed" },
881 { Qt::Key_Flip, "flipPressed" },
882 { Qt::Key_Menu, "menuPressed" },
883 { Qt::Key_VolumeUp, "volumeUpPressed" },
884 { Qt::Key_VolumeDown, "volumeDownPressed" },
888 bool QQuickKeysAttachedPrivate::isConnected(const char *signalName)
890 return isSignalConnected(signalIndex(signalName));
894 \qmlclass Keys QQuickKeysAttached
895 \inqmlmodule QtQuick 2
896 \ingroup qml-basic-interaction-elements
897 \brief The Keys attached property provides key handling to Items.
899 All visual primitives support key handling via the Keys
900 attached property. Keys can be handled via the onPressed
901 and onReleased signal properties.
903 The signal properties have a \l KeyEvent parameter, named
904 \e event which contains details of the event. If a key is
905 handled \e event.accepted should be set to true to prevent the
906 event from propagating up the item hierarchy.
908 \section1 Example Usage
910 The following example shows how the general onPressed handler can
911 be used to test for a certain key; in this case, the left cursor
914 \snippet doc/src/snippets/declarative/keys/keys-pressed.qml key item
916 Some keys may alternatively be handled via specific signal properties,
917 for example \e onSelectPressed. These handlers automatically set
918 \e event.accepted to true.
920 \snippet doc/src/snippets/declarative/keys/keys-handler.qml key item
922 See \l{Qt::Key}{Qt.Key} for the list of keyboard codes.
924 \section1 Key Handling Priorities
926 The Keys attached property can be configured to handle key events
927 before or after the item it is attached to. This makes it possible
928 to intercept events in order to override an item's default behavior,
929 or act as a fallback for keys not handled by the item.
931 If \l priority is Keys.BeforeItem (default) the order of key event processing is:
934 \o Items specified in \c forwardTo
935 \o specific key handlers, e.g. onReturnPressed
936 \o onKeyPress, onKeyRelease handlers
937 \o Item specific key handling, e.g. TextInput key handling
941 If priority is Keys.AfterItem the order of key event processing is:
944 \o Item specific key handling, e.g. TextInput key handling
945 \o Items specified in \c forwardTo
946 \o specific key handlers, e.g. onReturnPressed
947 \o onKeyPress, onKeyRelease handlers
951 If the event is accepted during any of the above steps, key
954 \sa KeyEvent, {KeyNavigation}{KeyNavigation attached property}
958 \qmlproperty bool QtQuick2::Keys::enabled
960 This flags enables key handling if true (default); otherwise
961 no key handlers will be called.
965 \qmlproperty enumeration QtQuick2::Keys::priority
967 This property determines whether the keys are processed before
968 or after the attached item's own key handling.
971 \o Keys.BeforeItem (default) - process the key events before normal
972 item key processing. If the event is accepted it will not
973 be passed on to the item.
974 \o Keys.AfterItem - process the key events after normal item key
975 handling. If the item accepts the key event it will not be
976 handled by the Keys attached property handler.
981 \qmlproperty list<Object> QtQuick2::Keys::forwardTo
983 This property provides a way to forward key presses, key releases, and keyboard input
984 coming from input methods to other items. This can be useful when you want
985 one item to handle some keys (e.g. the up and down arrow keys), and another item to
986 handle other keys (e.g. the left and right arrow keys). Once an item that has been
987 forwarded keys accepts the event it is no longer forwarded to items later in the
990 This example forwards key events to two lists:
1001 Keys.forwardTo: [list1, list2]
1008 \qmlsignal QtQuick2::Keys::onPressed(KeyEvent event)
1010 This handler is called when a key has been pressed. The \a event
1011 parameter provides information about the event.
1015 \qmlsignal QtQuick2::Keys::onReleased(KeyEvent event)
1017 This handler is called when a key has been released. The \a event
1018 parameter provides information about the event.
1022 \qmlsignal QtQuick2::Keys::onDigit0Pressed(KeyEvent event)
1024 This handler is called when the digit '0' has been pressed. The \a event
1025 parameter provides information about the event.
1029 \qmlsignal QtQuick2::Keys::onDigit1Pressed(KeyEvent event)
1031 This handler is called when the digit '1' has been pressed. The \a event
1032 parameter provides information about the event.
1036 \qmlsignal QtQuick2::Keys::onDigit2Pressed(KeyEvent event)
1038 This handler is called when the digit '2' has been pressed. The \a event
1039 parameter provides information about the event.
1043 \qmlsignal QtQuick2::Keys::onDigit3Pressed(KeyEvent event)
1045 This handler is called when the digit '3' has been pressed. The \a event
1046 parameter provides information about the event.
1050 \qmlsignal QtQuick2::Keys::onDigit4Pressed(KeyEvent event)
1052 This handler is called when the digit '4' has been pressed. The \a event
1053 parameter provides information about the event.
1057 \qmlsignal QtQuick2::Keys::onDigit5Pressed(KeyEvent event)
1059 This handler is called when the digit '5' has been pressed. The \a event
1060 parameter provides information about the event.
1064 \qmlsignal QtQuick2::Keys::onDigit6Pressed(KeyEvent event)
1066 This handler is called when the digit '6' has been pressed. The \a event
1067 parameter provides information about the event.
1071 \qmlsignal QtQuick2::Keys::onDigit7Pressed(KeyEvent event)
1073 This handler is called when the digit '7' has been pressed. The \a event
1074 parameter provides information about the event.
1078 \qmlsignal QtQuick2::Keys::onDigit8Pressed(KeyEvent event)
1080 This handler is called when the digit '8' has been pressed. The \a event
1081 parameter provides information about the event.
1085 \qmlsignal QtQuick2::Keys::onDigit9Pressed(KeyEvent event)
1087 This handler is called when the digit '9' has been pressed. The \a event
1088 parameter provides information about the event.
1092 \qmlsignal QtQuick2::Keys::onLeftPressed(KeyEvent event)
1094 This handler is called when the Left arrow has been pressed. The \a event
1095 parameter provides information about the event.
1099 \qmlsignal QtQuick2::Keys::onRightPressed(KeyEvent event)
1101 This handler is called when the Right arrow has been pressed. The \a event
1102 parameter provides information about the event.
1106 \qmlsignal QtQuick2::Keys::onUpPressed(KeyEvent event)
1108 This handler is called when the Up arrow has been pressed. The \a event
1109 parameter provides information about the event.
1113 \qmlsignal QtQuick2::Keys::onDownPressed(KeyEvent event)
1115 This handler is called when the Down arrow has been pressed. The \a event
1116 parameter provides information about the event.
1120 \qmlsignal QtQuick2::Keys::onTabPressed(KeyEvent event)
1122 This handler is called when the Tab key has been pressed. The \a event
1123 parameter provides information about the event.
1127 \qmlsignal QtQuick2::Keys::onBacktabPressed(KeyEvent event)
1129 This handler is called when the Shift+Tab key combination (Backtab) has
1130 been pressed. The \a event parameter provides information about the event.
1134 \qmlsignal QtQuick2::Keys::onAsteriskPressed(KeyEvent event)
1136 This handler is called when the Asterisk '*' has been pressed. The \a event
1137 parameter provides information about the event.
1141 \qmlsignal QtQuick2::Keys::onEscapePressed(KeyEvent event)
1143 This handler is called when the Escape key has been pressed. The \a event
1144 parameter provides information about the event.
1148 \qmlsignal QtQuick2::Keys::onReturnPressed(KeyEvent event)
1150 This handler is called when the Return key has been pressed. The \a event
1151 parameter provides information about the event.
1155 \qmlsignal QtQuick2::Keys::onEnterPressed(KeyEvent event)
1157 This handler is called when the Enter key has been pressed. The \a event
1158 parameter provides information about the event.
1162 \qmlsignal QtQuick2::Keys::onDeletePressed(KeyEvent event)
1164 This handler is called when the Delete key has been pressed. The \a event
1165 parameter provides information about the event.
1169 \qmlsignal QtQuick2::Keys::onSpacePressed(KeyEvent event)
1171 This handler is called when the Space key has been pressed. The \a event
1172 parameter provides information about the event.
1176 \qmlsignal QtQuick2::Keys::onBackPressed(KeyEvent event)
1178 This handler is called when the Back key has been pressed. The \a event
1179 parameter provides information about the event.
1183 \qmlsignal QtQuick2::Keys::onCancelPressed(KeyEvent event)
1185 This handler is called when the Cancel key has been pressed. The \a event
1186 parameter provides information about the event.
1190 \qmlsignal QtQuick2::Keys::onSelectPressed(KeyEvent event)
1192 This handler is called when the Select key has been pressed. The \a event
1193 parameter provides information about the event.
1197 \qmlsignal QtQuick2::Keys::onYesPressed(KeyEvent event)
1199 This handler is called when the Yes key has been pressed. The \a event
1200 parameter provides information about the event.
1204 \qmlsignal QtQuick2::Keys::onNoPressed(KeyEvent event)
1206 This handler is called when the No key has been pressed. The \a event
1207 parameter provides information about the event.
1211 \qmlsignal QtQuick2::Keys::onContext1Pressed(KeyEvent event)
1213 This handler is called when the Context1 key has been pressed. The \a event
1214 parameter provides information about the event.
1218 \qmlsignal QtQuick2::Keys::onContext2Pressed(KeyEvent event)
1220 This handler is called when the Context2 key has been pressed. The \a event
1221 parameter provides information about the event.
1225 \qmlsignal QtQuick2::Keys::onContext3Pressed(KeyEvent event)
1227 This handler is called when the Context3 key has been pressed. The \a event
1228 parameter provides information about the event.
1232 \qmlsignal QtQuick2::Keys::onContext4Pressed(KeyEvent event)
1234 This handler is called when the Context4 key has been pressed. The \a event
1235 parameter provides information about the event.
1239 \qmlsignal QtQuick2::Keys::onCallPressed(KeyEvent event)
1241 This handler is called when the Call key has been pressed. The \a event
1242 parameter provides information about the event.
1246 \qmlsignal QtQuick2::Keys::onHangupPressed(KeyEvent event)
1248 This handler is called when the Hangup key has been pressed. The \a event
1249 parameter provides information about the event.
1253 \qmlsignal QtQuick2::Keys::onFlipPressed(KeyEvent event)
1255 This handler is called when the Flip key has been pressed. The \a event
1256 parameter provides information about the event.
1260 \qmlsignal QtQuick2::Keys::onMenuPressed(KeyEvent event)
1262 This handler is called when the Menu key has been pressed. The \a event
1263 parameter provides information about the event.
1267 \qmlsignal QtQuick2::Keys::onVolumeUpPressed(KeyEvent event)
1269 This handler is called when the VolumeUp key has been pressed. The \a event
1270 parameter provides information about the event.
1274 \qmlsignal QtQuick2::Keys::onVolumeDownPressed(KeyEvent event)
1276 This handler is called when the VolumeDown key has been pressed. The \a event
1277 parameter provides information about the event.
1280 QQuickKeysAttached::QQuickKeysAttached(QObject *parent)
1281 : QObject(*(new QQuickKeysAttachedPrivate), parent),
1282 QQuickItemKeyFilter(qobject_cast<QQuickItem*>(parent))
1284 Q_D(QQuickKeysAttached);
1285 m_processPost = false;
1286 d->item = qobject_cast<QQuickItem*>(parent);
1289 QQuickKeysAttached::~QQuickKeysAttached()
1293 QQuickKeysAttached::Priority QQuickKeysAttached::priority() const
1295 return m_processPost ? AfterItem : BeforeItem;
1298 void QQuickKeysAttached::setPriority(Priority order)
1300 bool processPost = order == AfterItem;
1301 if (processPost != m_processPost) {
1302 m_processPost = processPost;
1303 emit priorityChanged();
1307 void QQuickKeysAttached::componentComplete()
1309 Q_D(QQuickKeysAttached);
1311 for (int ii = 0; ii < d->targets.count(); ++ii) {
1312 QQuickItem *targetItem = d->targets.at(ii);
1313 if (targetItem && (targetItem->flags() & QQuickItem::ItemAcceptsInputMethod)) {
1314 d->item->setFlag(QQuickItem::ItemAcceptsInputMethod);
1321 void QQuickKeysAttached::keyPressed(QKeyEvent *event, bool post)
1323 Q_D(QQuickKeysAttached);
1324 if (post != m_processPost || !d->enabled || d->inPress) {
1326 QQuickItemKeyFilter::keyPressed(event, post);
1330 // first process forwards
1331 if (d->item && d->item->canvas()) {
1333 for (int ii = 0; ii < d->targets.count(); ++ii) {
1334 QQuickItem *i = d->targets.at(ii);
1335 if (i && i->isVisible()) {
1336 d->item->canvas()->sendEvent(i, event);
1337 if (event->isAccepted()) {
1346 QQuickKeyEvent ke(*event);
1347 QByteArray keySignal = keyToSignal(event->key());
1348 if (!keySignal.isEmpty()) {
1349 keySignal += "(QQuickKeyEvent*)";
1350 if (d->isConnected(keySignal)) {
1351 // If we specifically handle a key then default to accepted
1352 ke.setAccepted(true);
1353 int idx = QQuickKeysAttached::staticMetaObject.indexOfSignal(keySignal);
1354 metaObject()->method(idx).invoke(this, Qt::DirectConnection, Q_ARG(QQuickKeyEvent*, &ke));
1357 if (!ke.isAccepted())
1359 event->setAccepted(ke.isAccepted());
1361 if (!event->isAccepted()) QQuickItemKeyFilter::keyPressed(event, post);
1364 void QQuickKeysAttached::keyReleased(QKeyEvent *event, bool post)
1366 Q_D(QQuickKeysAttached);
1367 if (post != m_processPost || !d->enabled || d->inRelease) {
1369 QQuickItemKeyFilter::keyReleased(event, post);
1373 if (d->item && d->item->canvas()) {
1374 d->inRelease = true;
1375 for (int ii = 0; ii < d->targets.count(); ++ii) {
1376 QQuickItem *i = d->targets.at(ii);
1377 if (i && i->isVisible()) {
1378 d->item->canvas()->sendEvent(i, event);
1379 if (event->isAccepted()) {
1380 d->inRelease = false;
1385 d->inRelease = false;
1388 QQuickKeyEvent ke(*event);
1390 event->setAccepted(ke.isAccepted());
1392 if (!event->isAccepted()) QQuickItemKeyFilter::keyReleased(event, post);
1395 void QQuickKeysAttached::inputMethodEvent(QInputMethodEvent *event, bool post)
1397 Q_D(QQuickKeysAttached);
1398 if (post == m_processPost && d->item && !d->inIM && d->item->canvas()) {
1400 for (int ii = 0; ii < d->targets.count(); ++ii) {
1401 QQuickItem *i = d->targets.at(ii);
1402 if (i && i->isVisible() && (i->flags() & QQuickItem::ItemAcceptsInputMethod)) {
1403 d->item->canvas()->sendEvent(i, event);
1404 if (event->isAccepted()) {
1413 QQuickItemKeyFilter::inputMethodEvent(event, post);
1416 QVariant QQuickKeysAttached::inputMethodQuery(Qt::InputMethodQuery query) const
1418 Q_D(const QQuickKeysAttached);
1420 for (int ii = 0; ii < d->targets.count(); ++ii) {
1421 QQuickItem *i = d->targets.at(ii);
1422 if (i && i->isVisible() && (i->flags() & QQuickItem::ItemAcceptsInputMethod) && i == d->imeItem) {
1423 //### how robust is i == d->imeItem check?
1424 QVariant v = i->inputMethodQuery(query);
1425 if (v.userType() == QVariant::RectF)
1426 v = d->item->mapRectFromItem(i, v.toRectF()); //### cost?
1431 return QQuickItemKeyFilter::inputMethodQuery(query);
1434 QQuickKeysAttached *QQuickKeysAttached::qmlAttachedProperties(QObject *obj)
1436 return new QQuickKeysAttached(obj);
1440 \qmlclass LayoutMirroring QQuickLayoutMirroringAttached
1441 \inqmlmodule QtQuick 2
1442 \ingroup qml-utility-elements
1443 \brief The LayoutMirroring attached property is used to mirror layout behavior.
1445 The LayoutMirroring attached property is used to horizontally mirror \l {anchor-layout}{Item anchors},
1446 \l{Using QML Positioner and Repeater Items}{positioner} elements (such as \l Row and \l Grid)
1447 and views (such as \l GridView and horizontal \l ListView). Mirroring is a visual change: left
1448 anchors become right anchors, and positioner elements like \l Grid and \l Row reverse the
1449 horizontal layout of child items.
1451 Mirroring is enabled for an item by setting the \l enabled property to true. By default, this
1452 only affects the item itself; setting the \l childrenInherit property to true propagates the mirroring
1453 behavior to all child elements as well. If the \c LayoutMirroring attached property has not been defined
1454 for an item, mirroring is not enabled.
1456 The following example shows mirroring in action. The \l Row below is specified as being anchored
1457 to the left of its parent. However, since mirroring has been enabled, the anchor is horizontally
1458 reversed and it is now anchored to the right. Also, since items in a \l Row are positioned
1459 from left to right by default, they are now positioned from right to left instead, as demonstrated
1460 by the numbering and opacity of the items:
1462 \snippet doc/src/snippets/declarative/layoutmirroring.qml 0
1464 \image layoutmirroring.png
1466 Layout mirroring is useful when it is necessary to support both left-to-right and right-to-left
1467 layout versions of an application to target different language areas. The \l childrenInherit
1468 property allows layout mirroring to be applied without manually setting layout configurations
1469 for every item in an application. Keep in mind, however, that mirroring does not affect any
1470 positioning that is defined by the \l Item \l {Item::}{x} coordinate value, so even with
1471 mirroring enabled, it will often be necessary to apply some layout fixes to support the
1472 desired layout direction. Also, it may be necessary to disable the mirroring of individual
1473 child items (by setting \l {enabled}{LayoutMirroring.enabled} to false for such items) if
1474 mirroring is not the desired behavior, or if the child item already implements mirroring in
1477 See \l {QML Right-to-left User Interfaces} for further details on using \c LayoutMirroring and
1478 other related features to implement right-to-left support for an application.
1482 \qmlproperty bool QtQuick2::LayoutMirroring::enabled
1484 This property holds whether the item's layout is mirrored horizontally. Setting this to true
1485 horizontally reverses \l {anchor-layout}{anchor} settings such that left anchors become right,
1486 and right anchors become left. For \l{Using QML Positioner and Repeater Items}{positioner} elements
1487 (such as \l Row and \l Grid) and view elements (such as \l {GridView}{GridView} and \l {ListView}{ListView})
1488 this also mirrors the horizontal layout direction of the item.
1490 The default value is false.
1494 \qmlproperty bool QtQuick2::LayoutMirroring::childrenInherit
1496 This property holds whether the \l {enabled}{LayoutMirroring.enabled} value for this item
1497 is inherited by its children.
1499 The default value is false.
1503 QQuickLayoutMirroringAttached::QQuickLayoutMirroringAttached(QObject *parent) : QObject(parent), itemPrivate(0)
1505 if (QQuickItem *item = qobject_cast<QQuickItem*>(parent)) {
1506 itemPrivate = QQuickItemPrivate::get(item);
1507 itemPrivate->attachedLayoutDirection = this;
1509 qmlInfo(parent) << tr("LayoutDirection attached property only works with Items");
1512 QQuickLayoutMirroringAttached * QQuickLayoutMirroringAttached::qmlAttachedProperties(QObject *object)
1514 return new QQuickLayoutMirroringAttached(object);
1517 bool QQuickLayoutMirroringAttached::enabled() const
1519 return itemPrivate ? itemPrivate->effectiveLayoutMirror : false;
1522 void QQuickLayoutMirroringAttached::setEnabled(bool enabled)
1527 itemPrivate->isMirrorImplicit = false;
1528 if (enabled != itemPrivate->effectiveLayoutMirror) {
1529 itemPrivate->setLayoutMirror(enabled);
1530 if (itemPrivate->inheritMirrorFromItem)
1531 itemPrivate->resolveLayoutMirror();
1535 void QQuickLayoutMirroringAttached::resetEnabled()
1537 if (itemPrivate && !itemPrivate->isMirrorImplicit) {
1538 itemPrivate->isMirrorImplicit = true;
1539 itemPrivate->resolveLayoutMirror();
1543 bool QQuickLayoutMirroringAttached::childrenInherit() const
1545 return itemPrivate ? itemPrivate->inheritMirrorFromItem : false;
1548 void QQuickLayoutMirroringAttached::setChildrenInherit(bool childrenInherit) {
1549 if (itemPrivate && childrenInherit != itemPrivate->inheritMirrorFromItem) {
1550 itemPrivate->inheritMirrorFromItem = childrenInherit;
1551 itemPrivate->resolveLayoutMirror();
1552 childrenInheritChanged();
1556 void QQuickItemPrivate::resolveLayoutMirror()
1559 if (QQuickItem *parentItem = q->parentItem()) {
1560 QQuickItemPrivate *parentPrivate = QQuickItemPrivate::get(parentItem);
1561 setImplicitLayoutMirror(parentPrivate->inheritedLayoutMirror, parentPrivate->inheritMirrorFromParent);
1563 setImplicitLayoutMirror(isMirrorImplicit ? false : effectiveLayoutMirror, inheritMirrorFromItem);
1567 void QQuickItemPrivate::setImplicitLayoutMirror(bool mirror, bool inherit)
1569 inherit = inherit || inheritMirrorFromItem;
1570 if (!isMirrorImplicit && inheritMirrorFromItem)
1571 mirror = effectiveLayoutMirror;
1572 if (mirror == inheritedLayoutMirror && inherit == inheritMirrorFromParent)
1575 inheritMirrorFromParent = inherit;
1576 inheritedLayoutMirror = inheritMirrorFromParent ? mirror : false;
1578 if (isMirrorImplicit)
1579 setLayoutMirror(inherit ? inheritedLayoutMirror : false);
1580 for (int i = 0; i < childItems.count(); ++i) {
1581 if (QQuickItem *child = qobject_cast<QQuickItem *>(childItems.at(i))) {
1582 QQuickItemPrivate *childPrivate = QQuickItemPrivate::get(child);
1583 childPrivate->setImplicitLayoutMirror(inheritedLayoutMirror, inheritMirrorFromParent);
1588 void QQuickItemPrivate::setLayoutMirror(bool mirror)
1590 if (mirror != effectiveLayoutMirror) {
1591 effectiveLayoutMirror = mirror;
1593 QQuickAnchorsPrivate *anchor_d = QQuickAnchorsPrivate::get(_anchors);
1594 anchor_d->fillChanged();
1595 anchor_d->centerInChanged();
1596 anchor_d->updateHorizontalAnchors();
1597 emit _anchors->mirroredChanged();
1600 if (attachedLayoutDirection) {
1601 emit attachedLayoutDirection->enabledChanged();
1608 \brief The QQuickItem class provides the most basic of all visual items in QML.
1612 All visual items in Qt Declarative inherit from QQuickItem. Although QQuickItem
1613 has no visual appearance, it defines all the properties that are
1614 common across visual items - such as the x and y position, the
1615 width and height, \l {anchor-layout}{anchoring} and key handling.
1617 You can subclass QQuickItem to provide your own custom visual item that inherits
1618 these features. Note that, because it does not draw anything, QQuickItem sets the
1619 QGraphicsItem::ItemHasNoContents flag. If you subclass QQuickItem to create a visual
1620 item, you will need to unset this flag.
1625 \qmlclass Item QQuickItem
1626 \inqmlmodule QtQuick 2
1627 \ingroup qml-basic-visual-elements
1628 \brief The Item is the most basic of all visual items in QML.
1630 All visual items in Qt Declarative inherit from Item. Although Item
1631 has no visual appearance, it defines all the properties that are
1632 common across visual items - such as the x and y position, the
1633 width and height, \l {anchor-layout}{anchoring} and key handling.
1635 Item is also useful for grouping items together.
1652 fillMode: Image.Tile
1659 \section1 Key Handling
1661 Key handling is available to all Item-based visual elements via the \l {Keys}{Keys}
1662 attached property. The \e Keys attached property provides basic handlers such
1663 as \l {Keys::onPressed}{onPressed} and \l {Keys::onReleased}{onReleased},
1664 as well as handlers for specific keys, such as
1665 \l {Keys::onCancelPressed}{onCancelPressed}. The example below
1666 assigns \l {qmlfocus}{focus} to the item and handles
1667 the Left key via the general \e onPressed handler and the Select key via the
1668 onSelectPressed handler:
1674 if (event.key == Qt.Key_Left) {
1675 console.log("move left");
1676 event.accepted = true;
1679 Keys.onSelectPressed: console.log("Selected");
1683 See the \l {Keys}{Keys} attached property for detailed documentation.
1685 \section1 Layout Mirroring
1687 Item layouts can be mirrored using the \l {LayoutMirroring}{LayoutMirroring} attached property.
1692 \fn void QQuickItem::childrenRectChanged(const QRectF &)
1697 \fn void QQuickItem::baselineOffsetChanged(qreal)
1702 \fn void QQuickItem::stateChanged(const QString &state)
1707 \fn void QQuickItem::parentChanged(QQuickItem *)
1712 \fn void QQuickItem::smoothChanged(bool)
1717 \fn void QQuickItem::clipChanged(bool)
1721 /*! \fn void QQuickItem::transformOriginChanged(TransformOrigin)
1726 \fn void QQuickItem::focusChanged(bool)
1731 \fn void QQuickItem::activeFocusChanged(bool)
1735 \fn QQuickItem::QQuickItem(QQuickItem *parent)
1737 Constructs a QQuickItem with the given \a parent.
1739 QQuickItem::QQuickItem(QQuickItem* parent)
1740 : QObject(*(new QQuickItemPrivate), parent)
1748 QQuickItem::QQuickItem(QQuickItemPrivate &dd, QQuickItem *parent)
1749 : QObject(dd, parent)
1756 static int qt_item_count = 0;
1758 static void qt_print_item_count()
1760 qDebug("Number of leaked items: %i", qt_item_count);
1766 Destroys the QQuickItem.
1768 QQuickItem::~QQuickItem()
1772 if (qt_item_count < 0)
1773 qDebug("Item destroyed after qt_print_item_count() was called.");
1780 else if (d->canvas && d->itemNodeInstance)
1781 QQuickCanvasPrivate::get(d->canvas)->cleanup(d->itemNodeInstance); // cleanup root
1782 // XXX todo - optimize
1783 while (!d->childItems.isEmpty())
1784 d->childItems.first()->setParentItem(0);
1786 for (int ii = 0; ii < d->changeListeners.count(); ++ii) {
1787 QQuickAnchorsPrivate *anchor = d->changeListeners.at(ii).listener->anchorPrivate();
1789 anchor->clearItem(this);
1793 update item anchors that depended on us unless they are our child (and will also be destroyed),
1794 or our sibling, and our parent is also being destroyed.
1796 for (int ii = 0; ii < d->changeListeners.count(); ++ii) {
1797 QQuickAnchorsPrivate *anchor = d->changeListeners.at(ii).listener->anchorPrivate();
1798 if (anchor && anchor->item && anchor->item->parentItem() && anchor->item->parentItem() != this)
1802 for (int ii = 0; ii < d->changeListeners.count(); ++ii) {
1803 const QQuickItemPrivate::ChangeListener &change = d->changeListeners.at(ii);
1804 if (change.types & QQuickItemPrivate::Destroyed)
1805 change.listener->itemDestroyed(this);
1807 d->changeListeners.clear();
1808 delete d->_anchorLines; d->_anchorLines = 0;
1809 delete d->_anchors; d->_anchors = 0;
1810 delete d->_stateGroup; d->_stateGroup = 0;
1811 delete d->_contents; d->_contents = 0;
1815 \qmlproperty enumeration QtQuick2::Item::transformOrigin
1816 This property holds the origin point around which scale and rotation transform.
1818 Nine transform origins are available, as shown in the image below.
1820 \image declarative-transformorigin.png
1822 This example rotates an image around its bottom-right corner.
1825 source: "myimage.png"
1826 transformOrigin: Item.BottomRight
1831 The default transform origin is \c Item.Center.
1833 To set an arbitrary transform origin point use the \l Scale or \l Rotation
1838 \qmlproperty Item QtQuick2::Item::parent
1839 This property holds the parent of the item.
1843 \property QQuickItem::parent
1844 This property holds the parent of the item.
1846 void QQuickItem::setParentItem(QQuickItem *parentItem)
1849 if (parentItem == d->parentItem)
1852 d->removeFromDirtyList();
1854 QQuickItem *oldParentItem = d->parentItem;
1855 QQuickItem *scopeFocusedItem = 0;
1857 if (oldParentItem) {
1858 QQuickItemPrivate *op = QQuickItemPrivate::get(oldParentItem);
1860 QQuickItem *scopeItem = 0;
1862 if (d->canvas && hasFocus()) {
1863 scopeItem = oldParentItem;
1864 while (!scopeItem->isFocusScope()) scopeItem = scopeItem->parentItem();
1865 scopeFocusedItem = this;
1866 } else if (d->canvas && !isFocusScope() && d->subFocusItem) {
1867 scopeItem = oldParentItem;
1868 while (!scopeItem->isFocusScope()) scopeItem = scopeItem->parentItem();
1869 scopeFocusedItem = d->subFocusItem;
1872 if (scopeFocusedItem)
1873 QQuickCanvasPrivate::get(d->canvas)->clearFocusInScope(scopeItem, scopeFocusedItem,
1874 QQuickCanvasPrivate::DontChangeFocusProperty);
1876 op->removeChild(this);
1879 d->parentItem = parentItem;
1881 QQuickCanvas *parentCanvas = parentItem?QQuickItemPrivate::get(parentItem)->canvas:0;
1882 if (d->canvas != parentCanvas) {
1883 QQuickItemPrivate::InitializationState initState;
1885 d->initCanvas(&initState, parentCanvas);
1888 d->dirty(QQuickItemPrivate::ParentChanged);
1891 QQuickItemPrivate::get(d->parentItem)->addChild(this);
1893 d->setEffectiveVisibleRecur(d->calcEffectiveVisible());
1894 d->setEffectiveEnableRecur(d->calcEffectiveEnable());
1896 if (scopeFocusedItem && d->parentItem && d->canvas) {
1897 // We need to test whether this item becomes scope focused
1898 QQuickItem *scopeItem = 0;
1899 scopeItem = d->parentItem;
1900 while (!scopeItem->isFocusScope()) scopeItem = scopeItem->parentItem();
1902 if (scopeItem->scopedFocusItem()) {
1903 QQuickItemPrivate::get(scopeFocusedItem)->focus = false;
1904 emit scopeFocusedItem->focusChanged(false);
1906 QQuickCanvasPrivate::get(d->canvas)->setFocusInScope(scopeItem, scopeFocusedItem,
1907 QQuickCanvasPrivate::DontChangeFocusProperty);
1911 d->resolveLayoutMirror();
1913 d->itemChange(ItemParentHasChanged, d->parentItem);
1915 d->parentNotifier.notify();
1916 emit parentChanged(d->parentItem);
1919 void QQuickItem::stackBefore(const QQuickItem *sibling)
1922 if (!sibling || sibling == this || !d->parentItem || d->parentItem != QQuickItemPrivate::get(sibling)->parentItem) {
1923 qWarning("QQuickItem::stackBefore: Cannot stack before %p, which must be a sibling", sibling);
1927 QQuickItemPrivate *parentPrivate = QQuickItemPrivate::get(d->parentItem);
1929 int myIndex = parentPrivate->childItems.indexOf(this);
1930 int siblingIndex = parentPrivate->childItems.indexOf(const_cast<QQuickItem *>(sibling));
1932 Q_ASSERT(myIndex != -1 && siblingIndex != -1);
1934 if (myIndex == siblingIndex - 1)
1937 parentPrivate->childItems.removeAt(myIndex);
1939 if (myIndex < siblingIndex) --siblingIndex;
1941 parentPrivate->childItems.insert(siblingIndex, this);
1943 parentPrivate->dirty(QQuickItemPrivate::ChildrenStackingChanged);
1944 parentPrivate->markSortedChildrenDirty(this);
1946 for (int ii = qMin(siblingIndex, myIndex); ii < parentPrivate->childItems.count(); ++ii)
1947 QQuickItemPrivate::get(parentPrivate->childItems.at(ii))->siblingOrderChanged();
1950 void QQuickItem::stackAfter(const QQuickItem *sibling)
1953 if (!sibling || sibling == this || !d->parentItem || d->parentItem != QQuickItemPrivate::get(sibling)->parentItem) {
1954 qWarning("QQuickItem::stackAfter: Cannot stack after %p, which must be a sibling", sibling);
1958 QQuickItemPrivate *parentPrivate = QQuickItemPrivate::get(d->parentItem);
1960 int myIndex = parentPrivate->childItems.indexOf(this);
1961 int siblingIndex = parentPrivate->childItems.indexOf(const_cast<QQuickItem *>(sibling));
1963 Q_ASSERT(myIndex != -1 && siblingIndex != -1);
1965 if (myIndex == siblingIndex + 1)
1968 parentPrivate->childItems.removeAt(myIndex);
1970 if (myIndex < siblingIndex) --siblingIndex;
1972 parentPrivate->childItems.insert(siblingIndex + 1, this);
1974 parentPrivate->dirty(QQuickItemPrivate::ChildrenStackingChanged);
1975 parentPrivate->markSortedChildrenDirty(this);
1977 for (int ii = qMin(myIndex, siblingIndex + 1); ii < parentPrivate->childItems.count(); ++ii)
1978 QQuickItemPrivate::get(parentPrivate->childItems.at(ii))->siblingOrderChanged();
1982 Returns the QQuickItem parent of this item.
1984 QQuickItem *QQuickItem::parentItem() const
1986 Q_D(const QQuickItem);
1987 return d->parentItem;
1990 QSGEngine *QQuickItem::sceneGraphEngine() const
1992 return canvas()->sceneGraphEngine();
1995 QQuickCanvas *QQuickItem::canvas() const
1997 Q_D(const QQuickItem);
2001 static bool itemZOrder_sort(QQuickItem *lhs, QQuickItem *rhs)
2003 return lhs->z() < rhs->z();
2006 QList<QQuickItem *> QQuickItemPrivate::paintOrderChildItems() const
2008 if (sortedChildItems)
2009 return *sortedChildItems;
2011 // If none of the items have set Z then the paint order list is the same as
2012 // the childItems list. This is by far the most common case.
2014 for (int i = 0; i < childItems.count(); ++i) {
2015 if (QQuickItemPrivate::get(childItems.at(i))->z != 0.) {
2021 sortedChildItems = new QList<QQuickItem*>(childItems);
2022 qStableSort(sortedChildItems->begin(), sortedChildItems->end(), itemZOrder_sort);
2023 return *sortedChildItems;
2026 sortedChildItems = const_cast<QList<QQuickItem*>*>(&childItems);
2031 void QQuickItemPrivate::addChild(QQuickItem *child)
2035 Q_ASSERT(!childItems.contains(child));
2037 childItems.append(child);
2039 markSortedChildrenDirty(child);
2040 dirty(QQuickItemPrivate::ChildrenChanged);
2042 itemChange(QQuickItem::ItemChildAddedChange, child);
2044 emit q->childrenChanged();
2047 void QQuickItemPrivate::removeChild(QQuickItem *child)
2052 Q_ASSERT(childItems.contains(child));
2053 childItems.removeOne(child);
2054 Q_ASSERT(!childItems.contains(child));
2056 markSortedChildrenDirty(child);
2057 dirty(QQuickItemPrivate::ChildrenChanged);
2059 itemChange(QQuickItem::ItemChildRemovedChange, child);
2061 emit q->childrenChanged();
2064 void QQuickItemPrivate::InitializationState::clear()
2069 void QQuickItemPrivate::InitializationState::clear(QQuickItem *fs)
2074 QQuickItem *QQuickItemPrivate::InitializationState::getFocusScope(QQuickItem *item)
2077 QQuickItem *fs = item->parentItem();
2078 while (!fs->isFocusScope())
2079 fs = fs->parentItem();
2085 void QQuickItemPrivate::initCanvas(InitializationState *state, QQuickCanvas *c)
2090 removeFromDirtyList();
2091 QQuickCanvasPrivate *c = QQuickCanvasPrivate::get(canvas);
2092 if (polishScheduled)
2093 c->itemsToPolish.remove(q);
2094 if (c->mouseGrabberItem == q)
2095 c->mouseGrabberItem = 0;
2097 c->hoverItems.removeAll(q);
2098 if (itemNodeInstance)
2099 c->cleanup(itemNodeInstance);
2104 if (canvas && polishScheduled)
2105 QQuickCanvasPrivate::get(canvas)->itemsToPolish.insert(q);
2107 itemNodeInstance = 0;
2113 beforePaintNode = 0;
2115 InitializationState _dummy;
2116 InitializationState *childState = state;
2118 if (c && q->isFocusScope()) {
2120 childState = &_dummy;
2123 for (int ii = 0; ii < childItems.count(); ++ii) {
2124 QQuickItem *child = childItems.at(ii);
2125 QQuickItemPrivate::get(child)->initCanvas(childState, c);
2130 if (state->getFocusScope(q)->scopedFocusItem()) {
2132 emit q->focusChanged(false);
2134 QQuickCanvasPrivate::get(canvas)->setFocusInScope(state->getFocusScope(q), q);
2141 screenAttached->canvasChanged(c);
2142 itemChange(QQuickItem::ItemSceneChange, c);
2146 Returns a transform that maps points from canvas space into item space.
2148 QTransform QQuickItemPrivate::canvasToItemTransform() const
2150 // XXX todo - optimize
2151 return itemToCanvasTransform().inverted();
2155 Returns a transform that maps points from item space into canvas space.
2157 QTransform QQuickItemPrivate::itemToCanvasTransform() const
2160 QTransform rv = parentItem?QQuickItemPrivate::get(parentItem)->itemToCanvasTransform():QTransform();
2161 itemToParentTransform(rv);
2166 Motifies \a t with this items local transform relative to its parent.
2168 void QQuickItemPrivate::itemToParentTransform(QTransform &t) const
2173 if (!transforms.isEmpty()) {
2175 for (int ii = transforms.count() - 1; ii >= 0; --ii)
2176 transforms.at(ii)->applyTo(&m);
2177 t = m.toTransform();
2180 if (scale != 1. || rotation != 0.) {
2181 QPointF tp = computeTransformOrigin();
2182 t.translate(tp.x(), tp.y());
2183 t.scale(scale, scale);
2185 t.translate(-tp.x(), -tp.y());
2191 \qmlproperty real QtQuick2::Item::childrenRect.x
2192 \qmlproperty real QtQuick2::Item::childrenRect.y
2193 \qmlproperty real QtQuick2::Item::childrenRect.width
2194 \qmlproperty real QtQuick2::Item::childrenRect.height
2196 The childrenRect properties allow an item access to the geometry of its
2197 children. This property is useful if you have an item that needs to be
2198 sized to fit its children.
2203 \qmlproperty list<Item> QtQuick2::Item::children
2204 \qmlproperty list<Object> QtQuick2::Item::resources
2206 The children property contains the list of visual children of this item.
2207 The resources property contains non-visual resources that you want to
2210 Generally you can rely on Item's default property to handle all this for
2211 you, but it can come in handy in some cases.
2230 Returns true if construction of the QML component is complete; otherwise
2233 It is often desirable to delay some processing until the component is
2236 \sa componentComplete()
2238 bool QQuickItem::isComponentComplete() const
2240 Q_D(const QQuickItem);
2241 return d->componentComplete;
2244 QQuickItemPrivate::QQuickItemPrivate()
2245 : _anchors(0), _contents(0), baselineOffset(0), _anchorLines(0), _stateGroup(0), origin(QQuickItem::Center),
2247 flags(0), widthValid(false), heightValid(false), componentComplete(true),
2248 keepMouse(false), keepTouch(false), hoverEnabled(false), smooth(false), focus(false), activeFocus(false), notifiedFocus(false),
2249 notifiedActiveFocus(false), filtersChildMouseEvents(false), explicitVisible(true),
2250 effectiveVisible(true), explicitEnable(true), effectiveEnable(true), polishScheduled(false),
2251 inheritedLayoutMirror(false), effectiveLayoutMirror(false), isMirrorImplicit(true),
2252 inheritMirrorFromParent(false), inheritMirrorFromItem(false), childrenDoNotOverlap(false),
2254 canvas(0), parentItem(0), sortedChildItems(&childItems),
2258 x(0), y(0), width(0), height(0), implicitWidth(0), implicitHeight(0),
2259 z(0), scale(1), rotation(0), opacity(1),
2261 attachedLayoutDirection(0), acceptedMouseButtons(0),
2262 imHints(Qt::ImhMultiLine),
2266 dirtyAttributes(0), nextDirtyItem(0), prevDirtyItem(0),
2268 itemNodeInstance(0), opacityNode(0), clipNode(0), rootNode(0), groupNode(0), paintNode(0)
2269 , beforePaintNode(0), effectRefCount(0), hideRefCount(0)
2274 QQuickItemPrivate::~QQuickItemPrivate()
2276 if (sortedChildItems != &childItems)
2277 delete sortedChildItems;
2280 void QQuickItemPrivate::init(QQuickItem *parent)
2284 static bool atexit_registered = false;
2285 if (!atexit_registered) {
2286 atexit(qt_print_item_count);
2287 atexit_registered = true;
2292 baselineOffset.invalidate();
2295 q->setParentItem(parent);
2296 QQuickItemPrivate *parentPrivate = QQuickItemPrivate::get(parent);
2297 setImplicitLayoutMirror(parentPrivate->inheritedLayoutMirror, parentPrivate->inheritMirrorFromParent);
2301 void QQuickItemPrivate::data_append(QDeclarativeListProperty<QObject> *prop, QObject *o)
2306 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2308 // This test is measurably (albeit only slightly) faster than qobject_cast<>()
2309 const QMetaObject *mo = o->metaObject();
2310 while (mo && mo != &QQuickItem::staticMetaObject) {
2311 mo = mo->d.superdata;
2315 QQuickItem *item = static_cast<QQuickItem *>(o);
2316 item->setParentItem(that);
2318 if (o->inherits("QGraphicsItem"))
2319 qWarning("Cannot add a QtQuick 1.0 item (%s) into a QtQuick 2.0 scene!", o->metaObject()->className());
2321 // XXX todo - do we really want this behavior?
2327 \qmlproperty list<Object> QtQuick2::Item::data
2330 The data property allows you to freely mix visual children and resources
2331 in an item. If you assign a visual item to the data list it becomes
2332 a child and if you assign any other object type, it is added as a resource.
2356 data is a behind-the-scenes property: you should never need to explicitly
2360 int QQuickItemPrivate::data_count(QDeclarativeListProperty<QObject> *prop)
2367 QObject *QQuickItemPrivate::data_at(QDeclarativeListProperty<QObject> *prop, int i)
2375 void QQuickItemPrivate::data_clear(QDeclarativeListProperty<QObject> *prop)
2381 QObject *QQuickItemPrivate::resources_at(QDeclarativeListProperty<QObject> *prop, int index)
2383 const QObjectList children = prop->object->children();
2384 if (index < children.count())
2385 return children.at(index);
2390 void QQuickItemPrivate::resources_append(QDeclarativeListProperty<QObject> *prop, QObject *o)
2392 // XXX todo - do we really want this behavior?
2393 o->setParent(prop->object);
2396 int QQuickItemPrivate::resources_count(QDeclarativeListProperty<QObject> *prop)
2398 return prop->object->children().count();
2401 void QQuickItemPrivate::resources_clear(QDeclarativeListProperty<QObject> *prop)
2403 // XXX todo - do we really want this behavior?
2404 const QObjectList children = prop->object->children();
2405 for (int index = 0; index < children.count(); index++)
2406 children.at(index)->setParent(0);
2409 QQuickItem *QQuickItemPrivate::children_at(QDeclarativeListProperty<QQuickItem> *prop, int index)
2411 QQuickItemPrivate *p = QQuickItemPrivate::get(static_cast<QQuickItem *>(prop->object));
2412 if (index >= p->childItems.count() || index < 0)
2415 return p->childItems.at(index);
2418 void QQuickItemPrivate::children_append(QDeclarativeListProperty<QQuickItem> *prop, QQuickItem *o)
2423 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2424 if (o->parentItem() == that)
2425 o->setParentItem(0);
2427 o->setParentItem(that);
2430 int QQuickItemPrivate::children_count(QDeclarativeListProperty<QQuickItem> *prop)
2432 QQuickItemPrivate *p = QQuickItemPrivate::get(static_cast<QQuickItem *>(prop->object));
2433 return p->childItems.count();
2436 void QQuickItemPrivate::children_clear(QDeclarativeListProperty<QQuickItem> *prop)
2438 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2439 QQuickItemPrivate *p = QQuickItemPrivate::get(that);
2440 while (!p->childItems.isEmpty())
2441 p->childItems.at(0)->setParentItem(0);
2444 int QQuickItemPrivate::transform_count(QDeclarativeListProperty<QQuickTransform> *prop)
2446 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2447 return QQuickItemPrivate::get(that)->transforms.count();
2450 void QQuickTransform::appendToItem(QQuickItem *item)
2452 Q_D(QQuickTransform);
2456 QQuickItemPrivate *p = QQuickItemPrivate::get(item);
2458 if (!d->items.isEmpty() && !p->transforms.isEmpty() && p->transforms.contains(this)) {
2459 p->transforms.removeOne(this);
2460 p->transforms.append(this);
2462 p->transforms.append(this);
2463 d->items.append(item);
2466 p->dirty(QQuickItemPrivate::Transform);
2469 void QQuickTransform::prependToItem(QQuickItem *item)
2471 Q_D(QQuickTransform);
2475 QQuickItemPrivate *p = QQuickItemPrivate::get(item);
2477 if (!d->items.isEmpty() && !p->transforms.isEmpty() && p->transforms.contains(this)) {
2478 p->transforms.removeOne(this);
2479 p->transforms.prepend(this);
2481 p->transforms.prepend(this);
2482 d->items.append(item);
2485 p->dirty(QQuickItemPrivate::Transform);
2488 void QQuickItemPrivate::transform_append(QDeclarativeListProperty<QQuickTransform> *prop, QQuickTransform *transform)
2493 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2494 transform->appendToItem(that);
2497 QQuickTransform *QQuickItemPrivate::transform_at(QDeclarativeListProperty<QQuickTransform> *prop, int idx)
2499 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2500 QQuickItemPrivate *p = QQuickItemPrivate::get(that);
2502 if (idx < 0 || idx >= p->transforms.count())
2505 return p->transforms.at(idx);
2508 void QQuickItemPrivate::transform_clear(QDeclarativeListProperty<QQuickTransform> *prop)
2510 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2511 QQuickItemPrivate *p = QQuickItemPrivate::get(that);
2513 for (int ii = 0; ii < p->transforms.count(); ++ii) {
2514 QQuickTransform *t = p->transforms.at(ii);
2515 QQuickTransformPrivate *tp = QQuickTransformPrivate::get(t);
2516 tp->items.removeOne(that);
2519 p->transforms.clear();
2521 p->dirty(QQuickItemPrivate::Transform);
2525 \property QQuickItem::childrenRect
2526 \brief The geometry of an item's children.
2528 This property holds the (collective) position and size of the item's children.
2532 \qmlproperty real QtQuick2::Item::x
2533 \qmlproperty real QtQuick2::Item::y
2534 \qmlproperty real QtQuick2::Item::width
2535 \qmlproperty real QtQuick2::Item::height
2537 Defines the item's position and size relative to its parent.
2540 Item { x: 100; y: 100; width: 100; height: 100 }
2545 \qmlproperty real QtQuick2::Item::z
2547 Sets the stacking order of sibling items. By default the stacking order is 0.
2549 Items with a higher stacking value are drawn on top of siblings with a
2550 lower stacking order. Items with the same stacking value are drawn
2551 bottom up in the order they appear. Items with a negative stacking
2552 value are drawn under their parent's content.
2554 The following example shows the various effects of stacking order.
2558 \o \image declarative-item_stacking1.png
2559 \o Same \c z - later children above earlier children:
2564 width: 100; height: 100
2568 x: 50; y: 50; width: 100; height: 100
2573 \o \image declarative-item_stacking2.png
2574 \o Higher \c z on top:
2580 width: 100; height: 100
2584 x: 50; y: 50; width: 100; height: 100
2589 \o \image declarative-item_stacking3.png
2590 \o Same \c z - children above parents:
2595 width: 100; height: 100
2598 x: 50; y: 50; width: 100; height: 100
2604 \o \image declarative-item_stacking4.png
2605 \o Lower \c z below:
2610 width: 100; height: 100
2614 x: 50; y: 50; width: 100; height: 100
2623 \qmlproperty bool QtQuick2::Item::visible
2625 This property holds whether the item is visible. By default this is true.
2627 Setting this property directly affects the \c visible value of child
2628 items. When set to \c false, the \c visible values of all child items also
2629 become \c false. When set to \c true, the \c visible values of child items
2630 are returned to \c true, unless they have explicitly been set to \c false.
2632 (Because of this flow-on behavior, using the \c visible property may not
2633 have the intended effect if a property binding should only respond to
2634 explicit property changes. In such cases it may be better to use the
2635 \l opacity property instead.)
2637 Setting this property to \c false automatically causes \l focus to be set
2638 to \c false, and this item will longer receive mouse and keyboard events.
2639 (In contrast, setting the \l opacity to 0 does not affect the \l focus
2640 property and the receiving of key events.)
2642 \note This property's value is only affected by changes to this property or
2643 the parent's \c visible property. It does not change, for example, if this
2644 item moves off-screen, or if the \l opacity changes to 0.
2649 \qmlproperty AnchorLine QtQuick2::Item::anchors.top
2650 \qmlproperty AnchorLine QtQuick2::Item::anchors.bottom
2651 \qmlproperty AnchorLine QtQuick2::Item::anchors.left
2652 \qmlproperty AnchorLine QtQuick2::Item::anchors.right
2653 \qmlproperty AnchorLine QtQuick2::Item::anchors.horizontalCenter
2654 \qmlproperty AnchorLine QtQuick2::Item::anchors.verticalCenter
2655 \qmlproperty AnchorLine QtQuick2::Item::anchors.baseline
2657 \qmlproperty Item QtQuick2::Item::anchors.fill
2658 \qmlproperty Item QtQuick2::Item::anchors.centerIn
2660 \qmlproperty real QtQuick2::Item::anchors.margins
2661 \qmlproperty real QtQuick2::Item::anchors.topMargin
2662 \qmlproperty real QtQuick2::Item::anchors.bottomMargin
2663 \qmlproperty real QtQuick2::Item::anchors.leftMargin
2664 \qmlproperty real QtQuick2::Item::anchors.rightMargin
2665 \qmlproperty real QtQuick2::Item::anchors.horizontalCenterOffset
2666 \qmlproperty real QtQuick2::Item::anchors.verticalCenterOffset
2667 \qmlproperty real QtQuick2::Item::anchors.baselineOffset
2669 \qmlproperty bool QtQuick2::Item::anchors.mirrored
2671 Anchors provide a way to position an item by specifying its
2672 relationship with other items.
2674 Margins apply to top, bottom, left, right, and fill anchors.
2675 The \c anchors.margins property can be used to set all of the various margins at once, to the same value.
2676 Note that margins are anchor-specific and are not applied if an item does not
2679 Offsets apply for horizontal center, vertical center, and baseline anchors.
2683 \o \image declarative-anchors_example.png
2684 \o Text anchored to Image, horizontally centered and vertically below, with a margin.
2693 anchors.horizontalCenter: pic.horizontalCenter
2694 anchors.top: pic.bottom
2695 anchors.topMargin: 5
2701 \o \image declarative-anchors_example2.png
2703 Left of Text anchored to right of Image, with a margin. The y
2704 property of both defaults to 0.
2714 anchors.left: pic.right
2715 anchors.leftMargin: 5
2722 \c anchors.fill provides a convenient way for one item to have the
2723 same geometry as another item, and is equivalent to connecting all
2724 four directional anchors.
2726 To clear an anchor value, set it to \c undefined.
2728 \c anchors.mirrored returns true it the layout has been \l {LayoutMirroring}{mirrored}.
2730 \note You can only anchor an item to siblings or a parent.
2732 For more information see \l {anchor-layout}{Anchor Layouts}.
2736 \property QQuickItem::baselineOffset
2737 \brief The position of the item's baseline in local coordinates.
2739 The baseline of a \l Text item is the imaginary line on which the text
2740 sits. Controls containing text usually set their baseline to the
2741 baseline of their text.
2743 For non-text items, a default baseline offset of 0 is used.
2745 QQuickAnchors *QQuickItemPrivate::anchors() const
2748 Q_Q(const QQuickItem);
2749 _anchors = new QQuickAnchors(const_cast<QQuickItem *>(q));
2750 if (!componentComplete)
2751 _anchors->classBegin();
2756 QQuickItemPrivate::AnchorLines *QQuickItemPrivate::anchorLines() const
2758 Q_Q(const QQuickItem);
2759 if (!_anchorLines) _anchorLines =
2760 new AnchorLines(const_cast<QQuickItem *>(q));
2761 return _anchorLines;
2764 void QQuickItemPrivate::siblingOrderChanged()
2767 for (int ii = 0; ii < changeListeners.count(); ++ii) {
2768 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
2769 if (change.types & QQuickItemPrivate::SiblingOrder) {
2770 change.listener->itemSiblingOrderChanged(q);
2775 QDeclarativeListProperty<QObject> QQuickItemPrivate::data()
2777 return QDeclarativeListProperty<QObject>(q_func(), 0, QQuickItemPrivate::data_append,
2778 QQuickItemPrivate::data_count,
2779 QQuickItemPrivate::data_at,
2780 QQuickItemPrivate::data_clear);
2783 QRectF QQuickItem::childrenRect()
2786 if (!d->_contents) {
2787 d->_contents = new QQuickContents(this);
2788 if (d->componentComplete)
2789 d->_contents->complete();
2791 return d->_contents->rectF();
2794 QList<QQuickItem *> QQuickItem::childItems() const
2796 Q_D(const QQuickItem);
2797 return d->childItems;
2800 bool QQuickItem::clip() const
2802 return flags() & ItemClipsChildrenToShape;
2805 void QQuickItem::setClip(bool c)
2810 setFlag(ItemClipsChildrenToShape, c);
2812 emit clipChanged(c);
2817 This function is called to handle this item's changes in
2818 geometry from \a oldGeometry to \a newGeometry. If the two
2819 geometries are the same, it doesn't do anything.
2821 void QQuickItem::geometryChanged(const QRectF &newGeometry, const QRectF &oldGeometry)
2826 QQuickAnchorsPrivate::get(d->_anchors)->updateMe();
2828 bool xChange = (newGeometry.x() != oldGeometry.x());
2829 bool yChange = (newGeometry.y() != oldGeometry.y());
2830 bool widthChange = (newGeometry.width() != oldGeometry.width());
2831 bool heightChange = (newGeometry.height() != oldGeometry.height());
2833 for (int ii = 0; ii < d->changeListeners.count(); ++ii) {
2834 const QQuickItemPrivate::ChangeListener &change = d->changeListeners.at(ii);
2835 if (change.types & QQuickItemPrivate::Geometry) {
2836 if (change.gTypes == QQuickItemPrivate::GeometryChange) {
2837 change.listener->itemGeometryChanged(this, newGeometry, oldGeometry);
2838 } else if ((xChange && (change.gTypes & QQuickItemPrivate::XChange)) ||
2839 (yChange && (change.gTypes & QQuickItemPrivate::YChange)) ||
2840 (widthChange && (change.gTypes & QQuickItemPrivate::WidthChange)) ||
2841 (heightChange && (change.gTypes & QQuickItemPrivate::HeightChange))) {
2842 change.listener->itemGeometryChanged(this, newGeometry, oldGeometry);
2852 emit widthChanged();
2854 emit heightChanged();
2858 Called by the rendering thread when it is time to sync the state of the QML objects with the
2859 scene graph objects. The function should return the root of the scene graph subtree for
2860 this item. \a oldNode is the node that was returned the last time the function was called.
2862 The main thread is blocked while this function is executed so it is safe to read
2863 values from the QQuickItem instance and other objects in the main thread.
2865 \warning This is the only function in which it is allowed to make use of scene graph
2866 objects from the main thread. Use of scene graph objects outside this function will
2867 result in race conditions and potential crashes.
2870 QSGNode *QQuickItem::updatePaintNode(QSGNode *oldNode, UpdatePaintNodeData *)
2876 QSGTransformNode *QQuickItemPrivate::createTransformNode()
2878 return new QSGTransformNode;
2881 void QQuickItem::updatePolish()
2885 void QQuickItemPrivate::removeItemChangeListener(QQuickItemChangeListener *listener, ChangeTypes types)
2887 ChangeListener change(listener, types);
2888 changeListeners.removeOne(change);
2891 void QQuickItemPrivate::updateOrAddGeometryChangeListener(QQuickItemChangeListener *listener, GeometryChangeTypes types)
2893 ChangeListener change(listener, types);
2894 int index = changeListeners.find(change);
2896 changeListeners[index].gTypes = change.gTypes; //we may have different GeometryChangeTypes
2898 changeListeners.append(change);
2901 void QQuickItemPrivate::updateOrRemoveGeometryChangeListener(QQuickItemChangeListener *listener, GeometryChangeTypes types)
2903 ChangeListener change(listener, types);
2904 if (types == NoChange) {
2905 changeListeners.removeOne(change);
2907 int index = changeListeners.find(change);
2909 changeListeners[index].gTypes = change.gTypes; //we may have different GeometryChangeTypes
2913 void QQuickItem::keyPressEvent(QKeyEvent *event)
2918 void QQuickItem::keyReleaseEvent(QKeyEvent *event)
2923 void QQuickItem::inputMethodEvent(QInputMethodEvent *event)
2928 void QQuickItem::focusInEvent(QFocusEvent *)
2932 void QQuickItem::focusOutEvent(QFocusEvent *)
2936 void QQuickItem::mousePressEvent(QMouseEvent *event)
2941 void QQuickItem::mouseMoveEvent(QMouseEvent *event)
2946 void QQuickItem::mouseReleaseEvent(QMouseEvent *event)
2951 void QQuickItem::mouseDoubleClickEvent(QMouseEvent *event)
2953 mousePressEvent(event);
2956 void QQuickItem::mouseUngrabEvent()
2961 void QQuickItem::touchUngrabEvent()
2966 void QQuickItem::wheelEvent(QWheelEvent *event)
2971 void QQuickItem::touchEvent(QTouchEvent *event)
2976 void QQuickItem::hoverEnterEvent(QHoverEvent *event)
2981 void QQuickItem::hoverMoveEvent(QHoverEvent *event)
2986 void QQuickItem::hoverLeaveEvent(QHoverEvent *event)
2991 void QQuickItem::dragEnterEvent(QDragEnterEvent *event)
2996 void QQuickItem::dragMoveEvent(QDragMoveEvent *event)
3002 void QQuickItem::dragLeaveEvent(QDragLeaveEvent *event)
3008 void QQuickItem::dropEvent(QDropEvent *event)
3013 bool QQuickItem::childMouseEventFilter(QQuickItem *, QEvent *)
3018 void QQuickItem::windowDeactivateEvent()
3020 foreach (QQuickItem* item, childItems()) {
3021 item->windowDeactivateEvent();
3025 Qt::InputMethodHints QQuickItem::inputMethodHints() const
3027 Q_D(const QQuickItem);
3031 void QQuickItem::setInputMethodHints(Qt::InputMethodHints hints)
3036 if (!d->canvas || d->canvas->activeFocusItem() != this)
3039 QInputPanel *p = qApp->inputPanel();
3040 if (p->inputItem() == this)
3041 qApp->inputPanel()->update(Qt::ImHints);
3044 void QQuickItem::updateMicroFocus()
3046 QInputPanel *p = qApp->inputPanel();
3047 if (p->inputItem() == this)
3048 qApp->inputPanel()->update(Qt::ImQueryInput);
3051 QVariant QQuickItem::inputMethodQuery(Qt::InputMethodQuery query) const
3053 Q_D(const QQuickItem);
3058 v = (bool)(flags() & ItemAcceptsInputMethod);
3061 v = (int)inputMethodHints();
3063 case Qt::ImCursorRectangle:
3065 case Qt::ImCursorPosition:
3066 case Qt::ImSurroundingText:
3067 case Qt::ImCurrentSelection:
3068 case Qt::ImMaximumTextLength:
3069 case Qt::ImAnchorPosition:
3070 case Qt::ImPreferredLanguage:
3072 v = d->keyHandler->inputMethodQuery(query);
3080 QQuickAnchorLine QQuickItemPrivate::left() const
3082 return anchorLines()->left;
3085 QQuickAnchorLine QQuickItemPrivate::right() const
3087 return anchorLines()->right;
3090 QQuickAnchorLine QQuickItemPrivate::horizontalCenter() const
3092 return anchorLines()->hCenter;
3095 QQuickAnchorLine QQuickItemPrivate::top() const
3097 return anchorLines()->top;
3100 QQuickAnchorLine QQuickItemPrivate::bottom() const
3102 return anchorLines()->bottom;
3105 QQuickAnchorLine QQuickItemPrivate::verticalCenter() const
3107 return anchorLines()->vCenter;
3110 QQuickAnchorLine QQuickItemPrivate::baseline() const
3112 return anchorLines()->baseline;
3115 qreal QQuickItem::baselineOffset() const
3117 Q_D(const QQuickItem);
3118 if (!d->baselineOffset.isValid()) {
3121 return d->baselineOffset;
3124 void QQuickItem::setBaselineOffset(qreal offset)
3127 if (offset == d->baselineOffset)
3130 d->baselineOffset = offset;
3132 for (int ii = 0; ii < d->changeListeners.count(); ++ii) {
3133 const QQuickItemPrivate::ChangeListener &change = d->changeListeners.at(ii);
3134 if (change.types & QQuickItemPrivate::Geometry) {
3135 QQuickAnchorsPrivate *anchor = change.listener->anchorPrivate();
3137 anchor->updateVerticalAnchors();
3140 emit baselineOffsetChanged(offset);
3143 void QQuickItem::update()
3146 Q_ASSERT(flags() & ItemHasContents);
3147 d->dirty(QQuickItemPrivate::Content);
3150 void QQuickItem::polish()
3153 if (!d->polishScheduled) {
3154 d->polishScheduled = true;
3156 QQuickCanvasPrivate *p = QQuickCanvasPrivate::get(d->canvas);
3157 bool maybeupdate = p->itemsToPolish.isEmpty();
3158 p->itemsToPolish.insert(this);
3159 if (maybeupdate) d->canvas->maybeUpdate();
3164 void QQuickItem::mapFromItem(QDeclarativeV8Function *args) const
3166 if (args->Length() != 0) {
3167 v8::Local<v8::Value> item = (*args)[0];
3168 QV8Engine *engine = args->engine();
3170 QQuickItem *itemObj = 0;
3171 if (!item->IsNull())
3172 itemObj = qobject_cast<QQuickItem*>(engine->toQObject(item));
3174 if (!itemObj && !item->IsNull()) {
3175 qmlInfo(this) << "mapFromItem() given argument \"" << engine->toString(item->ToString())
3176 << "\" which is neither null nor an Item";
3180 v8::Local<v8::Object> rv = v8::Object::New();
3181 args->returnValue(rv);
3183 qreal x = (args->Length() > 1)?(*args)[1]->NumberValue():0;
3184 qreal y = (args->Length() > 2)?(*args)[2]->NumberValue():0;
3186 QPointF p = mapFromItem(itemObj, QPointF(x, y));
3188 rv->Set(v8::String::New("x"), v8::Number::New(p.x()));
3189 rv->Set(v8::String::New("y"), v8::Number::New(p.y()));
3193 QTransform QQuickItem::itemTransform(QQuickItem *other, bool *ok) const
3195 Q_D(const QQuickItem);
3197 // XXX todo - we need to be able to handle common parents better and detect
3201 QTransform t = d->itemToCanvasTransform();
3202 if (other) t *= QQuickItemPrivate::get(other)->canvasToItemTransform();
3207 void QQuickItem::mapToItem(QDeclarativeV8Function *args) const
3209 if (args->Length() != 0) {
3210 v8::Local<v8::Value> item = (*args)[0];
3211 QV8Engine *engine = args->engine();
3213 QQuickItem *itemObj = 0;
3214 if (!item->IsNull())
3215 itemObj = qobject_cast<QQuickItem*>(engine->toQObject(item));
3217 if (!itemObj && !item->IsNull()) {
3218 qmlInfo(this) << "mapToItem() given argument \"" << engine->toString(item->ToString())
3219 << "\" which is neither null nor an Item";
3223 v8::Local<v8::Object> rv = v8::Object::New();
3224 args->returnValue(rv);
3226 qreal x = (args->Length() > 1)?(*args)[1]->NumberValue():0;
3227 qreal y = (args->Length() > 2)?(*args)[2]->NumberValue():0;
3229 QPointF p = mapToItem(itemObj, QPointF(x, y));
3231 rv->Set(v8::String::New("x"), v8::Number::New(p.x()));
3232 rv->Set(v8::String::New("y"), v8::Number::New(p.y()));
3236 void QQuickItem::forceActiveFocus()
3239 QQuickItem *parent = parentItem();
3241 if (parent->flags() & QQuickItem::ItemIsFocusScope) {
3242 parent->setFocus(true);
3244 parent = parent->parentItem();
3248 QQuickItem *QQuickItem::childAt(qreal x, qreal y) const
3250 // XXX todo - should this include transform etc.?
3251 const QList<QQuickItem *> children = childItems();
3252 for (int i = children.count()-1; i >= 0; --i) {
3253 QQuickItem *child = children.at(i);
3254 if (child->isVisible() && child->x() <= x
3255 && child->x() + child->width() >= x
3257 && child->y() + child->height() >= y)
3263 QDeclarativeListProperty<QObject> QQuickItemPrivate::resources()
3265 return QDeclarativeListProperty<QObject>(q_func(), 0, QQuickItemPrivate::resources_append,
3266 QQuickItemPrivate::resources_count,
3267 QQuickItemPrivate::resources_at,
3268 QQuickItemPrivate::resources_clear);
3271 QDeclarativeListProperty<QQuickItem> QQuickItemPrivate::children()
3273 return QDeclarativeListProperty<QQuickItem>(q_func(), 0, QQuickItemPrivate::children_append,
3274 QQuickItemPrivate::children_count,
3275 QQuickItemPrivate::children_at,
3276 QQuickItemPrivate::children_clear);
3280 QDeclarativeListProperty<QDeclarativeState> QQuickItemPrivate::states()
3282 return _states()->statesProperty();
3285 QDeclarativeListProperty<QDeclarativeTransition> QQuickItemPrivate::transitions()
3287 return _states()->transitionsProperty();
3290 QString QQuickItemPrivate::state() const
3295 return _stateGroup->state();
3298 void QQuickItemPrivate::setState(const QString &state)
3300 _states()->setState(state);
3303 QString QQuickItem::state() const
3305 Q_D(const QQuickItem);
3309 void QQuickItem::setState(const QString &state)
3315 QDeclarativeListProperty<QQuickTransform> QQuickItem::transform()
3317 return QDeclarativeListProperty<QQuickTransform>(this, 0, QQuickItemPrivate::transform_append,
3318 QQuickItemPrivate::transform_count,
3319 QQuickItemPrivate::transform_at,
3320 QQuickItemPrivate::transform_clear);
3323 void QQuickItem::classBegin()
3326 d->componentComplete = false;
3328 d->_stateGroup->classBegin();
3330 d->_anchors->classBegin();
3333 void QQuickItem::componentComplete()
3336 d->componentComplete = true;
3338 d->_stateGroup->componentComplete();
3340 d->_anchors->componentComplete();
3341 QQuickAnchorsPrivate::get(d->_anchors)->updateOnComplete();
3344 d->keyHandler->componentComplete();
3346 d->_contents->complete();
3349 QDeclarativeStateGroup *QQuickItemPrivate::_states()
3353 _stateGroup = new QDeclarativeStateGroup;
3354 if (!componentComplete)
3355 _stateGroup->classBegin();
3356 FAST_CONNECT(_stateGroup, SIGNAL(stateChanged(QString)),
3357 q, SIGNAL(stateChanged(QString)))
3363 QQuickItemPrivate::AnchorLines::AnchorLines(QQuickItem *q)
3366 left.anchorLine = QQuickAnchorLine::Left;
3368 right.anchorLine = QQuickAnchorLine::Right;
3370 hCenter.anchorLine = QQuickAnchorLine::HCenter;
3372 top.anchorLine = QQuickAnchorLine::Top;
3374 bottom.anchorLine = QQuickAnchorLine::Bottom;
3376 vCenter.anchorLine = QQuickAnchorLine::VCenter;
3378 baseline.anchorLine = QQuickAnchorLine::Baseline;
3381 QPointF QQuickItemPrivate::computeTransformOrigin() const
3385 case QQuickItem::TopLeft:
3386 return QPointF(0, 0);
3387 case QQuickItem::Top:
3388 return QPointF(width / 2., 0);
3389 case QQuickItem::TopRight:
3390 return QPointF(width, 0);
3391 case QQuickItem::Left:
3392 return QPointF(0, height / 2.);
3393 case QQuickItem::Center:
3394 return QPointF(width / 2., height / 2.);
3395 case QQuickItem::Right:
3396 return QPointF(width, height / 2.);
3397 case QQuickItem::BottomLeft:
3398 return QPointF(0, height);
3399 case QQuickItem::Bottom:
3400 return QPointF(width / 2., height);
3401 case QQuickItem::BottomRight:
3402 return QPointF(width, height);
3406 void QQuickItemPrivate::transformChanged()
3410 void QQuickItemPrivate::deliverKeyEvent(QKeyEvent *e)
3414 Q_ASSERT(e->isAccepted());
3416 if (e->type() == QEvent::KeyPress)
3417 keyHandler->keyPressed(e, false);
3419 keyHandler->keyReleased(e, false);
3421 if (e->isAccepted())
3427 if (e->type() == QEvent::KeyPress)
3428 q->keyPressEvent(e);
3430 q->keyReleaseEvent(e);
3432 if (e->isAccepted())
3438 if (e->type() == QEvent::KeyPress)
3439 keyHandler->keyPressed(e, true);
3441 keyHandler->keyReleased(e, true);
3445 void QQuickItemPrivate::deliverInputMethodEvent(QInputMethodEvent *e)
3449 Q_ASSERT(e->isAccepted());
3451 keyHandler->inputMethodEvent(e, false);
3453 if (e->isAccepted())
3459 q->inputMethodEvent(e);
3461 if (e->isAccepted())
3467 keyHandler->inputMethodEvent(e, true);
3471 void QQuickItemPrivate::deliverFocusEvent(QFocusEvent *e)
3475 if (e->type() == QEvent::FocusIn) {
3478 q->focusOutEvent(e);
3482 void QQuickItemPrivate::deliverMouseEvent(QMouseEvent *e)
3486 Q_ASSERT(e->isAccepted());
3488 switch (e->type()) {
3490 Q_ASSERT(!"Unknown event type");
3491 case QEvent::MouseMove:
3492 q->mouseMoveEvent(e);
3494 case QEvent::MouseButtonPress:
3495 q->mousePressEvent(e);
3497 case QEvent::MouseButtonRelease:
3498 q->mouseReleaseEvent(e);
3500 case QEvent::MouseButtonDblClick:
3501 q->mouseDoubleClickEvent(e);
3506 void QQuickItemPrivate::deliverWheelEvent(QWheelEvent *e)
3512 void QQuickItemPrivate::deliverTouchEvent(QTouchEvent *e)
3518 void QQuickItemPrivate::deliverHoverEvent(QHoverEvent *e)
3521 switch (e->type()) {
3523 Q_ASSERT(!"Unknown event type");
3524 case QEvent::HoverEnter:
3525 q->hoverEnterEvent(e);
3527 case QEvent::HoverLeave:
3528 q->hoverLeaveEvent(e);
3530 case QEvent::HoverMove:
3531 q->hoverMoveEvent(e);
3536 void QQuickItemPrivate::deliverDragEvent(QEvent *e)
3539 switch (e->type()) {
3541 Q_ASSERT(!"Unknown event type");
3542 case QEvent::DragEnter:
3543 q->dragEnterEvent(static_cast<QDragEnterEvent *>(e));
3545 case QEvent::DragLeave:
3546 q->dragLeaveEvent(static_cast<QDragLeaveEvent *>(e));
3548 case QEvent::DragMove:
3549 q->dragMoveEvent(static_cast<QDragMoveEvent *>(e));
3552 q->dropEvent(static_cast<QDropEvent *>(e));
3557 void QQuickItem::itemChange(ItemChange change, const ItemChangeData &value)
3564 // XXX todo - do we want/need this anymore?
3565 // Note that it's now used for varying clip rect
3566 QRectF QQuickItem::boundingRect() const
3568 Q_D(const QQuickItem);
3569 return QRectF(0, 0, d->width, d->height);
3572 QQuickItem::TransformOrigin QQuickItem::transformOrigin() const
3574 Q_D(const QQuickItem);
3578 void QQuickItem::setTransformOrigin(TransformOrigin origin)
3581 if (origin == d->origin)
3585 d->dirty(QQuickItemPrivate::TransformOrigin);
3587 emit transformOriginChanged(d->origin);
3590 QPointF QQuickItem::transformOriginPoint() const
3592 Q_D(const QQuickItem);
3593 if (!d->transformOriginPoint.isNull())
3594 return d->transformOriginPoint;
3595 return d->computeTransformOrigin();
3598 void QQuickItem::setTransformOriginPoint(const QPointF &point)
3601 if (d->transformOriginPoint == point)
3604 d->transformOriginPoint = point;
3605 d->dirty(QQuickItemPrivate::TransformOrigin);
3608 qreal QQuickItem::z() const
3610 Q_D(const QQuickItem);
3614 void QQuickItem::setZ(qreal v)
3622 d->dirty(QQuickItemPrivate::ZValue);
3623 if (d->parentItem) {
3624 QQuickItemPrivate::get(d->parentItem)->dirty(QQuickItemPrivate::ChildrenStackingChanged);
3625 QQuickItemPrivate::get(d->parentItem)->markSortedChildrenDirty(this);
3633 \qmlproperty real QtQuick2::Item::rotation
3634 This property holds the rotation of the item in degrees clockwise.
3636 This specifies how many degrees to rotate the item around its transformOrigin.
3637 The default rotation is 0 degrees (i.e. not rotated at all).
3641 \o \image declarative-rotation.png
3646 width: 100; height: 100
3649 x: 25; y: 25; width: 50; height: 50
3656 \sa transform, Rotation
3660 \qmlproperty real QtQuick2::Item::scale
3661 This property holds the scale of the item.
3663 A scale of less than 1 means the item will be displayed smaller than
3664 normal, and a scale of greater than 1 means the item will be
3665 displayed larger than normal. A negative scale means the item will
3668 By default, items are displayed at a scale of 1 (i.e. at their
3671 Scaling is from the item's transformOrigin.
3675 \o \image declarative-scale.png
3680 width: 100; height: 100
3683 width: 25; height: 25
3687 x: 25; y: 25; width: 50; height: 50
3694 \sa transform, Scale
3698 \qmlproperty real QtQuick2::Item::opacity
3700 This property holds the opacity of the item. Opacity is specified as a
3701 number between 0 (fully transparent) and 1 (fully opaque). The default is 1.
3703 When this property is set, the specified opacity is also applied
3704 individually to child items. In almost all cases this is what you want,
3705 but in some cases it may produce undesired results. For example in the
3706 second set of rectangles below, the red rectangle has specified an opacity
3707 of 0.5, which affects the opacity of its blue child rectangle even though
3708 the child has not specified an opacity.
3712 \o \image declarative-item_opacity1.png
3718 width: 100; height: 100
3721 x: 50; y: 50; width: 100; height: 100
3727 \o \image declarative-item_opacity2.png
3734 width: 100; height: 100
3737 x: 50; y: 50; width: 100; height: 100
3744 If an item's opacity is set to 0, the item will no longer receive mouse
3745 events, but will continue to receive key events and will retain the keyboard
3746 \l focus if it has been set. (In contrast, setting the \l visible property
3747 to \c false stops both mouse and keyboard events, and also removes focus
3752 Returns a value indicating whether mouse input should
3753 remain with this item exclusively.
3755 \sa setKeepMouseGrab()
3758 qreal QQuickItem::rotation() const
3760 Q_D(const QQuickItem);
3764 void QQuickItem::setRotation(qreal r)
3767 if (d->rotation == r)
3772 d->dirty(QQuickItemPrivate::BasicTransform);
3774 d->itemChange(ItemRotationHasChanged, r);
3776 emit rotationChanged();
3779 qreal QQuickItem::scale() const
3781 Q_D(const QQuickItem);
3785 void QQuickItem::setScale(qreal s)
3793 d->dirty(QQuickItemPrivate::BasicTransform);
3795 emit scaleChanged();
3798 qreal QQuickItem::opacity() const
3800 Q_D(const QQuickItem);
3804 void QQuickItem::setOpacity(qreal o)
3807 if (d->opacity == o)
3812 d->dirty(QQuickItemPrivate::OpacityValue);
3814 d->itemChange(ItemOpacityHasChanged, o);
3816 emit opacityChanged();
3819 bool QQuickItem::isVisible() const
3821 Q_D(const QQuickItem);
3822 return d->effectiveVisible;
3825 void QQuickItem::setVisible(bool v)
3828 if (v == d->explicitVisible)
3831 d->explicitVisible = v;
3833 d->setEffectiveVisibleRecur(d->calcEffectiveVisible());
3836 bool QQuickItem::isEnabled() const
3838 Q_D(const QQuickItem);
3839 return d->effectiveEnable;
3842 void QQuickItem::setEnabled(bool e)
3845 if (e == d->explicitEnable)
3848 d->explicitEnable = e;
3850 d->setEffectiveEnableRecur(d->calcEffectiveEnable());
3853 bool QQuickItemPrivate::calcEffectiveVisible() const
3855 // XXX todo - Should the effective visible of an element with no parent just be the current
3856 // effective visible? This would prevent pointless re-processing in the case of an element
3857 // moving to/from a no-parent situation, but it is different from what graphics view does.
3858 return explicitVisible && (!parentItem || QQuickItemPrivate::get(parentItem)->effectiveVisible);
3861 void QQuickItemPrivate::setEffectiveVisibleRecur(bool newEffectiveVisible)
3865 if (newEffectiveVisible && !explicitVisible) {
3866 // This item locally overrides visibility
3870 if (newEffectiveVisible == effectiveVisible) {
3871 // No change necessary
3875 effectiveVisible = newEffectiveVisible;
3877 if (parentItem) QQuickItemPrivate::get(parentItem)->dirty(ChildrenStackingChanged);
3880 QQuickCanvasPrivate *canvasPriv = QQuickCanvasPrivate::get(canvas);
3881 if (canvasPriv->mouseGrabberItem == q)
3885 for (int ii = 0; ii < childItems.count(); ++ii)
3886 QQuickItemPrivate::get(childItems.at(ii))->setEffectiveVisibleRecur(newEffectiveVisible);
3888 for (int ii = 0; ii < changeListeners.count(); ++ii) {
3889 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
3890 if (change.types & QQuickItemPrivate::Visibility)
3891 change.listener->itemVisibilityChanged(q);
3894 emit q->visibleChanged();
3897 bool QQuickItemPrivate::calcEffectiveEnable() const
3899 // XXX todo - Should the effective enable of an element with no parent just be the current
3900 // effective enable? This would prevent pointless re-processing in the case of an element
3901 // moving to/from a no-parent situation, but it is different from what graphics view does.
3902 return explicitEnable && (!parentItem || QQuickItemPrivate::get(parentItem)->effectiveEnable);
3905 void QQuickItemPrivate::setEffectiveEnableRecur(bool newEffectiveEnable)
3909 // XXX todo - need to fixup focus
3911 if (newEffectiveEnable && !explicitEnable) {
3912 // This item locally overrides enable
3916 if (newEffectiveEnable == effectiveEnable) {
3917 // No change necessary
3921 effectiveEnable = newEffectiveEnable;
3924 QQuickCanvasPrivate *canvasPriv = QQuickCanvasPrivate::get(canvas);
3925 if (canvasPriv->mouseGrabberItem == q)
3929 for (int ii = 0; ii < childItems.count(); ++ii)
3930 QQuickItemPrivate::get(childItems.at(ii))->setEffectiveEnableRecur(newEffectiveEnable);
3932 emit q->enabledChanged();
3935 QString QQuickItemPrivate::dirtyToString() const
3937 #define DIRTY_TO_STRING(value) if (dirtyAttributes & value) { \
3938 if (!rv.isEmpty()) \
3939 rv.append(QLatin1String("|")); \
3940 rv.append(QLatin1String(#value)); \
3943 // QString rv = QLatin1String("0x") + QString::number(dirtyAttributes, 16);
3946 DIRTY_TO_STRING(TransformOrigin);
3947 DIRTY_TO_STRING(Transform);
3948 DIRTY_TO_STRING(BasicTransform);
3949 DIRTY_TO_STRING(Position);
3950 DIRTY_TO_STRING(Size);
3951 DIRTY_TO_STRING(ZValue);
3952 DIRTY_TO_STRING(Content);
3953 DIRTY_TO_STRING(Smooth);
3954 DIRTY_TO_STRING(OpacityValue);
3955 DIRTY_TO_STRING(ChildrenChanged);
3956 DIRTY_TO_STRING(ChildrenStackingChanged);
3957 DIRTY_TO_STRING(ParentChanged);
3958 DIRTY_TO_STRING(Clip);
3959 DIRTY_TO_STRING(Canvas);
3960 DIRTY_TO_STRING(EffectReference);
3961 DIRTY_TO_STRING(Visible);
3962 DIRTY_TO_STRING(HideReference);
3967 void QQuickItemPrivate::dirty(DirtyType type)
3970 if (type & (TransformOrigin | Transform | BasicTransform | Position | Size))
3973 if (!(dirtyAttributes & type) || (canvas && !prevDirtyItem)) {
3974 dirtyAttributes |= type;
3977 QQuickCanvasPrivate::get(canvas)->dirtyItem(q);
3982 void QQuickItemPrivate::addToDirtyList()
3987 if (!prevDirtyItem) {
3988 Q_ASSERT(!nextDirtyItem);
3990 QQuickCanvasPrivate *p = QQuickCanvasPrivate::get(canvas);
3991 nextDirtyItem = p->dirtyItemList;
3992 if (nextDirtyItem) QQuickItemPrivate::get(nextDirtyItem)->prevDirtyItem = &nextDirtyItem;
3993 prevDirtyItem = &p->dirtyItemList;
3994 p->dirtyItemList = q;
3997 Q_ASSERT(prevDirtyItem);
4000 void QQuickItemPrivate::removeFromDirtyList()
4002 if (prevDirtyItem) {
4003 if (nextDirtyItem) QQuickItemPrivate::get(nextDirtyItem)->prevDirtyItem = prevDirtyItem;
4004 *prevDirtyItem = nextDirtyItem;
4008 Q_ASSERT(!prevDirtyItem);
4009 Q_ASSERT(!nextDirtyItem);
4012 void QQuickItemPrivate::refFromEffectItem(bool hide)
4015 if (1 == effectRefCount) {
4016 dirty(EffectReference);
4017 if (parentItem) QQuickItemPrivate::get(parentItem)->dirty(ChildrenStackingChanged);
4020 if (++hideRefCount == 1)
4021 dirty(HideReference);
4025 void QQuickItemPrivate::derefFromEffectItem(bool unhide)
4027 Q_ASSERT(effectRefCount);
4029 if (0 == effectRefCount) {
4030 dirty(EffectReference);
4031 if (parentItem) QQuickItemPrivate::get(parentItem)->dirty(ChildrenStackingChanged);
4034 if (--hideRefCount == 0)
4035 dirty(HideReference);
4039 void QQuickItemPrivate::itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &data)
4043 case QQuickItem::ItemChildAddedChange:
4044 q->itemChange(change, data);
4045 for (int ii = 0; ii < changeListeners.count(); ++ii) {
4046 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
4047 if (change.types & QQuickItemPrivate::Children) {
4048 change.listener->itemChildAdded(q, data.item);
4052 case QQuickItem::ItemChildRemovedChange:
4053 q->itemChange(change, data);
4054 for (int ii = 0; ii < changeListeners.count(); ++ii) {
4055 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
4056 if (change.types & QQuickItemPrivate::Children) {
4057 change.listener->itemChildRemoved(q, data.item);
4061 case QQuickItem::ItemSceneChange:
4062 q->itemChange(change, data);
4064 case QQuickItem::ItemVisibleHasChanged:
4065 q->itemChange(change, data);
4066 for (int ii = 0; ii < changeListeners.count(); ++ii) {
4067 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
4068 if (change.types & QQuickItemPrivate::Visibility) {
4069 change.listener->itemVisibilityChanged(q);
4073 case QQuickItem::ItemParentHasChanged:
4074 q->itemChange(change, data);
4075 for (int ii = 0; ii < changeListeners.count(); ++ii) {
4076 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
4077 if (change.types & QQuickItemPrivate::Parent) {
4078 change.listener->itemParentChanged(q, data.item);
4082 case QQuickItem::ItemOpacityHasChanged:
4083 q->itemChange(change, data);
4084 for (int ii = 0; ii < changeListeners.count(); ++ii) {
4085 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
4086 if (change.types & QQuickItemPrivate::Opacity) {
4087 change.listener->itemOpacityChanged(q);
4091 case QQuickItem::ItemActiveFocusHasChanged:
4092 q->itemChange(change, data);
4094 case QQuickItem::ItemRotationHasChanged:
4095 q->itemChange(change, data);
4096 for (int ii = 0; ii < changeListeners.count(); ++ii) {
4097 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
4098 if (change.types & QQuickItemPrivate::Rotation) {
4099 change.listener->itemRotationChanged(q);
4107 \property QQuickItem::smooth
4108 \brief whether the item is smoothly transformed.
4110 This property is provided purely for the purpose of optimization. Turning
4111 smooth transforms off is faster, but looks worse; turning smooth
4112 transformations on is slower, but looks better.
4114 By default smooth transformations are off.
4118 Returns true if the item should be drawn with antialiasing and
4119 smooth pixmap filtering, false otherwise.
4121 The default is false.
4125 bool QQuickItem::smooth() const
4127 Q_D(const QQuickItem);
4132 Sets whether the item should be drawn with antialiasing and
4133 smooth pixmap filtering to \a smooth.
4137 void QQuickItem::setSmooth(bool smooth)
4140 if (d->smooth == smooth)
4144 d->dirty(QQuickItemPrivate::Smooth);
4146 emit smoothChanged(smooth);
4149 QQuickItem::Flags QQuickItem::flags() const
4151 Q_D(const QQuickItem);
4152 return (QQuickItem::Flags)d->flags;
4155 void QQuickItem::setFlag(Flag flag, bool enabled)
4159 setFlags((Flags)(d->flags | (quint32)flag));
4161 setFlags((Flags)(d->flags & ~(quint32)flag));
4164 void QQuickItem::setFlags(Flags flags)
4168 if ((flags & ItemIsFocusScope) != (d->flags & ItemIsFocusScope)) {
4169 if (flags & ItemIsFocusScope && !d->childItems.isEmpty() && d->canvas) {
4170 qWarning("QQuickItem: Cannot set FocusScope once item has children and is in a canvas.");
4171 flags &= ~ItemIsFocusScope;
4172 } else if (d->flags & ItemIsFocusScope) {
4173 qWarning("QQuickItem: Cannot unset FocusScope flag.");
4174 flags |= ItemIsFocusScope;
4178 if ((flags & ItemClipsChildrenToShape ) != (d->flags & ItemClipsChildrenToShape))
4179 d->dirty(QQuickItemPrivate::Clip);
4184 qreal QQuickItem::x() const
4186 Q_D(const QQuickItem);
4190 qreal QQuickItem::y() const
4192 Q_D(const QQuickItem);
4196 QPointF QQuickItem::pos() const
4198 Q_D(const QQuickItem);
4199 return QPointF(d->x, d->y);
4202 void QQuickItem::setX(qreal v)
4211 d->dirty(QQuickItemPrivate::Position);
4213 geometryChanged(QRectF(x(), y(), width(), height()),
4214 QRectF(oldx, y(), width(), height()));
4217 void QQuickItem::setY(qreal v)
4226 d->dirty(QQuickItemPrivate::Position);
4228 geometryChanged(QRectF(x(), y(), width(), height()),
4229 QRectF(x(), oldy, width(), height()));
4232 void QQuickItem::setPos(const QPointF &pos)
4235 if (QPointF(d->x, d->y) == pos)
4244 d->dirty(QQuickItemPrivate::Position);
4246 geometryChanged(QRectF(x(), y(), width(), height()),
4247 QRectF(oldx, oldy, width(), height()));
4250 qreal QQuickItem::width() const
4252 Q_D(const QQuickItem);
4256 void QQuickItem::setWidth(qreal w)
4262 d->widthValid = true;
4266 qreal oldWidth = d->width;
4269 d->dirty(QQuickItemPrivate::Size);
4271 geometryChanged(QRectF(x(), y(), width(), height()),
4272 QRectF(x(), y(), oldWidth, height()));
4275 void QQuickItem::resetWidth()
4278 d->widthValid = false;
4279 setImplicitWidth(implicitWidth());
4282 void QQuickItemPrivate::implicitWidthChanged()
4285 emit q->implicitWidthChanged();
4288 qreal QQuickItemPrivate::getImplicitWidth() const
4290 return implicitWidth;
4293 Returns the width of the item that is implied by other properties that determine the content.
4295 qreal QQuickItem::implicitWidth() const
4297 Q_D(const QQuickItem);
4298 return d->getImplicitWidth();
4302 \qmlproperty real QtQuick2::Item::implicitWidth
4303 \qmlproperty real QtQuick2::Item::implicitHeight
4305 Defines the natural width or height of the Item if no \l width or \l height is specified.
4307 The default implicit size for most items is 0x0, however some elements have an inherent
4308 implicit size which cannot be overridden, e.g. Image, Text.
4310 Setting the implicit size is useful for defining components that have a preferred size
4311 based on their content, for example:
4318 property alias icon: image.source
4319 property alias label: text.text
4320 implicitWidth: text.implicitWidth + image.implicitWidth
4321 implicitHeight: Math.max(text.implicitHeight, image.implicitHeight)
4326 anchors.left: image.right; anchors.right: parent.right
4327 anchors.verticalCenter: parent.verticalCenter
4332 \bold Note: using implicitWidth of Text or TextEdit and setting the width explicitly
4333 incurs a performance penalty as the text must be laid out twice.
4337 Sets the implied width of the item to \a w.
4338 This is the width implied by other properties that determine the content.
4340 void QQuickItem::setImplicitWidth(qreal w)
4343 bool changed = w != d->implicitWidth;
4344 d->implicitWidth = w;
4345 if (d->width == w || widthValid()) {
4347 d->implicitWidthChanged();
4351 qreal oldWidth = d->width;
4354 d->dirty(QQuickItemPrivate::Size);
4356 geometryChanged(QRectF(x(), y(), width(), height()),
4357 QRectF(x(), y(), oldWidth, height()));
4360 d->implicitWidthChanged();
4364 Returns whether the width property has been set explicitly.
4366 bool QQuickItem::widthValid() const
4368 Q_D(const QQuickItem);
4369 return d->widthValid;
4372 qreal QQuickItem::height() const
4374 Q_D(const QQuickItem);
4378 void QQuickItem::setHeight(qreal h)
4384 d->heightValid = true;
4388 qreal oldHeight = d->height;
4391 d->dirty(QQuickItemPrivate::Size);
4393 geometryChanged(QRectF(x(), y(), width(), height()),
4394 QRectF(x(), y(), width(), oldHeight));
4397 void QQuickItem::resetHeight()
4400 d->heightValid = false;
4401 setImplicitHeight(implicitHeight());
4404 void QQuickItemPrivate::implicitHeightChanged()
4407 emit q->implicitHeightChanged();
4410 qreal QQuickItemPrivate::getImplicitHeight() const
4412 return implicitHeight;
4416 Returns the height of the item that is implied by other properties that determine the content.
4418 qreal QQuickItem::implicitHeight() const
4420 Q_D(const QQuickItem);
4421 return d->getImplicitHeight();
4426 Sets the implied height of the item to \a h.
4427 This is the height implied by other properties that determine the content.
4429 void QQuickItem::setImplicitHeight(qreal h)
4432 bool changed = h != d->implicitHeight;
4433 d->implicitHeight = h;
4434 if (d->height == h || heightValid()) {
4436 d->implicitHeightChanged();
4440 qreal oldHeight = d->height;
4443 d->dirty(QQuickItemPrivate::Size);
4445 geometryChanged(QRectF(x(), y(), width(), height()),
4446 QRectF(x(), y(), width(), oldHeight));
4449 d->implicitHeightChanged();
4452 void QQuickItem::setImplicitSize(qreal w, qreal h)
4455 bool wChanged = w != d->implicitWidth;
4456 bool hChanged = h != d->implicitHeight;
4458 d->implicitWidth = w;
4459 d->implicitHeight = h;
4463 if (d->width == w || widthValid()) {
4465 d->implicitWidthChanged();
4468 if (d->height == h || heightValid()) {
4470 d->implicitHeightChanged();
4476 qreal oldWidth = d->width;
4477 qreal oldHeight = d->height;
4483 d->dirty(QQuickItemPrivate::Size);
4485 geometryChanged(QRectF(x(), y(), width(), height()),
4486 QRectF(x(), y(), oldWidth, oldHeight));
4488 if (!wDone && wChanged)
4489 d->implicitWidthChanged();
4490 if (!hDone && hChanged)
4491 d->implicitHeightChanged();
4495 Returns whether the height property has been set explicitly.
4497 bool QQuickItem::heightValid() const
4499 Q_D(const QQuickItem);
4500 return d->heightValid;
4503 void QQuickItem::setSize(const QSizeF &size)
4506 d->heightValid = true;
4507 d->widthValid = true;
4509 if (QSizeF(d->width, d->height) == size)
4512 qreal oldHeight = d->height;
4513 qreal oldWidth = d->width;
4514 d->height = size.height();
4515 d->width = size.width();
4517 d->dirty(QQuickItemPrivate::Size);
4519 geometryChanged(QRectF(x(), y(), width(), height()),
4520 QRectF(x(), y(), oldWidth, oldHeight));
4523 bool QQuickItem::hasActiveFocus() const
4525 Q_D(const QQuickItem);
4526 return d->activeFocus;
4529 bool QQuickItem::hasFocus() const
4531 Q_D(const QQuickItem);
4535 void QQuickItem::setFocus(bool focus)
4538 if (d->focus == focus)
4542 // Need to find our nearest focus scope
4543 QQuickItem *scope = parentItem();
4544 while (scope && !scope->isFocusScope())
4545 scope = scope->parentItem();
4547 QQuickCanvasPrivate::get(d->canvas)->setFocusInScope(scope, this);
4549 QQuickCanvasPrivate::get(d->canvas)->clearFocusInScope(scope, this);
4552 emit focusChanged(focus);
4556 bool QQuickItem::isFocusScope() const
4558 return flags() & ItemIsFocusScope;
4561 QQuickItem *QQuickItem::scopedFocusItem() const
4563 Q_D(const QQuickItem);
4564 if (!isFocusScope())
4567 return d->subFocusItem;
4571 Qt::MouseButtons QQuickItem::acceptedMouseButtons() const
4573 Q_D(const QQuickItem);
4574 return d->acceptedMouseButtons;
4577 void QQuickItem::setAcceptedMouseButtons(Qt::MouseButtons buttons)
4580 d->acceptedMouseButtons = buttons;
4583 bool QQuickItem::filtersChildMouseEvents() const
4585 Q_D(const QQuickItem);
4586 return d->filtersChildMouseEvents;
4589 void QQuickItem::setFiltersChildMouseEvents(bool filter)
4592 d->filtersChildMouseEvents = filter;
4595 bool QQuickItem::isUnderMouse() const
4597 Q_D(const QQuickItem);
4601 QPoint cursorPos = QCursor::pos();
4602 if (QRectF(0, 0, width(), height()).contains(mapFromScene(cursorPos))) // ### refactor: d->canvas->mapFromGlobal(cursorPos))))
4607 bool QQuickItem::acceptHoverEvents() const
4609 Q_D(const QQuickItem);
4610 return d->hoverEnabled;
4613 void QQuickItem::setAcceptHoverEvents(bool enabled)
4616 d->hoverEnabled = enabled;
4619 void QQuickItem::grabMouse()
4624 QQuickCanvasPrivate *canvasPriv = QQuickCanvasPrivate::get(d->canvas);
4625 if (canvasPriv->mouseGrabberItem == this)
4628 QQuickItem *oldGrabber = canvasPriv->mouseGrabberItem;
4629 canvasPriv->mouseGrabberItem = this;
4631 oldGrabber->mouseUngrabEvent();
4634 void QQuickItem::ungrabMouse()
4639 QQuickCanvasPrivate *canvasPriv = QQuickCanvasPrivate::get(d->canvas);
4640 if (canvasPriv->mouseGrabberItem != this) {
4641 qWarning("QQuickItem::ungrabMouse(): Item is not the mouse grabber.");
4645 canvasPriv->mouseGrabberItem = 0;
4649 bool QQuickItem::keepMouseGrab() const
4651 Q_D(const QQuickItem);
4652 return d->keepMouse;
4656 The flag indicating whether the mouse should remain
4657 with this item is set to \a keep.
4659 This is useful for items that wish to grab and keep mouse
4660 interaction following a predefined gesture. For example,
4661 an item that is interested in horizontal mouse movement
4662 may set keepMouseGrab to true once a threshold has been
4663 exceeded. Once keepMouseGrab has been set to true, filtering
4664 items will not react to mouse events.
4666 If the item does not indicate that it wishes to retain mouse grab,
4667 a filtering item may steal the grab. For example, Flickable may attempt
4668 to steal a mouse grab if it detects that the user has begun to
4673 void QQuickItem::setKeepMouseGrab(bool keep)
4676 d->keepMouse = keep;
4680 Grabs the touch points specified by \a ids.
4682 These touch points will be owned by the item until
4683 they are released. Alternatively, the grab can be stolen
4684 by a filtering item like Flickable. Use setKeepTouchGrab()
4685 to prevent the grab from being stolen.
4687 \sa ungrabTouchPoints(), setKeepTouchGrab()
4689 void QQuickItem::grabTouchPoints(const QList<int> &ids)
4694 QQuickCanvasPrivate *canvasPriv = QQuickCanvasPrivate::get(d->canvas);
4696 QSet<QQuickItem*> ungrab;
4697 for (int i = 0; i < ids.count(); ++i) {
4698 QQuickItem *oldGrabber = canvasPriv->itemForTouchPointId.value(ids.at(i));
4699 if (oldGrabber == this)
4702 canvasPriv->itemForTouchPointId[ids.at(i)] = this;
4704 ungrab.insert(oldGrabber);
4706 foreach (QQuickItem *oldGrabber, ungrab)
4707 oldGrabber->touchUngrabEvent();
4711 Ungrabs the touch points owned by this item.
4713 \sa grabTouchPoints()
4715 void QQuickItem::ungrabTouchPoints()
4720 QQuickCanvasPrivate *canvasPriv = QQuickCanvasPrivate::get(d->canvas);
4722 QMutableHashIterator<int, QQuickItem*> i(canvasPriv->itemForTouchPointId);
4723 while (i.hasNext()) {
4725 if (i.value() == this)
4732 Returns a value indicating whether the touch points grabbed by this item
4733 should remain with this item exclusively.
4735 \sa setKeepTouchGrab(), keepMouseGrab()
4737 bool QQuickItem::keepTouchGrab() const
4739 Q_D(const QQuickItem);
4740 return d->keepTouch;
4744 The flag indicating whether the touch points grabbed
4745 by this item should remain with this item is set to \a keep.
4747 This is useful for items that wish to grab and keep specific touch
4748 points following a predefined gesture. For example,
4749 an item that is interested in horizontal touch point movement
4750 may set setKeepTouchGrab to true once a threshold has been
4751 exceeded. Once setKeepTouchGrab has been set to true, filtering
4752 items will not react to the relevant touch points.
4754 If the item does not indicate that it wishes to retain touch point grab,
4755 a filtering item may steal the grab. For example, Flickable may attempt
4756 to steal a touch point grab if it detects that the user has begun to
4759 \sa keepTouchGrab(), setKeepMouseGrab()
4761 void QQuickItem::setKeepTouchGrab(bool keep)
4764 d->keepTouch = keep;
4768 \qmlmethod object QtQuick2::Item::mapFromItem(Item item, real x, real y)
4770 Maps the point (\a x, \a y), which is in \a item's coordinate system, to
4771 this item's coordinate system, and returns an object with \c x and \c y
4772 properties matching the mapped coordinate.
4774 If \a item is a \c null value, this maps the point from the coordinate
4775 system of the root QML view.
4778 \qmlmethod object QtQuick2::Item::mapToItem(Item item, real x, real y)
4780 Maps the point (\a x, \a y), which is in this item's coordinate system, to
4781 \a item's coordinate system, and returns an object with \c x and \c y
4782 properties matching the mapped coordinate.
4784 If \a item is a \c null value, this maps \a x and \a y to the coordinate
4785 system of the root QML view.
4787 QPointF QQuickItem::mapToItem(const QQuickItem *item, const QPointF &point) const
4789 QPointF p = mapToScene(point);
4791 p = item->mapFromScene(p);
4795 QPointF QQuickItem::mapToScene(const QPointF &point) const
4797 Q_D(const QQuickItem);
4798 return d->itemToCanvasTransform().map(point);
4801 QRectF QQuickItem::mapRectToItem(const QQuickItem *item, const QRectF &rect) const
4803 Q_D(const QQuickItem);
4804 QTransform t = d->itemToCanvasTransform();
4806 t *= QQuickItemPrivate::get(item)->canvasToItemTransform();
4807 return t.mapRect(rect);
4810 QRectF QQuickItem::mapRectToScene(const QRectF &rect) const
4812 Q_D(const QQuickItem);
4813 return d->itemToCanvasTransform().mapRect(rect);
4816 QPointF QQuickItem::mapFromItem(const QQuickItem *item, const QPointF &point) const
4818 QPointF p = item?item->mapToScene(point):point;
4819 return mapFromScene(p);
4822 QPointF QQuickItem::mapFromScene(const QPointF &point) const
4824 Q_D(const QQuickItem);
4825 return d->canvasToItemTransform().map(point);
4828 QRectF QQuickItem::mapRectFromItem(const QQuickItem *item, const QRectF &rect) const
4830 Q_D(const QQuickItem);
4831 QTransform t = item?QQuickItemPrivate::get(item)->itemToCanvasTransform():QTransform();
4832 t *= d->canvasToItemTransform();
4833 return t.mapRect(rect);
4836 QRectF QQuickItem::mapRectFromScene(const QRectF &rect) const
4838 Q_D(const QQuickItem);
4839 return d->canvasToItemTransform().mapRect(rect);
4844 \qmlmethod QtQuick2::Item::forceActiveFocus()
4846 Forces active focus on the item.
4848 This method sets focus on the item and makes sure that all the focus scopes
4849 higher in the object hierarchy are also given the focus.
4853 Forces active focus on the item.
4855 This method sets focus on the item and makes sure that all the focus scopes
4856 higher in the object hierarchy are also given the focus.
4860 \qmlmethod QtQuick2::Item::childAt(real x, real y)
4862 Returns the visible child item at point (\a x, \a y), which is in this
4863 item's coordinate system, or \c null if there is no such item.
4867 Returns the visible child item at point (\a x, \a y), which is in this
4868 item's coordinate system, or 0 if there is no such item.
4872 \qmlproperty list<State> QtQuick2::Item::states
4873 This property holds a list of states defined by the item.
4889 \sa {qmlstate}{States}
4892 \qmlproperty list<Transition> QtQuick2::Item::transitions
4893 This property holds a list of transitions defined by the item.
4909 \sa {QML Animation and Transitions}{Transitions}
4912 \qmlproperty list<Filter> QtQuick2::Item::filter
4913 This property holds a list of graphical filters to be applied to the item.
4915 \l {Filter}{Filters} include things like \l {Blur}{blurring}
4916 the item, or giving it a \l Reflection. Some
4917 filters may not be available on all canvases; if a filter is not
4918 available on a certain canvas, it will simply not be applied for
4919 that canvas (but the QML will still be considered valid).
4937 \qmlproperty bool QtQuick2::Item::clip
4938 This property holds whether clipping is enabled. The default clip value is \c false.
4940 If clipping is enabled, an item will clip its own painting, as well
4941 as the painting of its children, to its bounding rectangle.
4943 Non-rectangular clipping regions are not supported for performance reasons.
4947 \property QQuickItem::clip
4948 This property holds whether clipping is enabled. The default clip value is \c false.
4950 If clipping is enabled, an item will clip its own painting, as well
4951 as the painting of its children, to its bounding rectangle. If you set
4952 clipping during an item's paint operation, remember to re-set it to
4953 prevent clipping the rest of your scene.
4955 Non-rectangular clipping regions are not supported for performance reasons.
4959 \qmlproperty string QtQuick2::Item::state
4961 This property holds the name of the current state of the item.
4963 This property is often used in scripts to change between states. For
4968 if (button.state == 'On')
4969 button.state = 'Off';
4971 button.state = 'On';
4975 If the item is in its base state (i.e. no explicit state has been
4976 set), \c state will be a blank string. Likewise, you can return an
4977 item to its base state by setting its current state to \c ''.
4979 \sa {qmlstates}{States}
4983 \qmlproperty list<Transform> QtQuick2::Item::transform
4984 This property holds the list of transformations to apply.
4986 For more information see \l Transform.
4990 \enum QQuickItem::TransformOrigin
4992 Controls the point about which simple transforms like scale apply.
4994 \value TopLeft The top-left corner of the item.
4995 \value Top The center point of the top of the item.
4996 \value TopRight The top-right corner of the item.
4997 \value Left The left most point of the vertical middle.
4998 \value Center The center of the item.
4999 \value Right The right most point of the vertical middle.
5000 \value BottomLeft The bottom-left corner of the item.
5001 \value Bottom The center point of the bottom of the item.
5002 \value BottomRight The bottom-right corner of the item.
5007 \qmlproperty bool QtQuick2::Item::activeFocus
5009 This property indicates whether the item has active focus.
5011 An item with active focus will receive keyboard input,
5012 or is a FocusScope ancestor of the item that will receive keyboard input.
5014 Usually, activeFocus is gained by setting focus on an item and its enclosing
5015 FocusScopes. In the following example \c input will have activeFocus.
5028 \sa focus, {qmlfocus}{Keyboard Focus}
5032 \qmlproperty bool QtQuick2::Item::focus
5033 This property indicates whether the item has focus within the enclosing focus scope. If true, this item
5034 will gain active focus when the enclosing focus scope gains active focus.
5035 In the following example, \c input will be given active focus when \c scope gains active focus.
5048 For the purposes of this property, the scene as a whole is assumed to act like a focus scope.
5049 On a practical level, that means the following QML will give active focus to \c input on startup.
5060 \sa activeFocus, {qmlfocus}{Keyboard Focus}
5065 \property QQuickItem::anchors
5070 \property QQuickItem::left
5075 \property QQuickItem::right
5080 \property QQuickItem::horizontalCenter
5085 \property QQuickItem::top
5090 \property QQuickItem::bottom
5095 \property QQuickItem::verticalCenter
5100 \property QQuickItem::focus
5105 \property QQuickItem::transform
5110 \property QQuickItem::transformOrigin
5115 \property QQuickItem::activeFocus
5120 \property QQuickItem::baseline
5125 \property QQuickItem::data
5130 \property QQuickItem::resources
5135 \property QQuickItem::state
5140 \property QQuickItem::states
5145 \property QQuickItem::transformOriginPoint
5150 \property QQuickItem::transitions
5154 bool QQuickItem::event(QEvent *ev)
5157 if (ev->type() == QEvent::PolishRequest) {
5159 d->polishScheduled = false;
5163 return QObject::event(ev);
5166 if (ev->type() == QEvent::InputMethodQuery) {
5167 QInputMethodQueryEvent *query = static_cast<QInputMethodQueryEvent *>(ev);
5168 Qt::InputMethodQueries queries = query->queries();
5169 for (uint i = 0; i < 32; ++i) {
5170 Qt::InputMethodQuery q = (Qt::InputMethodQuery)(int)(queries & (1<<i));
5172 QVariant v = inputMethodQuery(q);
5173 query->setValue(q, v);
5178 } else if (ev->type() == QEvent::InputMethod) {
5179 inputMethodEvent(static_cast<QInputMethodEvent *>(ev));
5182 return QObject::event(ev);
5185 #ifndef QT_NO_DEBUG_STREAM
5186 QDebug operator<<(QDebug debug, QQuickItem *item)
5189 debug << "QQuickItem(0)";
5193 debug << item->metaObject()->className() << "(this =" << ((void*)item)
5194 << ", name=" << item->objectName()
5195 << ", parent =" << ((void*)item->parentItem())
5196 << ", geometry =" << QRectF(item->pos(), QSizeF(item->width(), item->height()))
5197 << ", z =" << item->z() << ')';
5202 qint64 QQuickItemPrivate::consistentTime = -1;
5203 void QQuickItemPrivate::setConsistentTime(qint64 t)
5208 class QElapsedTimerConsistentTimeHack
5212 t1 = QQuickItemPrivate::consistentTime;
5216 return QQuickItemPrivate::consistentTime - t1;
5219 qint64 val = QQuickItemPrivate::consistentTime - t1;
5220 t1 = QQuickItemPrivate::consistentTime;
5230 void QQuickItemPrivate::start(QElapsedTimer &t)
5232 if (QQuickItemPrivate::consistentTime == -1)
5235 ((QElapsedTimerConsistentTimeHack*)&t)->start();
5238 qint64 QQuickItemPrivate::elapsed(QElapsedTimer &t)
5240 if (QQuickItemPrivate::consistentTime == -1)
5243 return ((QElapsedTimerConsistentTimeHack*)&t)->elapsed();
5246 qint64 QQuickItemPrivate::restart(QElapsedTimer &t)
5248 if (QQuickItemPrivate::consistentTime == -1)
5251 return ((QElapsedTimerConsistentTimeHack*)&t)->restart();
5255 \fn bool QQuickItem::isTextureProvider() const
5257 Returns true if this item is a texture provider. The default
5258 implementation returns false.
5260 This function can be called from any thread.
5264 \fn QSGTextureProvider *QQuickItem::textureProvider() const
5266 Returns the texture provider for an item. The default implementation
5269 This function may only be called on the rendering thread.
5274 #include <moc_qquickitem.cpp>