1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the QtQml module of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** GNU Lesser General Public License Usage
10 ** This file may be used under the terms of the GNU Lesser General Public
11 ** License version 2.1 as published by the Free Software Foundation and
12 ** appearing in the file LICENSE.LGPL included in the packaging of this
13 ** file. Please review the following information to ensure the GNU Lesser
14 ** General Public License version 2.1 requirements will be met:
15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
17 ** In addition, as a special exception, Nokia gives you certain additional
18 ** rights. These rights are described in the Nokia Qt LGPL Exception
19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
21 ** GNU General Public License Usage
22 ** Alternatively, this file may be used under the terms of the GNU General
23 ** Public License version 3.0 as published by the Free Software Foundation
24 ** and appearing in the file LICENSE.GPL included in the packaging of this
25 ** file. Please review the following information to ensure the GNU General
26 ** Public License version 3.0 requirements will be met:
27 ** http://www.gnu.org/copyleft/gpl.html.
30 ** Alternatively, this file may be used in accordance with the terms and
31 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
42 #include "qquickitem.h"
44 #include "qquickwindow.h"
45 #include <QtQml/qjsengine.h>
46 #include "qquickwindow_p.h"
48 #include "qquickevents_p_p.h"
49 #include "qquickscreen_p.h"
51 #include <QtQml/qqmlengine.h>
52 #include <QtQml/qqmlcomponent.h>
53 #include <QtQml/qqmlinfo.h>
54 #include <QtGui/qpen.h>
55 #include <QtGui/qguiapplication.h>
56 #include <QtGui/private/qguiapplication_p.h>
57 #include <QtGui/qinputmethod.h>
58 #include <QtCore/qdebug.h>
59 #include <QtCore/qcoreevent.h>
60 #include <QtCore/qnumeric.h>
62 #include <private/qqmlglobal_p.h>
63 #include <private/qqmlengine_p.h>
64 #include <QtQuick/private/qquickstategroup_p.h>
65 #include <private/qqmlopenmetaobject_p.h>
66 #include <QtQuick/private/qquickstate_p.h>
67 #include <private/qquickitem_p.h>
68 #include <private/qqmlaccessors_p.h>
69 #include <QtQuick/private/qquickaccessibleattached_p.h>
72 # include <QtGui/qcursor.h>
77 // XXX todo Check that elements that create items handle memory correctly after visual ownership change
82 void printFocusTree(QQuickItem *item, QQuickItem *scope = 0, int depth = 1);
83 void printFocusTree(QQuickItem *item, QQuickItem *scope, int depth)
86 << QByteArray(depth, '\t').constData()
87 << (scope && QQuickItemPrivate::get(scope)->subFocusItem == item ? '*' : ' ')
89 << item->hasActiveFocus()
90 << item->isFocusScope()
92 foreach (QQuickItem *child, item->childItems()) {
95 item->isFocusScope() || !scope ? item : scope,
96 item->isFocusScope() || !scope ? depth + 1 : depth);
101 static void QQuickItem_parentNotifier(QObject *o, intptr_t, QQmlNotifier **n)
103 QQuickItemPrivate *d = QQuickItemPrivate::get(static_cast<QQuickItem *>(o));
104 *n = &d->parentNotifier;
107 QML_PRIVATE_ACCESSOR(QQuickItem, QQuickItem *, parent, parentItem)
108 QML_PRIVATE_ACCESSOR(QQuickItem, qreal, x, x)
109 QML_PRIVATE_ACCESSOR(QQuickItem, qreal, y, y)
110 QML_PRIVATE_ACCESSOR(QQuickItem, qreal, width, width)
111 QML_PRIVATE_ACCESSOR(QQuickItem, qreal, height, height)
113 static QQmlAccessors QQuickItem_parent = { QQuickItem_parentRead, QQuickItem_parentNotifier };
114 static QQmlAccessors QQuickItem_x = { QQuickItem_xRead, 0 };
115 static QQmlAccessors QQuickItem_y = { QQuickItem_yRead, 0 };
116 static QQmlAccessors QQuickItem_width = { QQuickItem_widthRead, 0 };
117 static QQmlAccessors QQuickItem_height = { QQuickItem_heightRead, 0 };
119 QML_DECLARE_PROPERTIES(QQuickItem) {
120 { QML_PROPERTY_NAME(parent), 0, &QQuickItem_parent },
121 { QML_PROPERTY_NAME(x), 0, &QQuickItem_x },
122 { QML_PROPERTY_NAME(y), 0, &QQuickItem_y },
123 { QML_PROPERTY_NAME(width), 0, &QQuickItem_width },
124 { QML_PROPERTY_NAME(height), 0, &QQuickItem_height }
127 void QQuickItemPrivate::registerAccessorProperties()
129 QML_DEFINE_PROPERTIES(QQuickItem);
134 \instantiates QQuickTransform
135 \inqmlmodule QtQuick 2
136 \ingroup qtquick-visual-transforms
137 \brief For specifying advanced transformations on Items
139 The Transform type is a base type which cannot be instantiated directly.
140 The following concrete Transform types are available:
148 The Transform types let you create and control advanced transformations that can be configured
149 independently using specialized properties.
151 You can assign any number of Transforms to an \l Item. Each Transform is applied in order,
154 QQuickTransformPrivate::QQuickTransformPrivate()
158 QQuickTransform::QQuickTransform(QObject *parent)
159 : QObject(*(new QQuickTransformPrivate), parent)
163 QQuickTransform::QQuickTransform(QQuickTransformPrivate &dd, QObject *parent)
164 : QObject(dd, parent)
168 QQuickTransform::~QQuickTransform()
170 Q_D(QQuickTransform);
171 for (int ii = 0; ii < d->items.count(); ++ii) {
172 QQuickItemPrivate *p = QQuickItemPrivate::get(d->items.at(ii));
173 p->transforms.removeOne(this);
174 p->dirty(QQuickItemPrivate::Transform);
178 void QQuickTransform::update()
180 Q_D(QQuickTransform);
181 for (int ii = 0; ii < d->items.count(); ++ii) {
182 QQuickItemPrivate *p = QQuickItemPrivate::get(d->items.at(ii));
183 p->dirty(QQuickItemPrivate::Transform);
187 QQuickContents::QQuickContents(QQuickItem *item)
188 : m_item(item), m_x(0), m_y(0), m_width(0), m_height(0)
192 QQuickContents::~QQuickContents()
194 QList<QQuickItem *> children = m_item->childItems();
195 for (int i = 0; i < children.count(); ++i) {
196 QQuickItem *child = children.at(i);
197 QQuickItemPrivate::get(child)->removeItemChangeListener(this, QQuickItemPrivate::Geometry | QQuickItemPrivate::Destroyed);
201 bool QQuickContents::calcHeight(QQuickItem *changed)
204 qreal oldheight = m_height;
208 qreal bottom = oldy + oldheight;
209 qreal y = changed->y();
210 if (y + changed->height() > bottom)
211 bottom = y + changed->height();
215 m_height = bottom - top;
219 QList<QQuickItem *> children = m_item->childItems();
220 for (int i = 0; i < children.count(); ++i) {
221 QQuickItem *child = children.at(i);
222 qreal y = child->y();
223 if (y + child->height() > bottom)
224 bottom = y + child->height();
228 if (!children.isEmpty())
230 m_height = qMax(bottom - top, qreal(0.0));
233 return (m_height != oldheight || m_y != oldy);
236 bool QQuickContents::calcWidth(QQuickItem *changed)
239 qreal oldwidth = m_width;
243 qreal right = oldx + oldwidth;
244 qreal x = changed->x();
245 if (x + changed->width() > right)
246 right = x + changed->width();
250 m_width = right - left;
252 qreal left = FLT_MAX;
254 QList<QQuickItem *> children = m_item->childItems();
255 for (int i = 0; i < children.count(); ++i) {
256 QQuickItem *child = children.at(i);
257 qreal x = child->x();
258 if (x + child->width() > right)
259 right = x + child->width();
263 if (!children.isEmpty())
265 m_width = qMax(right - left, qreal(0.0));
268 return (m_width != oldwidth || m_x != oldx);
271 void QQuickContents::complete()
273 QQuickItemPrivate::get(m_item)->addItemChangeListener(this, QQuickItemPrivate::Children);
275 QList<QQuickItem *> children = m_item->childItems();
276 for (int i = 0; i < children.count(); ++i) {
277 QQuickItem *child = children.at(i);
278 QQuickItemPrivate::get(child)->addItemChangeListener(this, QQuickItemPrivate::Geometry | QQuickItemPrivate::Destroyed);
279 //###what about changes to visibility?
284 void QQuickContents::updateRect()
286 QQuickItemPrivate::get(m_item)->emitChildrenRectChanged(rectF());
289 void QQuickContents::itemGeometryChanged(QQuickItem *changed, const QRectF &newGeometry, const QRectF &oldGeometry)
292 bool wChanged = false;
293 bool hChanged = false;
294 //### we can only pass changed if the left edge has moved left, or the right edge has moved right
295 if (newGeometry.width() != oldGeometry.width() || newGeometry.x() != oldGeometry.x())
296 wChanged = calcWidth(/*changed*/);
297 if (newGeometry.height() != oldGeometry.height() || newGeometry.y() != oldGeometry.y())
298 hChanged = calcHeight(/*changed*/);
299 if (wChanged || hChanged)
303 void QQuickContents::itemDestroyed(QQuickItem *item)
306 QQuickItemPrivate::get(item)->removeItemChangeListener(this, QQuickItemPrivate::Geometry | QQuickItemPrivate::Destroyed);
310 void QQuickContents::itemChildRemoved(QQuickItem *, QQuickItem *item)
313 QQuickItemPrivate::get(item)->removeItemChangeListener(this, QQuickItemPrivate::Geometry | QQuickItemPrivate::Destroyed);
317 void QQuickContents::itemChildAdded(QQuickItem *, QQuickItem *item)
320 QQuickItemPrivate::get(item)->addItemChangeListener(this, QQuickItemPrivate::Geometry | QQuickItemPrivate::Destroyed);
324 QQuickItemKeyFilter::QQuickItemKeyFilter(QQuickItem *item)
325 : m_processPost(false), m_next(0)
327 QQuickItemPrivate *p = item?QQuickItemPrivate::get(item):0;
329 m_next = p->extra.value().keyHandler;
330 p->extra->keyHandler = this;
334 QQuickItemKeyFilter::~QQuickItemKeyFilter()
338 void QQuickItemKeyFilter::keyPressed(QKeyEvent *event, bool post)
340 if (m_next) m_next->keyPressed(event, post);
343 void QQuickItemKeyFilter::keyReleased(QKeyEvent *event, bool post)
345 if (m_next) m_next->keyReleased(event, post);
348 void QQuickItemKeyFilter::inputMethodEvent(QInputMethodEvent *event, bool post)
351 m_next->inputMethodEvent(event, post);
356 QVariant QQuickItemKeyFilter::inputMethodQuery(Qt::InputMethodQuery query) const
358 if (m_next) return m_next->inputMethodQuery(query);
362 void QQuickItemKeyFilter::componentComplete()
364 if (m_next) m_next->componentComplete();
367 \qmltype KeyNavigation
368 \instantiates QQuickKeyNavigationAttached
369 \inqmlmodule QtQuick 2
370 \ingroup qtquick-input
371 \brief Supports key navigation by arrow keys
373 Key-based user interfaces commonly allow the use of arrow keys to navigate between
374 focusable items. The KeyNavigation attached property enables this behavior by providing a
375 convenient way to specify the item that should gain focus when an arrow or tab key is pressed.
377 The following example provides key navigation for a 2x2 grid of items:
379 \snippet qml/keynavigation.qml 0
381 The top-left item initially receives focus by setting \l {Item::}{focus} to
382 \c true. When an arrow key is pressed, the focus will move to the
383 appropriate item, as defined by the value that has been set for
384 the KeyNavigation \l left, \l right, \l up or \l down properties.
386 Note that if a KeyNavigation attached property receives the key press and release
387 events for a requested arrow or tab key, the event is accepted and does not
388 propagate any further.
390 By default, KeyNavigation receives key events after the item to which it is attached.
391 If the item accepts the key event, the KeyNavigation attached property will not
392 receive an event for that key. Setting the \l priority property to
393 \c KeyNavigation.BeforeItem allows the event to be used for key navigation
394 before the item, rather than after.
396 If item to which the focus is switching is not enabled or visible, an attempt will
397 be made to skip this item and focus on the next. This is possible if there are
398 a chain of items with the same KeyNavigation handler. If multiple items in a row are not enabled
399 or visible, they will also be skipped.
401 KeyNavigation will implicitly set the other direction to return focus to this item. So if you set
402 \l left to another item, \l right will be set on that item's KeyNavigation to set focus back to this
403 item. However, if that item's KeyNavigation has had right explicitly set then no change will occur.
404 This means that the above example could have been written, with the same behaviour, without specifing
405 KeyNavigation.right or KeyNavigation.down for any of the items.
407 \sa {Keys}{Keys attached property}
411 \qmlproperty Item QtQuick2::KeyNavigation::left
412 \qmlproperty Item QtQuick2::KeyNavigation::right
413 \qmlproperty Item QtQuick2::KeyNavigation::up
414 \qmlproperty Item QtQuick2::KeyNavigation::down
416 These properties hold the item to assign focus to
417 when the left, right, up or down cursor keys
422 \qmlproperty Item QtQuick2::KeyNavigation::tab
423 \qmlproperty Item QtQuick2::KeyNavigation::backtab
425 These properties hold the item to assign focus to
426 when the Tab key or Shift+Tab key combination (Backtab) are pressed.
429 QQuickKeyNavigationAttached::QQuickKeyNavigationAttached(QObject *parent)
430 : QObject(*(new QQuickKeyNavigationAttachedPrivate), parent),
431 QQuickItemKeyFilter(qmlobject_cast<QQuickItem*>(parent))
433 m_processPost = true;
436 QQuickKeyNavigationAttached *
437 QQuickKeyNavigationAttached::qmlAttachedProperties(QObject *obj)
439 return new QQuickKeyNavigationAttached(obj);
442 QQuickItem *QQuickKeyNavigationAttached::left() const
444 Q_D(const QQuickKeyNavigationAttached);
448 void QQuickKeyNavigationAttached::setLeft(QQuickItem *i)
450 Q_D(QQuickKeyNavigationAttached);
455 QQuickKeyNavigationAttached* other =
456 qobject_cast<QQuickKeyNavigationAttached*>(qmlAttachedPropertiesObject<QQuickKeyNavigationAttached>(i));
457 if (other && !other->d_func()->rightSet){
458 other->d_func()->right = qobject_cast<QQuickItem*>(parent());
459 emit other->rightChanged();
464 QQuickItem *QQuickKeyNavigationAttached::right() const
466 Q_D(const QQuickKeyNavigationAttached);
470 void QQuickKeyNavigationAttached::setRight(QQuickItem *i)
472 Q_D(QQuickKeyNavigationAttached);
477 QQuickKeyNavigationAttached* other =
478 qobject_cast<QQuickKeyNavigationAttached*>(qmlAttachedPropertiesObject<QQuickKeyNavigationAttached>(i));
479 if (other && !other->d_func()->leftSet){
480 other->d_func()->left = qobject_cast<QQuickItem*>(parent());
481 emit other->leftChanged();
486 QQuickItem *QQuickKeyNavigationAttached::up() const
488 Q_D(const QQuickKeyNavigationAttached);
492 void QQuickKeyNavigationAttached::setUp(QQuickItem *i)
494 Q_D(QQuickKeyNavigationAttached);
499 QQuickKeyNavigationAttached* other =
500 qobject_cast<QQuickKeyNavigationAttached*>(qmlAttachedPropertiesObject<QQuickKeyNavigationAttached>(i));
501 if (other && !other->d_func()->downSet){
502 other->d_func()->down = qobject_cast<QQuickItem*>(parent());
503 emit other->downChanged();
508 QQuickItem *QQuickKeyNavigationAttached::down() const
510 Q_D(const QQuickKeyNavigationAttached);
514 void QQuickKeyNavigationAttached::setDown(QQuickItem *i)
516 Q_D(QQuickKeyNavigationAttached);
521 QQuickKeyNavigationAttached* other =
522 qobject_cast<QQuickKeyNavigationAttached*>(qmlAttachedPropertiesObject<QQuickKeyNavigationAttached>(i));
523 if (other && !other->d_func()->upSet) {
524 other->d_func()->up = qobject_cast<QQuickItem*>(parent());
525 emit other->upChanged();
530 QQuickItem *QQuickKeyNavigationAttached::tab() const
532 Q_D(const QQuickKeyNavigationAttached);
536 void QQuickKeyNavigationAttached::setTab(QQuickItem *i)
538 Q_D(QQuickKeyNavigationAttached);
543 QQuickKeyNavigationAttached* other =
544 qobject_cast<QQuickKeyNavigationAttached*>(qmlAttachedPropertiesObject<QQuickKeyNavigationAttached>(i));
545 if (other && !other->d_func()->backtabSet) {
546 other->d_func()->backtab = qobject_cast<QQuickItem*>(parent());
547 emit other->backtabChanged();
552 QQuickItem *QQuickKeyNavigationAttached::backtab() const
554 Q_D(const QQuickKeyNavigationAttached);
558 void QQuickKeyNavigationAttached::setBacktab(QQuickItem *i)
560 Q_D(QQuickKeyNavigationAttached);
564 d->backtabSet = true;
565 QQuickKeyNavigationAttached* other =
566 qobject_cast<QQuickKeyNavigationAttached*>(qmlAttachedPropertiesObject<QQuickKeyNavigationAttached>(i));
567 if (other && !other->d_func()->tabSet) {
568 other->d_func()->tab = qobject_cast<QQuickItem*>(parent());
569 emit other->tabChanged();
571 emit backtabChanged();
575 \qmlproperty enumeration QtQuick2::KeyNavigation::priority
577 This property determines whether the keys are processed before
578 or after the attached item's own key handling.
581 \li KeyNavigation.BeforeItem - process the key events before normal
582 item key processing. If the event is used for key navigation, it will be accepted and will not
583 be passed on to the item.
584 \li KeyNavigation.AfterItem (default) - process the key events after normal item key
585 handling. If the item accepts the key event it will not be
586 handled by the KeyNavigation attached property handler.
589 QQuickKeyNavigationAttached::Priority QQuickKeyNavigationAttached::priority() const
591 return m_processPost ? AfterItem : BeforeItem;
594 void QQuickKeyNavigationAttached::setPriority(Priority order)
596 bool processPost = order == AfterItem;
597 if (processPost != m_processPost) {
598 m_processPost = processPost;
599 emit priorityChanged();
603 void QQuickKeyNavigationAttached::keyPressed(QKeyEvent *event, bool post)
605 Q_D(QQuickKeyNavigationAttached);
608 if (post != m_processPost) {
609 QQuickItemKeyFilter::keyPressed(event, post);
614 switch (event->key()) {
616 if (QQuickItem *parentItem = qobject_cast<QQuickItem*>(parent()))
617 mirror = QQuickItemPrivate::get(parentItem)->effectiveLayoutMirror;
618 QQuickItem* leftItem = mirror ? d->right : d->left;
620 setFocusNavigation(leftItem, mirror ? "right" : "left");
625 case Qt::Key_Right: {
626 if (QQuickItem *parentItem = qobject_cast<QQuickItem*>(parent()))
627 mirror = QQuickItemPrivate::get(parentItem)->effectiveLayoutMirror;
628 QQuickItem* rightItem = mirror ? d->left : d->right;
630 setFocusNavigation(rightItem, mirror ? "left" : "right");
637 setFocusNavigation(d->up, "up");
643 setFocusNavigation(d->down, "down");
649 setFocusNavigation(d->tab, "tab");
653 case Qt::Key_Backtab:
655 setFocusNavigation(d->backtab, "backtab");
663 if (!event->isAccepted()) QQuickItemKeyFilter::keyPressed(event, post);
666 void QQuickKeyNavigationAttached::keyReleased(QKeyEvent *event, bool post)
668 Q_D(QQuickKeyNavigationAttached);
671 if (post != m_processPost) {
672 QQuickItemKeyFilter::keyReleased(event, post);
677 switch (event->key()) {
679 if (QQuickItem *parentItem = qobject_cast<QQuickItem*>(parent()))
680 mirror = QQuickItemPrivate::get(parentItem)->effectiveLayoutMirror;
681 if (mirror ? d->right : d->left)
685 if (QQuickItem *parentItem = qobject_cast<QQuickItem*>(parent()))
686 mirror = QQuickItemPrivate::get(parentItem)->effectiveLayoutMirror;
687 if (mirror ? d->left : d->right)
705 case Qt::Key_Backtab:
714 if (!event->isAccepted()) QQuickItemKeyFilter::keyReleased(event, post);
717 void QQuickKeyNavigationAttached::setFocusNavigation(QQuickItem *currentItem, const char *dir)
719 QQuickItem *initialItem = currentItem;
720 bool isNextItem = false;
723 if (currentItem->isVisible() && currentItem->isEnabled()) {
724 currentItem->setFocus(true);
727 qmlAttachedPropertiesObject<QQuickKeyNavigationAttached>(currentItem, false);
729 QQuickItem *tempItem = qvariant_cast<QQuickItem*>(attached->property(dir));
731 currentItem = tempItem;
737 while (currentItem != initialItem && isNextItem);
740 const QQuickKeysAttached::SigMap QQuickKeysAttached::sigMap[] = {
741 { Qt::Key_Left, "leftPressed" },
742 { Qt::Key_Right, "rightPressed" },
743 { Qt::Key_Up, "upPressed" },
744 { Qt::Key_Down, "downPressed" },
745 { Qt::Key_Tab, "tabPressed" },
746 { Qt::Key_Backtab, "backtabPressed" },
747 { Qt::Key_Asterisk, "asteriskPressed" },
748 { Qt::Key_NumberSign, "numberSignPressed" },
749 { Qt::Key_Escape, "escapePressed" },
750 { Qt::Key_Return, "returnPressed" },
751 { Qt::Key_Enter, "enterPressed" },
752 { Qt::Key_Delete, "deletePressed" },
753 { Qt::Key_Space, "spacePressed" },
754 { Qt::Key_Back, "backPressed" },
755 { Qt::Key_Cancel, "cancelPressed" },
756 { Qt::Key_Select, "selectPressed" },
757 { Qt::Key_Yes, "yesPressed" },
758 { Qt::Key_No, "noPressed" },
759 { Qt::Key_Context1, "context1Pressed" },
760 { Qt::Key_Context2, "context2Pressed" },
761 { Qt::Key_Context3, "context3Pressed" },
762 { Qt::Key_Context4, "context4Pressed" },
763 { Qt::Key_Call, "callPressed" },
764 { Qt::Key_Hangup, "hangupPressed" },
765 { Qt::Key_Flip, "flipPressed" },
766 { Qt::Key_Menu, "menuPressed" },
767 { Qt::Key_VolumeUp, "volumeUpPressed" },
768 { Qt::Key_VolumeDown, "volumeDownPressed" },
772 bool QQuickKeysAttached::isConnected(const char *signalName)
774 Q_D(QQuickKeysAttached);
775 int signal_index = d->signalIndex(signalName);
776 return d->isSignalConnected(signal_index);
781 \instantiates QQuickKeysAttached
782 \inqmlmodule QtQuick 2
783 \ingroup qtquick-input
784 \brief Provides key handling to Items
786 All visual primitives support key handling via the Keys
787 attached property. Keys can be handled via the onPressed
788 and onReleased signal properties.
790 The signal properties have a \l KeyEvent parameter, named
791 \e event which contains details of the event. If a key is
792 handled \e event.accepted should be set to true to prevent the
793 event from propagating up the item hierarchy.
795 \section1 Example Usage
797 The following example shows how the general onPressed handler can
798 be used to test for a certain key; in this case, the left cursor
801 \snippet qml/keys/keys-pressed.qml key item
803 Some keys may alternatively be handled via specific signal properties,
804 for example \e onSelectPressed. These handlers automatically set
805 \e event.accepted to true.
807 \snippet qml/keys/keys-handler.qml key item
809 See \l{Qt::Key}{Qt.Key} for the list of keyboard codes.
811 \section1 Key Handling Priorities
813 The Keys attached property can be configured to handle key events
814 before or after the item it is attached to. This makes it possible
815 to intercept events in order to override an item's default behavior,
816 or act as a fallback for keys not handled by the item.
818 If \l priority is Keys.BeforeItem (default) the order of key event processing is:
821 \li Items specified in \c forwardTo
822 \li specific key handlers, e.g. onReturnPressed
823 \li onKeyPress, onKeyRelease handlers
824 \li Item specific key handling, e.g. TextInput key handling
828 If priority is Keys.AfterItem the order of key event processing is:
831 \li Item specific key handling, e.g. TextInput key handling
832 \li Items specified in \c forwardTo
833 \li specific key handlers, e.g. onReturnPressed
834 \li onKeyPress, onKeyRelease handlers
838 If the event is accepted during any of the above steps, key
841 \sa KeyEvent, {KeyNavigation}{KeyNavigation attached property}
845 \qmlproperty bool QtQuick2::Keys::enabled
847 This flags enables key handling if true (default); otherwise
848 no key handlers will be called.
852 \qmlproperty enumeration QtQuick2::Keys::priority
854 This property determines whether the keys are processed before
855 or after the attached item's own key handling.
858 \li Keys.BeforeItem (default) - process the key events before normal
859 item key processing. If the event is accepted it will not
860 be passed on to the item.
861 \li Keys.AfterItem - process the key events after normal item key
862 handling. If the item accepts the key event it will not be
863 handled by the Keys attached property handler.
868 \qmlproperty list<Object> QtQuick2::Keys::forwardTo
870 This property provides a way to forward key presses, key releases, and keyboard input
871 coming from input methods to other items. This can be useful when you want
872 one item to handle some keys (e.g. the up and down arrow keys), and another item to
873 handle other keys (e.g. the left and right arrow keys). Once an item that has been
874 forwarded keys accepts the event it is no longer forwarded to items later in the
877 This example forwards key events to two lists:
888 Keys.forwardTo: [list1, list2]
895 \qmlsignal QtQuick2::Keys::onPressed(KeyEvent event)
897 This handler is called when a key has been pressed. The \a event
898 parameter provides information about the event.
902 \qmlsignal QtQuick2::Keys::onReleased(KeyEvent event)
904 This handler is called when a key has been released. The \a event
905 parameter provides information about the event.
909 \qmlsignal QtQuick2::Keys::onDigit0Pressed(KeyEvent event)
911 This handler is called when the digit '0' has been pressed. The \a event
912 parameter provides information about the event.
916 \qmlsignal QtQuick2::Keys::onDigit1Pressed(KeyEvent event)
918 This handler is called when the digit '1' has been pressed. The \a event
919 parameter provides information about the event.
923 \qmlsignal QtQuick2::Keys::onDigit2Pressed(KeyEvent event)
925 This handler is called when the digit '2' has been pressed. The \a event
926 parameter provides information about the event.
930 \qmlsignal QtQuick2::Keys::onDigit3Pressed(KeyEvent event)
932 This handler is called when the digit '3' has been pressed. The \a event
933 parameter provides information about the event.
937 \qmlsignal QtQuick2::Keys::onDigit4Pressed(KeyEvent event)
939 This handler is called when the digit '4' has been pressed. The \a event
940 parameter provides information about the event.
944 \qmlsignal QtQuick2::Keys::onDigit5Pressed(KeyEvent event)
946 This handler is called when the digit '5' has been pressed. The \a event
947 parameter provides information about the event.
951 \qmlsignal QtQuick2::Keys::onDigit6Pressed(KeyEvent event)
953 This handler is called when the digit '6' has been pressed. The \a event
954 parameter provides information about the event.
958 \qmlsignal QtQuick2::Keys::onDigit7Pressed(KeyEvent event)
960 This handler is called when the digit '7' has been pressed. The \a event
961 parameter provides information about the event.
965 \qmlsignal QtQuick2::Keys::onDigit8Pressed(KeyEvent event)
967 This handler is called when the digit '8' has been pressed. The \a event
968 parameter provides information about the event.
972 \qmlsignal QtQuick2::Keys::onDigit9Pressed(KeyEvent event)
974 This handler is called when the digit '9' has been pressed. The \a event
975 parameter provides information about the event.
979 \qmlsignal QtQuick2::Keys::onLeftPressed(KeyEvent event)
981 This handler is called when the Left arrow has been pressed. The \a event
982 parameter provides information about the event.
986 \qmlsignal QtQuick2::Keys::onRightPressed(KeyEvent event)
988 This handler is called when the Right arrow has been pressed. The \a event
989 parameter provides information about the event.
993 \qmlsignal QtQuick2::Keys::onUpPressed(KeyEvent event)
995 This handler is called when the Up arrow has been pressed. The \a event
996 parameter provides information about the event.
1000 \qmlsignal QtQuick2::Keys::onDownPressed(KeyEvent event)
1002 This handler is called when the Down arrow has been pressed. The \a event
1003 parameter provides information about the event.
1007 \qmlsignal QtQuick2::Keys::onTabPressed(KeyEvent event)
1009 This handler is called when the Tab key has been pressed. The \a event
1010 parameter provides information about the event.
1014 \qmlsignal QtQuick2::Keys::onBacktabPressed(KeyEvent event)
1016 This handler is called when the Shift+Tab key combination (Backtab) has
1017 been pressed. The \a event parameter provides information about the event.
1021 \qmlsignal QtQuick2::Keys::onAsteriskPressed(KeyEvent event)
1023 This handler is called when the Asterisk '*' has been pressed. The \a event
1024 parameter provides information about the event.
1028 \qmlsignal QtQuick2::Keys::onEscapePressed(KeyEvent event)
1030 This handler is called when the Escape key has been pressed. The \a event
1031 parameter provides information about the event.
1035 \qmlsignal QtQuick2::Keys::onReturnPressed(KeyEvent event)
1037 This handler is called when the Return key has been pressed. The \a event
1038 parameter provides information about the event.
1042 \qmlsignal QtQuick2::Keys::onEnterPressed(KeyEvent event)
1044 This handler is called when the Enter key has been pressed. The \a event
1045 parameter provides information about the event.
1049 \qmlsignal QtQuick2::Keys::onDeletePressed(KeyEvent event)
1051 This handler is called when the Delete key has been pressed. The \a event
1052 parameter provides information about the event.
1056 \qmlsignal QtQuick2::Keys::onSpacePressed(KeyEvent event)
1058 This handler is called when the Space key has been pressed. The \a event
1059 parameter provides information about the event.
1063 \qmlsignal QtQuick2::Keys::onBackPressed(KeyEvent event)
1065 This handler is called when the Back key has been pressed. The \a event
1066 parameter provides information about the event.
1070 \qmlsignal QtQuick2::Keys::onCancelPressed(KeyEvent event)
1072 This handler is called when the Cancel key has been pressed. The \a event
1073 parameter provides information about the event.
1077 \qmlsignal QtQuick2::Keys::onSelectPressed(KeyEvent event)
1079 This handler is called when the Select key has been pressed. The \a event
1080 parameter provides information about the event.
1084 \qmlsignal QtQuick2::Keys::onYesPressed(KeyEvent event)
1086 This handler is called when the Yes key has been pressed. The \a event
1087 parameter provides information about the event.
1091 \qmlsignal QtQuick2::Keys::onNoPressed(KeyEvent event)
1093 This handler is called when the No key has been pressed. The \a event
1094 parameter provides information about the event.
1098 \qmlsignal QtQuick2::Keys::onContext1Pressed(KeyEvent event)
1100 This handler is called when the Context1 key has been pressed. The \a event
1101 parameter provides information about the event.
1105 \qmlsignal QtQuick2::Keys::onContext2Pressed(KeyEvent event)
1107 This handler is called when the Context2 key has been pressed. The \a event
1108 parameter provides information about the event.
1112 \qmlsignal QtQuick2::Keys::onContext3Pressed(KeyEvent event)
1114 This handler is called when the Context3 key has been pressed. The \a event
1115 parameter provides information about the event.
1119 \qmlsignal QtQuick2::Keys::onContext4Pressed(KeyEvent event)
1121 This handler is called when the Context4 key has been pressed. The \a event
1122 parameter provides information about the event.
1126 \qmlsignal QtQuick2::Keys::onCallPressed(KeyEvent event)
1128 This handler is called when the Call key has been pressed. The \a event
1129 parameter provides information about the event.
1133 \qmlsignal QtQuick2::Keys::onHangupPressed(KeyEvent event)
1135 This handler is called when the Hangup key has been pressed. The \a event
1136 parameter provides information about the event.
1140 \qmlsignal QtQuick2::Keys::onFlipPressed(KeyEvent event)
1142 This handler is called when the Flip key has been pressed. The \a event
1143 parameter provides information about the event.
1147 \qmlsignal QtQuick2::Keys::onMenuPressed(KeyEvent event)
1149 This handler is called when the Menu key has been pressed. The \a event
1150 parameter provides information about the event.
1154 \qmlsignal QtQuick2::Keys::onVolumeUpPressed(KeyEvent event)
1156 This handler is called when the VolumeUp key has been pressed. The \a event
1157 parameter provides information about the event.
1161 \qmlsignal QtQuick2::Keys::onVolumeDownPressed(KeyEvent event)
1163 This handler is called when the VolumeDown key has been pressed. The \a event
1164 parameter provides information about the event.
1167 QQuickKeysAttached::QQuickKeysAttached(QObject *parent)
1168 : QObject(*(new QQuickKeysAttachedPrivate), parent),
1169 QQuickItemKeyFilter(qmlobject_cast<QQuickItem*>(parent))
1171 Q_D(QQuickKeysAttached);
1172 m_processPost = false;
1173 d->item = qmlobject_cast<QQuickItem*>(parent);
1176 QQuickKeysAttached::~QQuickKeysAttached()
1180 QQuickKeysAttached::Priority QQuickKeysAttached::priority() const
1182 return m_processPost ? AfterItem : BeforeItem;
1185 void QQuickKeysAttached::setPriority(Priority order)
1187 bool processPost = order == AfterItem;
1188 if (processPost != m_processPost) {
1189 m_processPost = processPost;
1190 emit priorityChanged();
1194 void QQuickKeysAttached::componentComplete()
1196 Q_D(QQuickKeysAttached);
1198 for (int ii = 0; ii < d->targets.count(); ++ii) {
1199 QQuickItem *targetItem = d->targets.at(ii);
1200 if (targetItem && (targetItem->flags() & QQuickItem::ItemAcceptsInputMethod)) {
1201 d->item->setFlag(QQuickItem::ItemAcceptsInputMethod);
1208 void QQuickKeysAttached::keyPressed(QKeyEvent *event, bool post)
1210 Q_D(QQuickKeysAttached);
1211 if (post != m_processPost || !d->enabled || d->inPress) {
1213 QQuickItemKeyFilter::keyPressed(event, post);
1217 // first process forwards
1218 if (d->item && d->item->window()) {
1220 for (int ii = 0; ii < d->targets.count(); ++ii) {
1221 QQuickItem *i = d->targets.at(ii);
1222 if (i && i->isVisible()) {
1223 d->item->window()->sendEvent(i, event);
1224 if (event->isAccepted()) {
1233 QQuickKeyEvent ke(*event);
1234 QByteArray keySignal = keyToSignal(event->key());
1235 if (!keySignal.isEmpty()) {
1236 keySignal += "(QQuickKeyEvent*)";
1237 if (isConnected(keySignal)) {
1238 // If we specifically handle a key then default to accepted
1239 ke.setAccepted(true);
1240 int idx = QQuickKeysAttached::staticMetaObject.indexOfSignal(keySignal);
1241 metaObject()->method(idx).invoke(this, Qt::DirectConnection, Q_ARG(QQuickKeyEvent*, &ke));
1244 if (!ke.isAccepted())
1246 event->setAccepted(ke.isAccepted());
1248 if (!event->isAccepted()) QQuickItemKeyFilter::keyPressed(event, post);
1251 void QQuickKeysAttached::keyReleased(QKeyEvent *event, bool post)
1253 Q_D(QQuickKeysAttached);
1254 if (post != m_processPost || !d->enabled || d->inRelease) {
1256 QQuickItemKeyFilter::keyReleased(event, post);
1260 if (d->item && d->item->window()) {
1261 d->inRelease = true;
1262 for (int ii = 0; ii < d->targets.count(); ++ii) {
1263 QQuickItem *i = d->targets.at(ii);
1264 if (i && i->isVisible()) {
1265 d->item->window()->sendEvent(i, event);
1266 if (event->isAccepted()) {
1267 d->inRelease = false;
1272 d->inRelease = false;
1275 QQuickKeyEvent ke(*event);
1277 event->setAccepted(ke.isAccepted());
1279 if (!event->isAccepted()) QQuickItemKeyFilter::keyReleased(event, post);
1282 void QQuickKeysAttached::inputMethodEvent(QInputMethodEvent *event, bool post)
1284 Q_D(QQuickKeysAttached);
1285 if (post == m_processPost && d->item && !d->inIM && d->item->window()) {
1287 for (int ii = 0; ii < d->targets.count(); ++ii) {
1288 QQuickItem *i = d->targets.at(ii);
1289 if (i && i->isVisible() && (i->flags() & QQuickItem::ItemAcceptsInputMethod)) {
1290 d->item->window()->sendEvent(i, event);
1291 if (event->isAccepted()) {
1300 QQuickItemKeyFilter::inputMethodEvent(event, post);
1303 QVariant QQuickKeysAttached::inputMethodQuery(Qt::InputMethodQuery query) const
1305 Q_D(const QQuickKeysAttached);
1307 for (int ii = 0; ii < d->targets.count(); ++ii) {
1308 QQuickItem *i = d->targets.at(ii);
1309 if (i && i->isVisible() && (i->flags() & QQuickItem::ItemAcceptsInputMethod) && i == d->imeItem) {
1310 //### how robust is i == d->imeItem check?
1311 QVariant v = i->inputMethodQuery(query);
1312 if (v.userType() == QVariant::RectF)
1313 v = d->item->mapRectFromItem(i, v.toRectF()); //### cost?
1318 return QQuickItemKeyFilter::inputMethodQuery(query);
1321 QQuickKeysAttached *QQuickKeysAttached::qmlAttachedProperties(QObject *obj)
1323 return new QQuickKeysAttached(obj);
1327 \qmltype LayoutMirroring
1328 \instantiates QQuickLayoutMirroringAttached
1329 \inqmlmodule QtQuick 2
1330 \ingroup qtquick-positioners
1331 \ingroup qml-utility-elements
1332 \brief Property used to mirror layout behavior
1334 The LayoutMirroring attached property is used to horizontally mirror \l {anchor-layout}{Item anchors},
1335 \l{Item Layouts}{positioner} types (such as \l Row and \l Grid)
1336 and views (such as \l GridView and horizontal \l ListView). Mirroring is a visual change: left
1337 anchors become right anchors, and positioner types like \l Grid and \l Row reverse the
1338 horizontal layout of child items.
1340 Mirroring is enabled for an item by setting the \l enabled property to true. By default, this
1341 only affects the item itself; setting the \l childrenInherit property to true propagates the mirroring
1342 behavior to all child items as well. If the \c LayoutMirroring attached property has not been defined
1343 for an item, mirroring is not enabled.
1345 The following example shows mirroring in action. The \l Row below is specified as being anchored
1346 to the left of its parent. However, since mirroring has been enabled, the anchor is horizontally
1347 reversed and it is now anchored to the right. Also, since items in a \l Row are positioned
1348 from left to right by default, they are now positioned from right to left instead, as demonstrated
1349 by the numbering and opacity of the items:
1351 \snippet qml/layoutmirroring.qml 0
1353 \image layoutmirroring.png
1355 Layout mirroring is useful when it is necessary to support both left-to-right and right-to-left
1356 layout versions of an application to target different language areas. The \l childrenInherit
1357 property allows layout mirroring to be applied without manually setting layout configurations
1358 for every item in an application. Keep in mind, however, that mirroring does not affect any
1359 positioning that is defined by the \l Item \l {Item::}{x} coordinate value, so even with
1360 mirroring enabled, it will often be necessary to apply some layout fixes to support the
1361 desired layout direction. Also, it may be necessary to disable the mirroring of individual
1362 child items (by setting \l {enabled}{LayoutMirroring.enabled} to false for such items) if
1363 mirroring is not the desired behavior, or if the child item already implements mirroring in
1366 See \l {Right-to-left User Interfaces} for further details on using \c LayoutMirroring and
1367 other related features to implement right-to-left support for an application.
1371 \qmlproperty bool QtQuick2::LayoutMirroring::enabled
1373 This property holds whether the item's layout is mirrored horizontally. Setting this to true
1374 horizontally reverses \l {anchor-layout}{anchor} settings such that left anchors become right,
1375 and right anchors become left. For \l{Item Layouts}{positioner} types
1376 (such as \l Row and \l Grid) and view types (such as \l {GridView}{GridView} and \l {ListView}{ListView})
1377 this also mirrors the horizontal layout direction of the item.
1379 The default value is false.
1383 \qmlproperty bool QtQuick2::LayoutMirroring::childrenInherit
1385 This property holds whether the \l {enabled}{LayoutMirroring.enabled} value for this item
1386 is inherited by its children.
1388 The default value is false.
1392 QQuickLayoutMirroringAttached::QQuickLayoutMirroringAttached(QObject *parent) : QObject(parent), itemPrivate(0)
1394 if (QQuickItem *item = qobject_cast<QQuickItem*>(parent)) {
1395 itemPrivate = QQuickItemPrivate::get(item);
1396 itemPrivate->extra.value().layoutDirectionAttached = this;
1398 qmlInfo(parent) << tr("LayoutDirection attached property only works with Items");
1401 QQuickLayoutMirroringAttached * QQuickLayoutMirroringAttached::qmlAttachedProperties(QObject *object)
1403 return new QQuickLayoutMirroringAttached(object);
1406 bool QQuickLayoutMirroringAttached::enabled() const
1408 return itemPrivate ? itemPrivate->effectiveLayoutMirror : false;
1411 void QQuickLayoutMirroringAttached::setEnabled(bool enabled)
1416 itemPrivate->isMirrorImplicit = false;
1417 if (enabled != itemPrivate->effectiveLayoutMirror) {
1418 itemPrivate->setLayoutMirror(enabled);
1419 if (itemPrivate->inheritMirrorFromItem)
1420 itemPrivate->resolveLayoutMirror();
1424 void QQuickLayoutMirroringAttached::resetEnabled()
1426 if (itemPrivate && !itemPrivate->isMirrorImplicit) {
1427 itemPrivate->isMirrorImplicit = true;
1428 itemPrivate->resolveLayoutMirror();
1432 bool QQuickLayoutMirroringAttached::childrenInherit() const
1434 return itemPrivate ? itemPrivate->inheritMirrorFromItem : false;
1437 void QQuickLayoutMirroringAttached::setChildrenInherit(bool childrenInherit) {
1438 if (itemPrivate && childrenInherit != itemPrivate->inheritMirrorFromItem) {
1439 itemPrivate->inheritMirrorFromItem = childrenInherit;
1440 itemPrivate->resolveLayoutMirror();
1441 childrenInheritChanged();
1445 void QQuickItemPrivate::resolveLayoutMirror()
1448 if (QQuickItem *parentItem = q->parentItem()) {
1449 QQuickItemPrivate *parentPrivate = QQuickItemPrivate::get(parentItem);
1450 setImplicitLayoutMirror(parentPrivate->inheritedLayoutMirror, parentPrivate->inheritMirrorFromParent);
1452 setImplicitLayoutMirror(isMirrorImplicit ? false : effectiveLayoutMirror, inheritMirrorFromItem);
1456 void QQuickItemPrivate::setImplicitLayoutMirror(bool mirror, bool inherit)
1458 inherit = inherit || inheritMirrorFromItem;
1459 if (!isMirrorImplicit && inheritMirrorFromItem)
1460 mirror = effectiveLayoutMirror;
1461 if (mirror == inheritedLayoutMirror && inherit == inheritMirrorFromParent)
1464 inheritMirrorFromParent = inherit;
1465 inheritedLayoutMirror = inheritMirrorFromParent ? mirror : false;
1467 if (isMirrorImplicit)
1468 setLayoutMirror(inherit ? inheritedLayoutMirror : false);
1469 for (int i = 0; i < childItems.count(); ++i) {
1470 if (QQuickItem *child = qmlobject_cast<QQuickItem *>(childItems.at(i))) {
1471 QQuickItemPrivate *childPrivate = QQuickItemPrivate::get(child);
1472 childPrivate->setImplicitLayoutMirror(inheritedLayoutMirror, inheritMirrorFromParent);
1477 void QQuickItemPrivate::setLayoutMirror(bool mirror)
1479 if (mirror != effectiveLayoutMirror) {
1480 effectiveLayoutMirror = mirror;
1482 QQuickAnchorsPrivate *anchor_d = QQuickAnchorsPrivate::get(_anchors);
1483 anchor_d->fillChanged();
1484 anchor_d->centerInChanged();
1485 anchor_d->updateHorizontalAnchors();
1488 if (extra.isAllocated() && extra->layoutDirectionAttached) {
1489 emit extra->layoutDirectionAttached->enabledChanged();
1494 void QQuickItemPrivate::setAccessibleFlagAndListener()
1497 QQuickItem *item = q;
1499 if (item->d_func()->isAccessible)
1500 break; // already set - grandparents should have the flag set as well.
1502 item->d_func()->isAccessible = true;
1503 item = item->d_func()->parentItem;
1507 void QQuickItemPrivate::updateSubFocusItem(QQuickItem *scope, bool focus)
1512 QQuickItemPrivate *scopePrivate = QQuickItemPrivate::get(scope);
1514 QQuickItem *oldSubFocusItem = scopePrivate->subFocusItem;
1515 // Correct focus chain in scope
1516 if (oldSubFocusItem) {
1517 QQuickItem *sfi = scopePrivate->subFocusItem->parentItem();
1518 while (sfi && sfi != scope) {
1519 QQuickItemPrivate::get(sfi)->subFocusItem = 0;
1520 sfi = sfi->parentItem();
1525 scopePrivate->subFocusItem = q;
1526 QQuickItem *sfi = scopePrivate->subFocusItem->parentItem();
1527 while (sfi && sfi != scope) {
1528 QQuickItemPrivate::get(sfi)->subFocusItem = q;
1529 sfi = sfi->parentItem();
1532 scopePrivate->subFocusItem = 0;
1538 \brief The QQuickItem class provides the most basic of all visual items in QtQuick.
1541 All visual items in Qt Quick inherit from QQuickItem. Although a QQuickItem
1542 instance has no visual appearance, it defines all the attributes that are
1543 common across visual items, such as x and y position, width and height,
1544 \l {Positioning with Anchors}{anchoring} and key handling support.
1546 You can subclass QQuickItem to provide your own custom visual item
1547 that inherits these features.
1549 \section2 Custom Items using Scene Graph
1551 All visual QML items are rendered using the scene graph, a
1552 low-level, high-performance rendering stack, closely tied to
1553 OpenGL. It is possible for subclasses of QQuickItem to add their
1554 own custom content into the scene graph by setting the
1555 QQuickItem::ItemHasContents flag and reimplementing the
1556 QQuickItem::updatePaintNode() function.
1558 \warning It is crucial that OpenGL operations and interaction with
1559 the scene graph happens exclusively on the rendering thread,
1560 primarily during the updatePaintNode() call. The best rule of
1561 thumb is to only use classes with the "QSG" prefix inside the
1562 QQuickItem::updatePaintNode() function.
1564 To read more about how the scene graph rendering works, see
1565 \l{Scene Graph and Rendering}
1567 \section2 Custom Items using QPainter
1569 The QQuickItem provides a subclass, QQuickPaintedItem, which
1570 allows the users to render content using QPainter.
1572 \warning Using QQuickPaintedItem uses an indirect 2D surface to
1573 render its content, either using software rasterization or using
1574 an OpenGL framebuffer object (FBO), so the rendering is a two-step
1575 operation. First rasterize the surface, then draw the
1576 surface. Using scene graph API directly is always significantly
1579 \sa QQuickWindow, QQuickPaintedItem
1584 \instantiates QQuickItem
1586 \inqmlmodule QtQuick 2
1587 \ingroup qtquick-visual
1588 \brief A basic visual QML type
1590 The Item type is the base type for all visual items in Qt Quick.
1592 All visual items in Qt Quick inherit from Item. Although an Item
1593 object has no visual appearance, it defines all the attributes that are
1594 common across visual items, such as x and y position, width and height,
1595 \l {Positioning with Anchors}{anchoring} and key handling support.
1597 The Item type can be useful for grouping several items under a single
1598 root visual item. For example:
1617 fillMode: Image.Tile
1624 \section2 Key Handling
1626 Key handling is available to all Item-based visual types via the \l Keys
1627 attached property. The \e Keys attached property provides basic handlers
1628 such as \l {Keys::}{onPressed} and \l {Keys}{::onReleased}, as well as
1629 handlers for specific keys, such as \l {Keys::}{onSpacePressed}. The
1630 example below assigns \l {Keyboard Focus in Qt Quick}{keyboard focus} to
1631 the item and handles the left key via the general \e onPressed handler
1632 and the return key via the onReturnPressed handler:
1640 if (event.key == Qt.Key_Left) {
1641 console.log("move left");
1642 event.accepted = true;
1645 Keys.onReturnPressed: console.log("Pressed return");
1649 See the \l Keys attached property for detailed documentation.
1651 \section2 Layout Mirroring
1653 Item layouts can be mirrored using the \l LayoutMirroring attached
1654 property. This causes \l{anchors.top}{anchors} to be horizontally
1655 reversed, and also causes items that lay out or position their children
1656 (such as ListView or \l Row) to horizontally reverse the direction of
1659 See LayoutMirroring for more details.
1663 \enum QQuickItem::Flag
1665 This enum type is used to specify various item properties.
1667 \value ItemClipsChildrenToShape Indicates this item should visually clip
1668 its children so that they are rendered only within the boundaries of this
1670 \value ItemAcceptsInputMethod Indicates the item supports text input
1672 \value ItemIsFocusScope Indicates the item is a focus scope. See
1673 \l {Keyboard Focus in Qt Quick} for more information.
1674 \value ItemHasContents Indicates the item has visual content and should be
1675 rendered by the scene graph.
1676 \value ItemAcceptsDrops Indicates the item accepts drag and drop events.
1678 \sa setFlag(), setFlags(), flags()
1682 \enum QQuickItem::ItemChange
1687 \class ItemChangeData
1692 \class QQuickItem::ItemChangeData
1697 \enum QQuickItem::TransformOrigin
1699 Controls the point about which simple transforms like scale apply.
1701 \value TopLeft The top-left corner of the item.
1702 \value Top The center point of the top of the item.
1703 \value TopRight The top-right corner of the item.
1704 \value Left The left most point of the vertical middle.
1705 \value Center The center of the item.
1706 \value Right The right most point of the vertical middle.
1707 \value BottomLeft The bottom-left corner of the item.
1708 \value Bottom The center point of the bottom of the item.
1709 \value BottomRight The bottom-right corner of the item.
1715 \fn void QQuickItem::childrenRectChanged(const QRectF &)
1720 \fn void QQuickItem::baselineOffsetChanged(qreal)
1725 \fn void QQuickItem::stateChanged(const QString &state)
1730 \fn void QQuickItem::parentChanged(QQuickItem *)
1735 \fn void QQuickItem::smoothChanged(bool)
1740 \fn void QQuickItem::antialiasingChanged(bool)
1745 \fn void QQuickItem::clipChanged(bool)
1750 \fn void QQuickItem::transformOriginChanged(TransformOrigin)
1755 \fn void QQuickItem::focusChanged(bool)
1760 \fn void QQuickItem::activeFocusChanged(bool)
1765 \fn void QQuickItem::childrenChanged()
1770 \fn void QQuickItem::opacityChanged()
1775 \fn void QQuickItem::enabledChanged()
1780 \fn void QQuickItem::visibleChanged()
1785 \fn void QQuickItem::visibleChildrenChanged()
1790 \fn void QQuickItem::rotationChanged()
1795 \fn void QQuickItem::scaleChanged()
1800 \fn void QQuickItem::xChanged()
1805 \fn void QQuickItem::yChanged()
1810 \fn void QQuickItem::widthChanged()
1815 \fn void QQuickItem::heightChanged()
1820 \fn void QQuickItem::zChanged()
1825 \fn void QQuickItem::implicitWidthChanged()
1830 \fn void QQuickItem::implicitHeightChanged()
1835 \fn QQuickItem::QQuickItem(QQuickItem *parent)
1837 Constructs a QQuickItem with the given \a parent.
1839 QQuickItem::QQuickItem(QQuickItem* parent)
1840 : QObject(*(new QQuickItemPrivate), parent)
1848 QQuickItem::QQuickItem(QQuickItemPrivate &dd, QQuickItem *parent)
1849 : QObject(dd, parent)
1856 static int qt_item_count = 0;
1858 static void qt_print_item_count()
1860 qDebug("Number of leaked items: %i", qt_item_count);
1866 Destroys the QQuickItem.
1868 QQuickItem::~QQuickItem()
1872 if (qt_item_count < 0)
1873 qDebug("Item destroyed after qt_print_item_count() was called.");
1878 if (d->windowRefCount > 1)
1879 d->windowRefCount = 1; // Make sure window is set to null in next call to derefWindow().
1885 // XXX todo - optimize
1886 while (!d->childItems.isEmpty())
1887 d->childItems.first()->setParentItem(0);
1889 for (int ii = 0; ii < d->changeListeners.count(); ++ii) {
1890 QQuickAnchorsPrivate *anchor = d->changeListeners.at(ii).listener->anchorPrivate();
1892 anchor->clearItem(this);
1896 update item anchors that depended on us unless they are our child (and will also be destroyed),
1897 or our sibling, and our parent is also being destroyed.
1899 for (int ii = 0; ii < d->changeListeners.count(); ++ii) {
1900 QQuickAnchorsPrivate *anchor = d->changeListeners.at(ii).listener->anchorPrivate();
1901 if (anchor && anchor->item && anchor->item->parentItem() && anchor->item->parentItem() != this)
1905 for (int ii = 0; ii < d->changeListeners.count(); ++ii) {
1906 const QQuickItemPrivate::ChangeListener &change = d->changeListeners.at(ii);
1907 if (change.types & QQuickItemPrivate::Destroyed)
1908 change.listener->itemDestroyed(this);
1911 d->changeListeners.clear();
1913 if (d->extra.isAllocated()) {
1914 delete d->extra->contents; d->extra->contents = 0;
1915 delete d->extra->layer; d->extra->layer = 0;
1918 delete d->_anchors; d->_anchors = 0;
1919 delete d->_stateGroup; d->_stateGroup = 0;
1923 \qmlproperty Item QtQuick2::Item::parent
1924 This property holds the visual parent of the item.
1926 \note The concept of the \e {visual parent} differs from that of the
1927 \e {QObject parent}. An item's visual parent may not necessarily be the
1928 same as its object parent. See \l {Concepts - Visual Parent in Qt Quick}
1932 \property QQuickItem::parent
1933 This property holds the visual parent of the item.
1935 \note The concept of the \e {visual parent} differs from that of the
1936 \e {QObject parent}. An item's visual parent may not necessarily be the
1937 same as its object parent. See \l {Concepts - Visual Parent in Qt Quick}
1940 QQuickItem *QQuickItem::parentItem() const
1942 Q_D(const QQuickItem);
1943 return d->parentItem;
1946 void QQuickItem::setParentItem(QQuickItem *parentItem)
1949 if (parentItem == d->parentItem)
1953 QQuickItem *itemAncestor = parentItem->parentItem();
1954 while (itemAncestor != 0) {
1955 if (itemAncestor == this) {
1956 qWarning("QQuickItem::setParentItem: Parent is already part of this items subtree.");
1959 itemAncestor = itemAncestor->parentItem();
1963 d->removeFromDirtyList();
1965 QQuickItem *oldParentItem = d->parentItem;
1966 QQuickItem *scopeFocusedItem = 0;
1968 if (oldParentItem) {
1969 QQuickItemPrivate *op = QQuickItemPrivate::get(oldParentItem);
1971 QQuickItem *scopeItem = 0;
1974 scopeFocusedItem = this;
1975 else if (!isFocusScope() && d->subFocusItem)
1976 scopeFocusedItem = d->subFocusItem;
1978 if (scopeFocusedItem) {
1979 scopeItem = oldParentItem;
1980 while (!scopeItem->isFocusScope() && scopeItem->parentItem())
1981 scopeItem = scopeItem->parentItem();
1983 QQuickWindowPrivate::get(d->window)->clearFocusInScope(scopeItem, scopeFocusedItem,
1984 QQuickWindowPrivate::DontChangeFocusProperty);
1985 if (scopeFocusedItem != this)
1986 QQuickItemPrivate::get(scopeFocusedItem)->updateSubFocusItem(this, true);
1988 QQuickItemPrivate::get(scopeFocusedItem)->updateSubFocusItem(scopeItem, false);
1992 const bool wasVisible = isVisible();
1993 op->removeChild(this);
1995 emit oldParentItem->visibleChildrenChanged();
1997 } else if (d->window) {
1998 QQuickWindowPrivate::get(d->window)->parentlessItems.remove(this);
2001 QQuickWindow *oldParentWindow = oldParentItem ? QQuickItemPrivate::get(oldParentItem)->window : 0;
2002 QQuickWindow *parentWindow = parentItem ? QQuickItemPrivate::get(parentItem)->window : 0;
2003 if (oldParentWindow == parentWindow) {
2004 // Avoid freeing and reallocating resources if the window stays the same.
2005 d->parentItem = parentItem;
2007 if (oldParentWindow)
2009 d->parentItem = parentItem;
2011 d->refWindow(parentWindow);
2014 d->dirty(QQuickItemPrivate::ParentChanged);
2017 QQuickItemPrivate::get(d->parentItem)->addChild(this);
2019 QQuickWindowPrivate::get(d->window)->parentlessItems.insert(this);
2021 d->setEffectiveVisibleRecur(d->calcEffectiveVisible());
2022 d->setEffectiveEnableRecur(0, d->calcEffectiveEnable());
2024 if (d->parentItem) {
2025 if (!scopeFocusedItem) {
2027 scopeFocusedItem = this;
2028 else if (!isFocusScope() && d->subFocusItem)
2029 scopeFocusedItem = d->subFocusItem;
2032 if (scopeFocusedItem) {
2033 // We need to test whether this item becomes scope focused
2034 QQuickItem *scopeItem = d->parentItem;
2035 while (!scopeItem->isFocusScope() && scopeItem->parentItem())
2036 scopeItem = scopeItem->parentItem();
2038 if (QQuickItemPrivate::get(scopeItem)->subFocusItem
2039 || (!scopeItem->isFocusScope() && scopeItem->hasFocus())) {
2040 if (scopeFocusedItem != this)
2041 QQuickItemPrivate::get(scopeFocusedItem)->updateSubFocusItem(this, false);
2042 QQuickItemPrivate::get(scopeFocusedItem)->focus = false;
2043 emit scopeFocusedItem->focusChanged(false);
2046 QQuickWindowPrivate::get(d->window)->setFocusInScope(scopeItem, scopeFocusedItem,
2047 QQuickWindowPrivate::DontChangeFocusProperty);
2049 QQuickItemPrivate::get(scopeFocusedItem)->updateSubFocusItem(scopeItem, true);
2055 d->resolveLayoutMirror();
2057 d->itemChange(ItemParentHasChanged, d->parentItem);
2059 d->parentNotifier.notify();
2060 if (d->isAccessible && d->parentItem) {
2061 d->parentItem->d_func()->setAccessibleFlagAndListener();
2064 emit parentChanged(d->parentItem);
2065 if (isVisible() && d->parentItem)
2066 emit d->parentItem->visibleChildrenChanged();
2070 Moves the specified \a sibling item to the index before this item
2071 within the visual stacking order.
2073 The given \a sibling must be a sibling of this item; that is, they must
2074 have the same immediate \l parent.
2076 \sa {Concepts - Visual Parent in Qt Quick}
2078 void QQuickItem::stackBefore(const QQuickItem *sibling)
2081 if (!sibling || sibling == this || !d->parentItem || d->parentItem != QQuickItemPrivate::get(sibling)->parentItem) {
2082 qWarning("QQuickItem::stackBefore: Cannot stack before %p, which must be a sibling", sibling);
2086 QQuickItemPrivate *parentPrivate = QQuickItemPrivate::get(d->parentItem);
2088 int myIndex = parentPrivate->childItems.lastIndexOf(this);
2089 int siblingIndex = parentPrivate->childItems.lastIndexOf(const_cast<QQuickItem *>(sibling));
2091 Q_ASSERT(myIndex != -1 && siblingIndex != -1);
2093 if (myIndex == siblingIndex - 1)
2096 parentPrivate->childItems.move(myIndex, myIndex < siblingIndex ? siblingIndex - 1 : siblingIndex);
2098 parentPrivate->dirty(QQuickItemPrivate::ChildrenStackingChanged);
2099 parentPrivate->markSortedChildrenDirty(this);
2101 for (int ii = qMin(siblingIndex, myIndex); ii < parentPrivate->childItems.count(); ++ii)
2102 QQuickItemPrivate::get(parentPrivate->childItems.at(ii))->siblingOrderChanged();
2106 Moves the specified \a sibling item to the index after this item
2107 within the visual stacking order.
2109 The given \a sibling must be a sibling of this item; that is, they must
2110 have the same immediate \l parent.
2112 \sa {Concepts - Visual Parent in Qt Quick}
2114 void QQuickItem::stackAfter(const QQuickItem *sibling)
2117 if (!sibling || sibling == this || !d->parentItem || d->parentItem != QQuickItemPrivate::get(sibling)->parentItem) {
2118 qWarning("QQuickItem::stackAfter: Cannot stack after %p, which must be a sibling", sibling);
2122 QQuickItemPrivate *parentPrivate = QQuickItemPrivate::get(d->parentItem);
2124 int myIndex = parentPrivate->childItems.lastIndexOf(this);
2125 int siblingIndex = parentPrivate->childItems.lastIndexOf(const_cast<QQuickItem *>(sibling));
2127 Q_ASSERT(myIndex != -1 && siblingIndex != -1);
2129 if (myIndex == siblingIndex + 1)
2132 parentPrivate->childItems.move(myIndex, myIndex > siblingIndex ? siblingIndex + 1 : siblingIndex);
2134 parentPrivate->dirty(QQuickItemPrivate::ChildrenStackingChanged);
2135 parentPrivate->markSortedChildrenDirty(this);
2137 for (int ii = qMin(myIndex, siblingIndex + 1); ii < parentPrivate->childItems.count(); ++ii)
2138 QQuickItemPrivate::get(parentPrivate->childItems.at(ii))->siblingOrderChanged();
2142 Returns the window in which this item is rendered.
2144 QQuickWindow *QQuickItem::window() const
2146 Q_D(const QQuickItem);
2150 static bool itemZOrder_sort(QQuickItem *lhs, QQuickItem *rhs)
2152 return lhs->z() < rhs->z();
2155 QList<QQuickItem *> QQuickItemPrivate::paintOrderChildItems() const
2157 if (sortedChildItems)
2158 return *sortedChildItems;
2160 // If none of the items have set Z then the paint order list is the same as
2161 // the childItems list. This is by far the most common case.
2163 for (int i = 0; i < childItems.count(); ++i) {
2164 if (QQuickItemPrivate::get(childItems.at(i))->z() != 0.) {
2170 sortedChildItems = new QList<QQuickItem*>(childItems);
2171 qStableSort(sortedChildItems->begin(), sortedChildItems->end(), itemZOrder_sort);
2172 return *sortedChildItems;
2175 sortedChildItems = const_cast<QList<QQuickItem*>*>(&childItems);
2180 void QQuickItemPrivate::addChild(QQuickItem *child)
2184 Q_ASSERT(!childItems.contains(child));
2186 childItems.append(child);
2188 markSortedChildrenDirty(child);
2189 dirty(QQuickItemPrivate::ChildrenChanged);
2191 itemChange(QQuickItem::ItemChildAddedChange, child);
2193 emit q->childrenChanged();
2196 void QQuickItemPrivate::removeChild(QQuickItem *child)
2201 Q_ASSERT(childItems.contains(child));
2202 childItems.removeOne(child);
2203 Q_ASSERT(!childItems.contains(child));
2205 markSortedChildrenDirty(child);
2206 dirty(QQuickItemPrivate::ChildrenChanged);
2208 itemChange(QQuickItem::ItemChildRemovedChange, child);
2210 emit q->childrenChanged();
2213 void QQuickItemPrivate::refWindow(QQuickWindow *c)
2215 // An item needs a window if it is referenced by another item which has a window.
2216 // Typically the item is referenced by a parent, but can also be referenced by a
2217 // ShaderEffect or ShaderEffectSource. 'windowRefCount' counts how many items with
2218 // a window is referencing this item. When the reference count goes from zero to one,
2219 // or one to zero, the window of this item is updated and propagated to the children.
2220 // As long as the reference count stays above zero, the window is unchanged.
2221 // refWindow() increments the reference count.
2222 // derefWindow() decrements the reference count.
2225 Q_ASSERT((window != 0) == (windowRefCount > 0));
2227 if (++windowRefCount > 1) {
2229 qWarning("QQuickItem: Cannot use same item on different windows at the same time.");
2230 return; // Window already set.
2233 Q_ASSERT(window == 0);
2236 if (polishScheduled)
2237 QQuickWindowPrivate::get(window)->itemsToPolish.insert(q);
2240 QQuickWindowPrivate::get(window)->parentlessItems.insert(q);
2242 for (int ii = 0; ii < childItems.count(); ++ii) {
2243 QQuickItem *child = childItems.at(ii);
2244 QQuickItemPrivate::get(child)->refWindow(c);
2249 if (extra.isAllocated() && extra->screenAttached)
2250 extra->screenAttached->windowChanged(c);
2251 itemChange(QQuickItem::ItemSceneChange, c);
2254 void QQuickItemPrivate::derefWindow()
2257 Q_ASSERT((window != 0) == (windowRefCount > 0));
2260 return; // This can happen when destroying recursive shader effect sources.
2262 if (--windowRefCount > 0)
2263 return; // There are still other references, so don't set window to null yet.
2265 q->releaseResources();
2266 removeFromDirtyList();
2267 QQuickWindowPrivate *c = QQuickWindowPrivate::get(window);
2268 if (polishScheduled)
2269 c->itemsToPolish.remove(q);
2270 QMutableHashIterator<int, QQuickItem *> itemTouchMapIt(c->itemForTouchPointId);
2271 while (itemTouchMapIt.hasNext()) {
2272 if (itemTouchMapIt.next().value() == q)
2273 itemTouchMapIt.remove();
2275 if (c->mouseGrabberItem == q)
2276 c->mouseGrabberItem = 0;
2277 #ifndef QT_NO_CURSOR
2278 if (c->cursorItem == q)
2282 c->hoverItems.removeAll(q);
2283 if (itemNodeInstance)
2284 c->cleanup(itemNodeInstance);
2286 c->parentlessItems.remove(q);
2290 itemNodeInstance = 0;
2292 if (extra.isAllocated()) {
2293 extra->opacityNode = 0;
2294 extra->clipNode = 0;
2295 extra->rootNode = 0;
2296 extra->beforePaintNode = 0;
2302 for (int ii = 0; ii < childItems.count(); ++ii) {
2303 QQuickItem *child = childItems.at(ii);
2304 QQuickItemPrivate::get(child)->derefWindow();
2309 if (extra.isAllocated() && extra->screenAttached)
2310 extra->screenAttached->windowChanged(0);
2311 itemChange(QQuickItem::ItemSceneChange, (QQuickWindow *)0);
2316 Returns a transform that maps points from window space into item space.
2318 QTransform QQuickItemPrivate::windowToItemTransform() const
2320 // XXX todo - optimize
2321 return itemToWindowTransform().inverted();
2325 Returns a transform that maps points from item space into window space.
2327 QTransform QQuickItemPrivate::itemToWindowTransform() const
2330 QTransform rv = parentItem?QQuickItemPrivate::get(parentItem)->itemToWindowTransform():QTransform();
2331 itemToParentTransform(rv);
2336 Motifies \a t with this items local transform relative to its parent.
2338 void QQuickItemPrivate::itemToParentTransform(QTransform &t) const
2343 if (!transforms.isEmpty()) {
2345 for (int ii = transforms.count() - 1; ii >= 0; --ii)
2346 transforms.at(ii)->applyTo(&m);
2347 t = m.toTransform();
2350 if (scale() != 1. || rotation() != 0.) {
2351 QPointF tp = computeTransformOrigin();
2352 t.translate(tp.x(), tp.y());
2353 t.scale(scale(), scale());
2354 t.rotate(rotation());
2355 t.translate(-tp.x(), -tp.y());
2360 Returns true if construction of the QML component is complete; otherwise
2363 It is often desirable to delay some processing until the component is
2366 \sa componentComplete()
2368 bool QQuickItem::isComponentComplete() const
2370 Q_D(const QQuickItem);
2371 return d->componentComplete;
2374 QQuickItemPrivate::QQuickItemPrivate()
2379 , heightValid(false)
2380 , baselineOffsetValid(false)
2381 , componentComplete(true)
2384 , hoverEnabled(false)
2386 , antialiasing(false)
2388 , activeFocus(false)
2389 , notifiedFocus(false)
2390 , notifiedActiveFocus(false)
2391 , filtersChildMouseEvents(false)
2392 , explicitVisible(true)
2393 , effectiveVisible(true)
2394 , explicitEnable(true)
2395 , effectiveEnable(true)
2396 , polishScheduled(false)
2397 , inheritedLayoutMirror(false)
2398 , effectiveLayoutMirror(false)
2399 , isMirrorImplicit(true)
2400 , inheritMirrorFromParent(false)
2401 , inheritMirrorFromItem(false)
2402 , isAccessible(false)
2405 , dirtyAttributes(0)
2411 , sortedChildItems(&childItems)
2420 , itemNodeInstance(0)
2426 QQuickItemPrivate::~QQuickItemPrivate()
2428 if (sortedChildItems != &childItems)
2429 delete sortedChildItems;
2432 void QQuickItemPrivate::init(QQuickItem *parent)
2436 static bool atexit_registered = false;
2437 if (!atexit_registered) {
2438 atexit(qt_print_item_count);
2439 atexit_registered = true;
2445 registerAccessorProperties();
2447 baselineOffsetValid = false;
2450 q->setParentItem(parent);
2451 QQuickItemPrivate *parentPrivate = QQuickItemPrivate::get(parent);
2452 setImplicitLayoutMirror(parentPrivate->inheritedLayoutMirror, parentPrivate->inheritMirrorFromParent);
2456 void QQuickItemPrivate::data_append(QQmlListProperty<QObject> *prop, QObject *o)
2461 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2463 if (QQuickItem *item = qmlobject_cast<QQuickItem *>(o)) {
2464 item->setParentItem(that);
2466 if (o->inherits("QGraphicsItem"))
2467 qWarning("Cannot add a QtQuick 1.0 item (%s) into a QtQuick 2.0 scene!", o->metaObject()->className());
2469 // XXX todo - do we really want this behavior?
2475 \qmlproperty list<Object> QtQuick2::Item::data
2478 The data property allows you to freely mix visual children and resources
2479 in an item. If you assign a visual item to the data list it becomes
2480 a child and if you assign any other object type, it is added as a resource.
2504 It should not generally be necessary to refer to the \c data property,
2505 as it is the default property for Item and thus all child items are
2506 automatically assigned to this property.
2509 int QQuickItemPrivate::data_count(QQmlListProperty<QObject> *prop)
2516 QObject *QQuickItemPrivate::data_at(QQmlListProperty<QObject> *prop, int i)
2524 void QQuickItemPrivate::data_clear(QQmlListProperty<QObject> *prop)
2530 QObject *QQuickItemPrivate::resources_at(QQmlListProperty<QObject> *prop, int index)
2532 const QObjectList children = prop->object->children();
2533 if (index < children.count())
2534 return children.at(index);
2539 void QQuickItemPrivate::resources_append(QQmlListProperty<QObject> *prop, QObject *o)
2541 // XXX todo - do we really want this behavior?
2542 o->setParent(prop->object);
2545 int QQuickItemPrivate::resources_count(QQmlListProperty<QObject> *prop)
2547 return prop->object->children().count();
2550 void QQuickItemPrivate::resources_clear(QQmlListProperty<QObject> *prop)
2552 // XXX todo - do we really want this behavior?
2553 const QObjectList children = prop->object->children();
2554 for (int index = 0; index < children.count(); index++)
2555 children.at(index)->setParent(0);
2558 QQuickItem *QQuickItemPrivate::children_at(QQmlListProperty<QQuickItem> *prop, int index)
2560 QQuickItemPrivate *p = QQuickItemPrivate::get(static_cast<QQuickItem *>(prop->object));
2561 if (index >= p->childItems.count() || index < 0)
2564 return p->childItems.at(index);
2567 void QQuickItemPrivate::children_append(QQmlListProperty<QQuickItem> *prop, QQuickItem *o)
2572 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2573 if (o->parentItem() == that)
2574 o->setParentItem(0);
2576 o->setParentItem(that);
2579 int QQuickItemPrivate::children_count(QQmlListProperty<QQuickItem> *prop)
2581 QQuickItemPrivate *p = QQuickItemPrivate::get(static_cast<QQuickItem *>(prop->object));
2582 return p->childItems.count();
2585 void QQuickItemPrivate::children_clear(QQmlListProperty<QQuickItem> *prop)
2587 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2588 QQuickItemPrivate *p = QQuickItemPrivate::get(that);
2589 while (!p->childItems.isEmpty())
2590 p->childItems.at(0)->setParentItem(0);
2593 void QQuickItemPrivate::visibleChildren_append(QQmlListProperty<QQuickItem>*, QQuickItem *self)
2596 qmlInfo(self) << "QQuickItem: visibleChildren property is readonly and cannot be assigned to.";
2599 int QQuickItemPrivate::visibleChildren_count(QQmlListProperty<QQuickItem> *prop)
2601 QQuickItemPrivate *p = QQuickItemPrivate::get(static_cast<QQuickItem *>(prop->object));
2602 int visibleCount = 0;
2603 int c = p->childItems.count();
2605 if (p->childItems.at(c)->isVisible()) visibleCount++;
2608 return visibleCount;
2611 QQuickItem *QQuickItemPrivate::visibleChildren_at(QQmlListProperty<QQuickItem> *prop, int index)
2613 QQuickItemPrivate *p = QQuickItemPrivate::get(static_cast<QQuickItem *>(prop->object));
2614 const int childCount = p->childItems.count();
2615 if (index >= childCount || index < 0)
2618 int visibleCount = -1;
2619 for (int i = 0; i < childCount; i++) {
2620 if (p->childItems.at(i)->isVisible()) visibleCount++;
2621 if (visibleCount == index) return p->childItems.at(i);
2626 int QQuickItemPrivate::transform_count(QQmlListProperty<QQuickTransform> *prop)
2628 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2629 QQuickItemPrivate *p = QQuickItemPrivate::get(that);
2631 return p->transforms.count();
2634 void QQuickTransform::appendToItem(QQuickItem *item)
2636 Q_D(QQuickTransform);
2640 QQuickItemPrivate *p = QQuickItemPrivate::get(item);
2642 if (!d->items.isEmpty() && !p->transforms.isEmpty() && p->transforms.contains(this)) {
2643 p->transforms.removeOne(this);
2644 p->transforms.append(this);
2646 p->transforms.append(this);
2647 d->items.append(item);
2650 p->dirty(QQuickItemPrivate::Transform);
2653 void QQuickTransform::prependToItem(QQuickItem *item)
2655 Q_D(QQuickTransform);
2659 QQuickItemPrivate *p = QQuickItemPrivate::get(item);
2661 if (!d->items.isEmpty() && !p->transforms.isEmpty() && p->transforms.contains(this)) {
2662 p->transforms.removeOne(this);
2663 p->transforms.prepend(this);
2665 p->transforms.prepend(this);
2666 d->items.append(item);
2669 p->dirty(QQuickItemPrivate::Transform);
2672 void QQuickItemPrivate::transform_append(QQmlListProperty<QQuickTransform> *prop, QQuickTransform *transform)
2677 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2678 transform->appendToItem(that);
2681 QQuickTransform *QQuickItemPrivate::transform_at(QQmlListProperty<QQuickTransform> *prop, int idx)
2683 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2684 QQuickItemPrivate *p = QQuickItemPrivate::get(that);
2686 if (idx < 0 || idx >= p->transforms.count())
2689 return p->transforms.at(idx);
2692 void QQuickItemPrivate::transform_clear(QQmlListProperty<QQuickTransform> *prop)
2694 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2695 QQuickItemPrivate *p = QQuickItemPrivate::get(that);
2697 for (int ii = 0; ii < p->transforms.count(); ++ii) {
2698 QQuickTransform *t = p->transforms.at(ii);
2699 QQuickTransformPrivate *tp = QQuickTransformPrivate::get(t);
2700 tp->items.removeOne(that);
2703 p->transforms.clear();
2705 p->dirty(QQuickItemPrivate::Transform);
2709 \qmlproperty AnchorLine QtQuick2::Item::anchors.top
2710 \qmlproperty AnchorLine QtQuick2::Item::anchors.bottom
2711 \qmlproperty AnchorLine QtQuick2::Item::anchors.left
2712 \qmlproperty AnchorLine QtQuick2::Item::anchors.right
2713 \qmlproperty AnchorLine QtQuick2::Item::anchors.horizontalCenter
2714 \qmlproperty AnchorLine QtQuick2::Item::anchors.verticalCenter
2715 \qmlproperty AnchorLine QtQuick2::Item::anchors.baseline
2717 \qmlproperty Item QtQuick2::Item::anchors.fill
2718 \qmlproperty Item QtQuick2::Item::anchors.centerIn
2720 \qmlproperty real QtQuick2::Item::anchors.margins
2721 \qmlproperty real QtQuick2::Item::anchors.topMargin
2722 \qmlproperty real QtQuick2::Item::anchors.bottomMargin
2723 \qmlproperty real QtQuick2::Item::anchors.leftMargin
2724 \qmlproperty real QtQuick2::Item::anchors.rightMargin
2725 \qmlproperty real QtQuick2::Item::anchors.horizontalCenterOffset
2726 \qmlproperty real QtQuick2::Item::anchors.verticalCenterOffset
2727 \qmlproperty real QtQuick2::Item::anchors.baselineOffset
2729 \qmlproperty bool QtQuick2::Item::anchors.alignWhenCentered
2731 Anchors provide a way to position an item by specifying its
2732 relationship with other items.
2734 Margins apply to top, bottom, left, right, and fill anchors.
2735 The \c anchors.margins property can be used to set all of the various margins at once, to the same value.
2736 It will not override a specific margin that has been previously set; to clear an explicit margin
2737 set it's value to \c undefined.
2738 Note that margins are anchor-specific and are not applied if an item does not
2741 Offsets apply for horizontal center, vertical center, and baseline anchors.
2745 \li \image declarative-anchors_example.png
2746 \li Text anchored to Image, horizontally centered and vertically below, with a margin.
2755 anchors.horizontalCenter: pic.horizontalCenter
2756 anchors.top: pic.bottom
2757 anchors.topMargin: 5
2763 \li \image declarative-anchors_example2.png
2765 Left of Text anchored to right of Image, with a margin. The y
2766 property of both defaults to 0.
2776 anchors.left: pic.right
2777 anchors.leftMargin: 5
2784 \c anchors.fill provides a convenient way for one item to have the
2785 same geometry as another item, and is equivalent to connecting all
2786 four directional anchors.
2788 To clear an anchor value, set it to \c undefined.
2790 \c anchors.alignWhenCentered (default true) forces centered anchors to align to a
2791 whole pixel, i.e. if the item being centered has an odd width/height the item
2792 will be positioned on a whole pixel rather than being placed on a half-pixel.
2793 This ensures the item is painted crisply. There are cases where this is not
2794 desirable, for example when rotating the item jitters may be apparent as the
2797 \note You can only anchor an item to siblings or a parent.
2799 For more information see \l {anchor-layout}{Anchor Layouts}.
2801 QQuickAnchors *QQuickItemPrivate::anchors() const
2804 Q_Q(const QQuickItem);
2805 _anchors = new QQuickAnchors(const_cast<QQuickItem *>(q));
2806 if (!componentComplete)
2807 _anchors->classBegin();
2812 void QQuickItemPrivate::siblingOrderChanged()
2815 for (int ii = 0; ii < changeListeners.count(); ++ii) {
2816 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
2817 if (change.types & QQuickItemPrivate::SiblingOrder) {
2818 change.listener->itemSiblingOrderChanged(q);
2823 QQmlListProperty<QObject> QQuickItemPrivate::data()
2825 return QQmlListProperty<QObject>(q_func(), 0, QQuickItemPrivate::data_append,
2826 QQuickItemPrivate::data_count,
2827 QQuickItemPrivate::data_at,
2828 QQuickItemPrivate::data_clear);
2832 \qmlproperty real QtQuick2::Item::childrenRect.x
2833 \qmlproperty real QtQuick2::Item::childrenRect.y
2834 \qmlproperty real QtQuick2::Item::childrenRect.width
2835 \qmlproperty real QtQuick2::Item::childrenRect.height
2837 This property holds the collective position and size of the item's
2840 This property is useful if you need to access the collective geometry
2841 of an item's children in order to correctly size the item.
2844 \property QQuickItem::childrenRect
2846 This property holds the collective position and size of the item's
2849 This property is useful if you need to access the collective geometry
2850 of an item's children in order to correctly size the item.
2852 QRectF QQuickItem::childrenRect()
2855 if (!d->extra.isAllocated() || !d->extra->contents) {
2856 d->extra.value().contents = new QQuickContents(this);
2857 if (d->componentComplete)
2858 d->extra->contents->complete();
2860 return d->extra->contents->rectF();
2864 Returns the children of this item.
2866 QList<QQuickItem *> QQuickItem::childItems() const
2868 Q_D(const QQuickItem);
2869 return d->childItems;
2873 \qmlproperty bool QtQuick2::Item::clip
2874 This property holds whether clipping is enabled. The default clip value is \c false.
2876 If clipping is enabled, an item will clip its own painting, as well
2877 as the painting of its children, to its bounding rectangle.
2879 Non-rectangular clipping regions are not supported for performance reasons.
2882 \property QQuickItem::clip
2883 This property holds whether clipping is enabled. The default clip value is \c false.
2885 If clipping is enabled, an item will clip its own painting, as well
2886 as the painting of its children, to its bounding rectangle. If you set
2887 clipping during an item's paint operation, remember to re-set it to
2888 prevent clipping the rest of your scene.
2890 Non-rectangular clipping regions are not supported for performance reasons.
2892 bool QQuickItem::clip() const
2894 return flags() & ItemClipsChildrenToShape;
2897 void QQuickItem::setClip(bool c)
2902 setFlag(ItemClipsChildrenToShape, c);
2904 emit clipChanged(c);
2909 This function is called to handle this item's changes in
2910 geometry from \a oldGeometry to \a newGeometry. If the two
2911 geometries are the same, it doesn't do anything.
2913 Derived classes must call the base class method within their implementation.
2915 void QQuickItem::geometryChanged(const QRectF &newGeometry, const QRectF &oldGeometry)
2920 QQuickAnchorsPrivate::get(d->_anchors)->updateMe();
2922 bool xChange = (newGeometry.x() != oldGeometry.x());
2923 bool yChange = (newGeometry.y() != oldGeometry.y());
2924 bool widthChange = (newGeometry.width() != oldGeometry.width());
2925 bool heightChange = (newGeometry.height() != oldGeometry.height());
2927 for (int ii = 0; ii < d->changeListeners.count(); ++ii) {
2928 const QQuickItemPrivate::ChangeListener &change = d->changeListeners.at(ii);
2929 if (change.types & QQuickItemPrivate::Geometry) {
2930 if (change.gTypes == QQuickItemPrivate::GeometryChange) {
2931 change.listener->itemGeometryChanged(this, newGeometry, oldGeometry);
2932 } else if ((xChange && (change.gTypes & QQuickItemPrivate::XChange)) ||
2933 (yChange && (change.gTypes & QQuickItemPrivate::YChange)) ||
2934 (widthChange && (change.gTypes & QQuickItemPrivate::WidthChange)) ||
2935 (heightChange && (change.gTypes & QQuickItemPrivate::HeightChange))) {
2936 change.listener->itemGeometryChanged(this, newGeometry, oldGeometry);
2946 emit widthChanged();
2948 emit heightChanged();
2952 Called by the rendering thread, as a result of
2953 QQuickItem::update(), when it is time to sync the state of the QML
2954 objects with the scene graph objects.
2956 The function should return the root of the scene graph subtree for
2957 this item. Most implementations will return a single
2958 QSGGeometryNode containing the visual representation of this item.
2959 \a oldNode is the node that was returned the last time the
2960 function was called.
2963 QSGNode *MyItem::updatePaintNode(QSGNode *node, UpdatePaintNodeData *)
2965 QSGSimpleRectNode *n = static_cast<QSGSimpleRectNode *>(node);
2967 n = new QSGSimpleRectNode();
2968 n->setColor(Qt::red);
2970 n->setRect(boundingRect());
2975 The main thread is blocked while this function is executed so it is safe to read
2976 values from the QQuickItem instance and other objects in the main thread.
2978 If no call to QQuickItem::updatePaintNode() result in actual scene graph
2979 changes, like QSGNode::markDirty() or adding and removing nodes, then
2980 the underlying implementation may decide to not render the scene again as
2981 the visual outcome is identical.
2983 \warning It is crucial that OpenGL operations and interaction with
2984 the scene graph happens exclusively on the rendering thread,
2985 primarily during the QQuickItem::updatePaintNode() call. The best
2986 rule of thumb is to only use classes with the "QSG" prefix inside
2987 the QQuickItem::updatePaintNode() function.
2989 \sa QSGMaterial, QSGSimpleMaterial, QSGGeometryNode, QSGGeometry,
2990 QSGFlatColorMaterial, QSGTextureMaterial, QSGNode::markDirty()
2993 QSGNode *QQuickItem::updatePaintNode(QSGNode *oldNode, UpdatePaintNodeData *)
3000 This function is called when the item's scene graph resources are no longer needed.
3001 It allows items to free its resources, for instance textures, that are not owned by scene graph
3002 nodes. Note that scene graph nodes are managed by QQuickWindow and should not be deleted by
3003 this function. Scene graph resources are no longer needed when the parent is set to null and
3004 the item is not used by any \l ShaderEffect or \l ShaderEffectSource.
3006 This function is called from the main thread. Therefore, resources used by the scene graph
3007 should not be deleted directly, but by calling \l QObject::deleteLater().
3009 \note The item destructor still needs to free its scene graph resources if not already done.
3012 void QQuickItem::releaseResources()
3016 QSGTransformNode *QQuickItemPrivate::createTransformNode()
3018 return new QSGTransformNode;
3022 This function should perform any layout as required for this item.
3024 When polish() is called, the scene graph schedules a polish event for this
3025 item. When the scene graph is ready to render this item, it calls
3026 updatePolish() to do any item layout as required before it renders the
3029 void QQuickItem::updatePolish()
3033 void QQuickItemPrivate::addItemChangeListener(QQuickItemChangeListener *listener, ChangeTypes types)
3035 changeListeners.append(ChangeListener(listener, types));
3038 void QQuickItemPrivate::removeItemChangeListener(QQuickItemChangeListener *listener, ChangeTypes types)
3040 ChangeListener change(listener, types);
3041 changeListeners.removeOne(change);
3044 void QQuickItemPrivate::updateOrAddGeometryChangeListener(QQuickItemChangeListener *listener, GeometryChangeTypes types)
3046 ChangeListener change(listener, types);
3047 int index = changeListeners.find(change);
3049 changeListeners[index].gTypes = change.gTypes; //we may have different GeometryChangeTypes
3051 changeListeners.append(change);
3054 void QQuickItemPrivate::updateOrRemoveGeometryChangeListener(QQuickItemChangeListener *listener,
3055 GeometryChangeTypes types)
3057 ChangeListener change(listener, types);
3058 if (types == NoChange) {
3059 changeListeners.removeOne(change);
3061 int index = changeListeners.find(change);
3063 changeListeners[index].gTypes = change.gTypes; //we may have different GeometryChangeTypes
3068 This event handler can be reimplemented in a subclass to receive key
3069 press events for an item. The event information is provided by the
3072 void QQuickItem::keyPressEvent(QKeyEvent *event)
3078 This event handler can be reimplemented in a subclass to receive key
3079 release events for an item. The event information is provided by the
3082 void QQuickItem::keyReleaseEvent(QKeyEvent *event)
3088 This event handler can be reimplemented in a subclass to receive input
3089 method events for an item. The event information is provided by the
3092 void QQuickItem::inputMethodEvent(QInputMethodEvent *event)
3098 This event handler can be reimplemented in a subclass to receive focus-in
3099 events for an item. The event information is provided by the
3102 void QQuickItem::focusInEvent(QFocusEvent *event)
3104 #ifndef QT_NO_ACCESSIBILITY
3105 QAccessibleEvent ev(this, QAccessible::Focus);
3106 QAccessible::updateAccessibility(&ev);
3111 This event handler can be reimplemented in a subclass to receive focus-out
3112 events for an item. The event information is provided by the
3115 void QQuickItem::focusOutEvent(QFocusEvent *event)
3120 This event handler can be reimplemented in a subclass to receive mouse
3121 press events for an item. The event information is provided by the
3124 void QQuickItem::mousePressEvent(QMouseEvent *event)
3130 This event handler can be reimplemented in a subclass to receive mouse
3131 move events for an item. The event information is provided by the
3134 void QQuickItem::mouseMoveEvent(QMouseEvent *event)
3140 This event handler can be reimplemented in a subclass to receive mouse
3141 release events for an item. The event information is provided by the
3144 void QQuickItem::mouseReleaseEvent(QMouseEvent *event)
3150 This event handler can be reimplemented in a subclass to receive mouse
3151 double-click events for an item. The event information is provided by the
3154 void QQuickItem::mouseDoubleClickEvent(QMouseEvent *)
3159 This event handler can be reimplemented in a subclass to be notified
3160 when a mouse ungrab event has occurred on this item.
3164 void QQuickItem::mouseUngrabEvent()
3170 This event handler can be reimplemented in a subclass to be notified
3171 when a touch ungrab event has occurred on this item.
3173 void QQuickItem::touchUngrabEvent()
3179 This event handler can be reimplemented in a subclass to receive
3180 wheel events for an item. The event information is provided by the
3183 void QQuickItem::wheelEvent(QWheelEvent *event)
3189 This event handler can be reimplemented in a subclass to receive touch
3190 events for an item. The event information is provided by the
3193 void QQuickItem::touchEvent(QTouchEvent *event)
3199 This event handler can be reimplemented in a subclass to receive hover-enter
3200 events for an item. The event information is provided by the
3203 Hover events are only provided if acceptHoverEvents() is true.
3205 void QQuickItem::hoverEnterEvent(QHoverEvent *event)
3211 This event handler can be reimplemented in a subclass to receive hover-move
3212 events for an item. The event information is provided by the
3215 Hover events are only provided if acceptHoverEvents() is true.
3217 void QQuickItem::hoverMoveEvent(QHoverEvent *event)
3223 This event handler can be reimplemented in a subclass to receive hover-leave
3224 events for an item. The event information is provided by the
3227 Hover events are only provided if acceptHoverEvents() is true.
3229 void QQuickItem::hoverLeaveEvent(QHoverEvent *event)
3234 #ifndef QT_NO_DRAGANDDROP
3236 This event handler can be reimplemented in a subclass to receive drag-enter
3237 events for an item. The event information is provided by the
3240 Drag and drop events are only provided if the ItemAcceptsDrops flag
3241 has been set for this item.
3243 \sa Drag, {Drag and Drop}
3245 void QQuickItem::dragEnterEvent(QDragEnterEvent *event)
3251 This event handler can be reimplemented in a subclass to receive drag-move
3252 events for an item. The event information is provided by the
3255 Drag and drop events are only provided if the ItemAcceptsDrops flag
3256 has been set for this item.
3258 \sa Drag, {Drag and Drop}
3260 void QQuickItem::dragMoveEvent(QDragMoveEvent *event)
3266 This event handler can be reimplemented in a subclass to receive drag-leave
3267 events for an item. The event information is provided by the
3270 Drag and drop events are only provided if the ItemAcceptsDrops flag
3271 has been set for this item.
3273 \sa Drag, {Drag and Drop}
3275 void QQuickItem::dragLeaveEvent(QDragLeaveEvent *event)
3281 This event handler can be reimplemented in a subclass to receive drop
3282 events for an item. The event information is provided by the
3285 Drag and drop events are only provided if the ItemAcceptsDrops flag
3286 has been set for this item.
3288 \sa Drag, {Drag and Drop}
3290 void QQuickItem::dropEvent(QDropEvent *event)
3294 #endif // QT_NO_DRAGANDDROP
3297 Reimplement this method to filter the mouse events that are received by
3298 this item's children.
3300 This method will only be called if filtersChildMouseEvents() is true.
3302 Return true if the specified \a event should not be passed onto the
3303 specified child \a item, and false otherwise.
3305 \sa setFiltersChildMouseEvents()
3307 bool QQuickItem::childMouseEventFilter(QQuickItem *item, QEvent *event)
3317 void QQuickItem::windowDeactivateEvent()
3319 foreach (QQuickItem* item, childItems()) {
3320 item->windowDeactivateEvent();
3325 This method is only relevant for input items.
3327 If this item is an input item, this method should be reimplemented to
3328 return the relevant input method flags for the given \a query.
3330 \sa QWidget::inputMethodQuery()
3332 QVariant QQuickItem::inputMethodQuery(Qt::InputMethodQuery query) const
3334 Q_D(const QQuickItem);
3339 v = (bool)(flags() & ItemAcceptsInputMethod);
3342 case Qt::ImCursorRectangle:
3344 case Qt::ImCursorPosition:
3345 case Qt::ImSurroundingText:
3346 case Qt::ImCurrentSelection:
3347 case Qt::ImMaximumTextLength:
3348 case Qt::ImAnchorPosition:
3349 case Qt::ImPreferredLanguage:
3350 if (d->extra.isAllocated() && d->extra->keyHandler)
3351 v = d->extra->keyHandler->inputMethodQuery(query);
3359 QQuickAnchorLine QQuickItemPrivate::left() const
3361 Q_Q(const QQuickItem);
3362 return QQuickAnchorLine(const_cast<QQuickItem *>(q), QQuickAnchorLine::Left);
3365 QQuickAnchorLine QQuickItemPrivate::right() const
3367 Q_Q(const QQuickItem);
3368 return QQuickAnchorLine(const_cast<QQuickItem *>(q), QQuickAnchorLine::Right);
3371 QQuickAnchorLine QQuickItemPrivate::horizontalCenter() const
3373 Q_Q(const QQuickItem);
3374 return QQuickAnchorLine(const_cast<QQuickItem *>(q), QQuickAnchorLine::HCenter);
3377 QQuickAnchorLine QQuickItemPrivate::top() const
3379 Q_Q(const QQuickItem);
3380 return QQuickAnchorLine(const_cast<QQuickItem *>(q), QQuickAnchorLine::Top);
3383 QQuickAnchorLine QQuickItemPrivate::bottom() const
3385 Q_Q(const QQuickItem);
3386 return QQuickAnchorLine(const_cast<QQuickItem *>(q), QQuickAnchorLine::Bottom);
3389 QQuickAnchorLine QQuickItemPrivate::verticalCenter() const
3391 Q_Q(const QQuickItem);
3392 return QQuickAnchorLine(const_cast<QQuickItem *>(q), QQuickAnchorLine::VCenter);
3395 QQuickAnchorLine QQuickItemPrivate::baseline() const
3397 Q_Q(const QQuickItem);
3398 return QQuickAnchorLine(const_cast<QQuickItem *>(q), QQuickAnchorLine::Baseline);
3402 \qmlproperty int QtQuick2::Item::baselineOffset
3404 Specifies the position of the item's baseline in local coordinates.
3406 The baseline of a \l Text item is the imaginary line on which the text
3407 sits. Controls containing text usually set their baseline to the
3408 baseline of their text.
3410 For non-text items, a default baseline offset of 0 is used.
3413 \property QQuickItem::baselineOffset
3415 Specifies the position of the item's baseline in local coordinates.
3417 The baseline of a \l Text item is the imaginary line on which the text
3418 sits. Controls containing text usually set their baseline to the
3419 baseline of their text.
3421 For non-text items, a default baseline offset of 0 is used.
3423 qreal QQuickItem::baselineOffset() const
3425 Q_D(const QQuickItem);
3426 if (d->baselineOffsetValid) {
3427 return d->baselineOffset;
3433 void QQuickItem::setBaselineOffset(qreal offset)
3436 if (offset == d->baselineOffset)
3439 d->baselineOffset = offset;
3440 d->baselineOffsetValid = true;
3442 for (int ii = 0; ii < d->changeListeners.count(); ++ii) {
3443 const QQuickItemPrivate::ChangeListener &change = d->changeListeners.at(ii);
3444 if (change.types & QQuickItemPrivate::Geometry) {
3445 QQuickAnchorsPrivate *anchor = change.listener->anchorPrivate();
3447 anchor->updateVerticalAnchors();
3451 if (d->_anchors && (d->_anchors->usedAnchors() & QQuickAnchors::BaselineAnchor))
3452 QQuickAnchorsPrivate::get(d->_anchors)->updateVerticalAnchors();
3454 emit baselineOffsetChanged(offset);
3459 * Schedules a call to updatePaintNode() for this item.
3461 * The call to QQuickItem::updatePaintNode() will always happen if the
3462 * item is showing in a QQuickWindow.
3464 * Only items which specifies QQuickItem::ItemHasContents are allowed
3465 * to call QQuickItem::update().
3467 void QQuickItem::update()
3470 Q_ASSERT(flags() & ItemHasContents);
3471 d->dirty(QQuickItemPrivate::Content);
3475 Schedules a polish event for this item.
3477 When the scene graph processes the request, it will call updatePolish()
3480 void QQuickItem::polish()
3483 if (!d->polishScheduled) {
3484 d->polishScheduled = true;
3486 QQuickWindowPrivate *p = QQuickWindowPrivate::get(d->window);
3487 bool maybeupdate = p->itemsToPolish.isEmpty();
3488 p->itemsToPolish.insert(this);
3489 if (maybeupdate) d->window->maybeUpdate();
3495 \qmlmethod object QtQuick2::Item::mapFromItem(Item item, real x, real y)
3496 \qmlmethod object QtQuick2::Item::mapFromItem(Item item, real x, real y, real width, real height)
3498 Maps the point (\a x, \a y) or rect (\a x, \a y, \a width, \a height), which is in \a
3499 item's coordinate system, to this item's coordinate system, and returns an object with \c x and
3500 \c y (and optionally \c width and \c height) properties matching the mapped coordinate.
3502 If \a item is a \c null value, this maps the point or rect from the coordinate system of
3508 void QQuickItem::mapFromItem(QQmlV8Function *args) const
3510 if (args->Length() != 0) {
3511 v8::Local<v8::Value> item = (*args)[0];
3512 QV8Engine *engine = args->engine();
3514 QQuickItem *itemObj = 0;
3515 if (!item->IsNull())
3516 itemObj = qobject_cast<QQuickItem*>(engine->toQObject(item));
3518 if (!itemObj && !item->IsNull()) {
3519 qmlInfo(this) << "mapFromItem() given argument \"" << engine->toString(item->ToString())
3520 << "\" which is neither null nor an Item";
3524 v8::Local<v8::Object> rv = v8::Object::New();
3525 args->returnValue(rv);
3527 qreal x = (args->Length() > 1)?(*args)[1]->NumberValue():0;
3528 qreal y = (args->Length() > 2)?(*args)[2]->NumberValue():0;
3530 if (args->Length() > 3) {
3531 qreal w = (*args)[3]->NumberValue();
3532 qreal h = (args->Length() > 4)?(*args)[4]->NumberValue():0;
3534 QRectF r = mapRectFromItem(itemObj, QRectF(x, y, w, h));
3536 rv->Set(v8::String::New("x"), v8::Number::New(r.x()));
3537 rv->Set(v8::String::New("y"), v8::Number::New(r.y()));
3538 rv->Set(v8::String::New("width"), v8::Number::New(r.width()));
3539 rv->Set(v8::String::New("height"), v8::Number::New(r.height()));
3541 QPointF p = mapFromItem(itemObj, QPointF(x, y));
3543 rv->Set(v8::String::New("x"), v8::Number::New(p.x()));
3544 rv->Set(v8::String::New("y"), v8::Number::New(p.y()));
3552 QTransform QQuickItem::itemTransform(QQuickItem *other, bool *ok) const
3554 Q_D(const QQuickItem);
3556 // XXX todo - we need to be able to handle common parents better and detect
3560 QTransform t = d->itemToWindowTransform();
3561 if (other) t *= QQuickItemPrivate::get(other)->windowToItemTransform();
3567 \qmlmethod object QtQuick2::Item::mapToItem(Item item, real x, real y)
3568 \qmlmethod object QtQuick2::Item::mapToItem(Item item, real x, real y, real width, real height)
3570 Maps the point (\a x, \a y) or rect (\a x, \a y, \a width, \a height), which is in this
3571 item's coordinate system, to \a item's coordinate system, and returns an object with \c x and
3572 \c y (and optionally \c width and \c height) properties matching the mapped coordinate.
3574 If \a item is a \c null value, this maps the point or rect to the coordinate system of the
3580 void QQuickItem::mapToItem(QQmlV8Function *args) const
3582 if (args->Length() != 0) {
3583 v8::Local<v8::Value> item = (*args)[0];
3584 QV8Engine *engine = args->engine();
3586 QQuickItem *itemObj = 0;
3587 if (!item->IsNull())
3588 itemObj = qobject_cast<QQuickItem*>(engine->toQObject(item));
3590 if (!itemObj && !item->IsNull()) {
3591 qmlInfo(this) << "mapToItem() given argument \"" << engine->toString(item->ToString())
3592 << "\" which is neither null nor an Item";
3596 v8::Local<v8::Object> rv = v8::Object::New();
3597 args->returnValue(rv);
3599 qreal x = (args->Length() > 1)?(*args)[1]->NumberValue():0;
3600 qreal y = (args->Length() > 2)?(*args)[2]->NumberValue():0;
3602 if (args->Length() > 3) {
3603 qreal w = (*args)[3]->NumberValue();
3604 qreal h = (args->Length() > 4)?(*args)[4]->NumberValue():0;
3606 QRectF r = mapRectToItem(itemObj, QRectF(x, y, w, h));
3608 rv->Set(v8::String::New("x"), v8::Number::New(r.x()));
3609 rv->Set(v8::String::New("y"), v8::Number::New(r.y()));
3610 rv->Set(v8::String::New("width"), v8::Number::New(r.width()));
3611 rv->Set(v8::String::New("height"), v8::Number::New(r.height()));
3613 QPointF p = mapToItem(itemObj, QPointF(x, y));
3615 rv->Set(v8::String::New("x"), v8::Number::New(p.x()));
3616 rv->Set(v8::String::New("y"), v8::Number::New(p.y()));
3622 \qmlmethod QtQuick2::Item::forceActiveFocus()
3624 Forces active focus on the item.
3626 This method sets focus on the item and ensures that all ancestor
3627 FocusScope objects in the object hierarchy are also given \l focus.
3632 Forces active focus on the item.
3634 This method sets focus on the item and ensures that all ancestor
3635 FocusScope objects in the object hierarchy are also given \l focus.
3639 void QQuickItem::forceActiveFocus()
3642 QQuickItem *parent = parentItem();
3644 if (parent->flags() & QQuickItem::ItemIsFocusScope) {
3645 parent->setFocus(true);
3647 parent = parent->parentItem();
3652 \qmlmethod QtQuick2::Item::childAt(real x, real y)
3654 Returns the first visible child item found at point (\a x, \a y) within
3655 the coordinate system of this item.
3657 Returns \c null if there is no such item.
3660 Returns the first visible child item found at point (\a x, \a y) within
3661 the coordinate system of this item.
3663 Returns 0 if there is no such item.
3665 QQuickItem *QQuickItem::childAt(qreal x, qreal y) const
3667 // XXX todo - should this include transform etc.?
3668 const QList<QQuickItem *> children = childItems();
3669 for (int i = children.count()-1; i >= 0; --i) {
3670 QQuickItem *child = children.at(i);
3671 if (child->isVisible() && child->x() <= x
3672 && child->x() + child->width() >= x
3674 && child->y() + child->height() >= y)
3680 QQmlListProperty<QObject> QQuickItemPrivate::resources()
3682 return QQmlListProperty<QObject>(q_func(), 0, QQuickItemPrivate::resources_append,
3683 QQuickItemPrivate::resources_count,
3684 QQuickItemPrivate::resources_at,
3685 QQuickItemPrivate::resources_clear);
3689 \qmlproperty list<Item> QtQuick2::Item::children
3690 \qmlproperty list<Object> QtQuick2::Item::resources
3692 The children property contains the list of visual children of this item.
3693 The resources property contains non-visual resources that you want to
3696 It is not generally necessary to refer to these properties when adding
3697 child items or resources, as the default \l data property will
3698 automatically assign child objects to the \c children and \c resources
3699 properties as appropriate. See the \l data documentation for details.
3702 \property QQuickItem::children
3706 \fn void QQuickItem::childrenChanged()
3709 QQmlListProperty<QQuickItem> QQuickItemPrivate::children()
3711 return QQmlListProperty<QQuickItem>(q_func(), 0, QQuickItemPrivate::children_append,
3712 QQuickItemPrivate::children_count,
3713 QQuickItemPrivate::children_at,
3714 QQuickItemPrivate::children_clear);
3719 \qmlproperty real QtQuick2::Item::visibleChildren
3720 This read-only property lists all of the item's children that are currently visible.
3721 Note that a child's visibility may have changed explicitly, or because the visibility
3722 of this (it's parent) item or another grandparent changed.
3725 \property QQuickItem::visibleChildren
3729 \fn void QQuickItem::visibleChildrenChanged()
3732 QQmlListProperty<QQuickItem> QQuickItemPrivate::visibleChildren()
3734 return QQmlListProperty<QQuickItem>(q_func(), 0, QQuickItemPrivate::visibleChildren_append,
3735 QQuickItemPrivate::visibleChildren_count,
3736 QQuickItemPrivate::visibleChildren_at);
3741 \qmlproperty list<State> QtQuick2::Item::states
3743 This property holds the list of possible states for this item. To change
3744 the state of this item, set the \l state property to one of these states,
3745 or set the \l state property to an empty string to revert the item to its
3748 This property is specified as a list of \l State objects. For example,
3749 below is an item with "red_color" and "blue_color" states:
3756 width: 100; height: 100
3761 PropertyChanges { target: root; color: "red" }
3765 PropertyChanges { target: root; color: "blue" }
3771 See \l{Qt Quick States} and \l{Animation and Transitions in Qt Quick} for
3772 more details on using states and transitions.
3777 \property QQuickItem::states
3780 QQmlListProperty<QQuickState> QQuickItemPrivate::states()
3782 return _states()->statesProperty();
3786 \qmlproperty list<Transition> QtQuick2::Item::transitions
3788 This property holds the list of transitions for this item. These define the
3789 transitions to be applied to the item whenever it changes its \l state.
3791 This property is specified as a list of \l Transition objects. For example:
3808 See \l{Qt Quick States} and \l{Animation and Transitions in Qt Quick} for
3809 more details on using states and transitions.
3814 \property QQuickItem::transitions
3817 QQmlListProperty<QQuickTransition> QQuickItemPrivate::transitions()
3819 return _states()->transitionsProperty();
3822 QString QQuickItemPrivate::state() const
3827 return _stateGroup->state();
3830 void QQuickItemPrivate::setState(const QString &state)
3832 _states()->setState(state);
3836 \qmlproperty string QtQuick2::Item::state
3838 This property holds the name of the current state of the item.
3840 If the item is in its default state — that is, no explicit state has been
3841 set — then this property holds an empty string. Likewise, you can return
3842 an item to its default state by setting this property to an empty string.
3844 \sa {Qt Quick States}
3847 \property QQuickItem::state
3849 This property holds the name of the current state of the item.
3851 If the item is in its default state — that is, no explicit state has been
3852 set — then this property holds an empty string. Likewise, you can return
3853 an item to its default state by setting this property to an empty string.
3855 \sa {Qt Quick States}
3857 QString QQuickItem::state() const
3859 Q_D(const QQuickItem);
3863 void QQuickItem::setState(const QString &state)
3870 \qmlproperty list<Transform> QtQuick2::Item::transform
3871 This property holds the list of transformations to apply.
3873 For more information see \l Transform.
3876 \property QQuickItem::transform
3882 QQmlListProperty<QQuickTransform> QQuickItem::transform()
3884 return QQmlListProperty<QQuickTransform>(this, 0, QQuickItemPrivate::transform_append,
3885 QQuickItemPrivate::transform_count,
3886 QQuickItemPrivate::transform_at,
3887 QQuickItemPrivate::transform_clear);
3892 Derived classes should call the base class method before adding their own action to
3893 perform at classBegin.
3895 void QQuickItem::classBegin()
3898 d->componentComplete = false;
3900 d->_stateGroup->classBegin();
3902 d->_anchors->classBegin();
3903 if (d->extra.isAllocated() && d->extra->layer)
3904 d->extra->layer->classBegin();
3909 Derived classes should call the base class method before adding their own actions to
3910 perform at componentComplete.
3912 void QQuickItem::componentComplete()
3915 d->componentComplete = true;
3917 d->_stateGroup->componentComplete();
3919 d->_anchors->componentComplete();
3920 QQuickAnchorsPrivate::get(d->_anchors)->updateOnComplete();
3923 if (d->extra.isAllocated() && d->extra->layer)
3924 d->extra->layer->componentComplete();
3926 if (d->extra.isAllocated() && d->extra->keyHandler)
3927 d->extra->keyHandler->componentComplete();
3929 if (d->extra.isAllocated() && d->extra->contents)
3930 d->extra->contents->complete();
3932 if (d->window && d->dirtyAttributes) {
3933 d->addToDirtyList();
3934 QQuickWindowPrivate::get(d->window)->dirtyItem(this);
3938 QQuickStateGroup *QQuickItemPrivate::_states()
3942 _stateGroup = new QQuickStateGroup;
3943 if (!componentComplete)
3944 _stateGroup->classBegin();
3945 qmlobject_connect(_stateGroup, QQuickStateGroup, SIGNAL(stateChanged(QString)),
3946 q, QQuickItem, SIGNAL(stateChanged(QString)))
3952 QPointF QQuickItemPrivate::computeTransformOrigin() const
3956 case QQuickItem::TopLeft:
3957 return QPointF(0, 0);
3958 case QQuickItem::Top:
3959 return QPointF(width / 2., 0);
3960 case QQuickItem::TopRight:
3961 return QPointF(width, 0);
3962 case QQuickItem::Left:
3963 return QPointF(0, height / 2.);
3964 case QQuickItem::Center:
3965 return QPointF(width / 2., height / 2.);
3966 case QQuickItem::Right:
3967 return QPointF(width, height / 2.);
3968 case QQuickItem::BottomLeft:
3969 return QPointF(0, height);
3970 case QQuickItem::Bottom:
3971 return QPointF(width / 2., height);
3972 case QQuickItem::BottomRight:
3973 return QPointF(width, height);
3977 void QQuickItemPrivate::transformChanged()
3979 if (extra.isAllocated() && extra->layer)
3980 extra->layer->updateMatrix();
3983 void QQuickItemPrivate::deliverKeyEvent(QKeyEvent *e)
3987 Q_ASSERT(e->isAccepted());
3988 if (extra.isAllocated() && extra->keyHandler) {
3989 if (e->type() == QEvent::KeyPress)
3990 extra->keyHandler->keyPressed(e, false);
3992 extra->keyHandler->keyReleased(e, false);
3994 if (e->isAccepted())
4000 if (e->type() == QEvent::KeyPress)
4001 q->keyPressEvent(e);
4003 q->keyReleaseEvent(e);
4005 if (e->isAccepted())
4008 if (extra.isAllocated() && extra->keyHandler) {
4011 if (e->type() == QEvent::KeyPress)
4012 extra->keyHandler->keyPressed(e, true);
4014 extra->keyHandler->keyReleased(e, true);
4018 void QQuickItemPrivate::deliverInputMethodEvent(QInputMethodEvent *e)
4022 Q_ASSERT(e->isAccepted());
4023 if (extra.isAllocated() && extra->keyHandler) {
4024 extra->keyHandler->inputMethodEvent(e, false);
4026 if (e->isAccepted())
4032 q->inputMethodEvent(e);
4034 if (e->isAccepted())
4037 if (extra.isAllocated() && extra->keyHandler) {
4040 extra->keyHandler->inputMethodEvent(e, true);
4044 void QQuickItemPrivate::deliverFocusEvent(QFocusEvent *e)
4048 if (e->type() == QEvent::FocusIn) {
4051 q->focusOutEvent(e);
4055 void QQuickItemPrivate::deliverMouseEvent(QMouseEvent *e)
4059 Q_ASSERT(e->isAccepted());
4061 switch (e->type()) {
4063 Q_ASSERT(!"Unknown event type");
4064 case QEvent::MouseMove:
4065 q->mouseMoveEvent(e);
4067 case QEvent::MouseButtonPress:
4068 q->mousePressEvent(e);
4070 case QEvent::MouseButtonRelease:
4071 q->mouseReleaseEvent(e);
4073 case QEvent::MouseButtonDblClick:
4074 q->mouseDoubleClickEvent(e);
4079 void QQuickItemPrivate::deliverWheelEvent(QWheelEvent *e)
4085 void QQuickItemPrivate::deliverTouchEvent(QTouchEvent *e)
4091 void QQuickItemPrivate::deliverHoverEvent(QHoverEvent *e)
4094 switch (e->type()) {
4096 Q_ASSERT(!"Unknown event type");
4097 case QEvent::HoverEnter:
4098 q->hoverEnterEvent(e);
4100 case QEvent::HoverLeave:
4101 q->hoverLeaveEvent(e);
4103 case QEvent::HoverMove:
4104 q->hoverMoveEvent(e);
4109 #ifndef QT_NO_DRAGANDDROP
4110 void QQuickItemPrivate::deliverDragEvent(QEvent *e)
4113 switch (e->type()) {
4115 Q_ASSERT(!"Unknown event type");
4116 case QEvent::DragEnter:
4117 q->dragEnterEvent(static_cast<QDragEnterEvent *>(e));
4119 case QEvent::DragLeave:
4120 q->dragLeaveEvent(static_cast<QDragLeaveEvent *>(e));
4122 case QEvent::DragMove:
4123 q->dragMoveEvent(static_cast<QDragMoveEvent *>(e));
4126 q->dropEvent(static_cast<QDropEvent *>(e));
4130 #endif // QT_NO_DRAGANDDROP
4135 void QQuickItem::itemChange(ItemChange change, const ItemChangeData &value)
4142 Notify input method on updated query values if needed. \a queries indicates
4143 the changed attributes.
4145 void QQuickItem::updateInputMethod(Qt::InputMethodQueries queries)
4147 if (hasActiveFocus())
4148 qApp->inputMethod()->update(queries);
4152 // XXX todo - do we want/need this anymore?
4153 QRectF QQuickItem::boundingRect() const
4155 Q_D(const QQuickItem);
4156 return QRectF(0, 0, d->width, d->height);
4160 QRectF QQuickItem::clipRect() const
4162 Q_D(const QQuickItem);
4163 return QRectF(0, 0, d->width, d->height);
4167 \qmlproperty enumeration QtQuick2::Item::transformOrigin
4168 This property holds the origin point around which scale and rotation transform.
4170 Nine transform origins are available, as shown in the image below.
4171 The default transform origin is \c Item.Center.
4173 \image declarative-transformorigin.png
4175 This example rotates an image around its bottom-right corner.
4178 source: "myimage.png"
4179 transformOrigin: Item.BottomRight
4184 To set an arbitrary transform origin point use the \l Scale or \l Rotation
4185 transform types with \l transform.
4188 \property QQuickItem::transformOrigin
4189 This property holds the origin point around which scale and rotation transform.
4191 Nine transform origins are available, as shown in the image below.
4192 The default transform origin is \c Item.Center.
4194 \image declarative-transformorigin.png
4196 QQuickItem::TransformOrigin QQuickItem::transformOrigin() const
4198 Q_D(const QQuickItem);
4202 void QQuickItem::setTransformOrigin(TransformOrigin origin)
4205 if (origin == d->origin())
4208 d->extra.value().origin = origin;
4209 d->dirty(QQuickItemPrivate::TransformOrigin);
4211 emit transformOriginChanged(d->origin());
4215 \property QQuickItem::transformOriginPoint
4221 QPointF QQuickItem::transformOriginPoint() const
4223 Q_D(const QQuickItem);
4224 if (d->extra.isAllocated() && !d->extra->userTransformOriginPoint.isNull())
4225 return d->extra->userTransformOriginPoint;
4226 return d->computeTransformOrigin();
4232 void QQuickItem::setTransformOriginPoint(const QPointF &point)
4235 if (d->extra.value().userTransformOriginPoint == point)
4238 d->extra->userTransformOriginPoint = point;
4239 d->dirty(QQuickItemPrivate::TransformOrigin);
4243 \qmlproperty real QtQuick2::Item::z
4245 Sets the stacking order of sibling items. By default the stacking order is 0.
4247 Items with a higher stacking value are drawn on top of siblings with a
4248 lower stacking order. Items with the same stacking value are drawn
4249 bottom up in the order they appear. Items with a negative stacking
4250 value are drawn under their parent's content.
4252 The following example shows the various effects of stacking order.
4256 \li \image declarative-item_stacking1.png
4257 \li Same \c z - later children above earlier children:
4262 width: 100; height: 100
4266 x: 50; y: 50; width: 100; height: 100
4271 \li \image declarative-item_stacking2.png
4272 \li Higher \c z on top:
4278 width: 100; height: 100
4282 x: 50; y: 50; width: 100; height: 100
4287 \li \image declarative-item_stacking3.png
4288 \li Same \c z - children above parents:
4293 width: 100; height: 100
4296 x: 50; y: 50; width: 100; height: 100
4302 \li \image declarative-item_stacking4.png
4303 \li Lower \c z below:
4308 width: 100; height: 100
4312 x: 50; y: 50; width: 100; height: 100
4320 \property QQuickItem::z
4322 Sets the stacking order of sibling items. By default the stacking order is 0.
4324 Items with a higher stacking value are drawn on top of siblings with a
4325 lower stacking order. Items with the same stacking value are drawn
4326 bottom up in the order they appear. Items with a negative stacking
4327 value are drawn under their parent's content.
4329 The following example shows the various effects of stacking order.
4333 \li \image declarative-item_stacking1.png
4334 \li Same \c z - later children above earlier children:
4339 width: 100; height: 100
4343 x: 50; y: 50; width: 100; height: 100
4348 \li \image declarative-item_stacking2.png
4349 \li Higher \c z on top:
4355 width: 100; height: 100
4359 x: 50; y: 50; width: 100; height: 100
4364 \li \image declarative-item_stacking3.png
4365 \li Same \c z - children above parents:
4370 width: 100; height: 100
4373 x: 50; y: 50; width: 100; height: 100
4379 \li \image declarative-item_stacking4.png
4380 \li Lower \c z below:
4385 width: 100; height: 100
4389 x: 50; y: 50; width: 100; height: 100
4396 qreal QQuickItem::z() const
4398 Q_D(const QQuickItem);
4402 void QQuickItem::setZ(qreal v)
4408 d->extra.value().z = v;
4410 d->dirty(QQuickItemPrivate::ZValue);
4411 if (d->parentItem) {
4412 QQuickItemPrivate::get(d->parentItem)->dirty(QQuickItemPrivate::ChildrenStackingChanged);
4413 QQuickItemPrivate::get(d->parentItem)->markSortedChildrenDirty(this);
4418 if (d->extra.isAllocated() && d->extra->layer)
4419 d->extra->layer->updateZ();
4423 \qmlproperty real QtQuick2::Item::rotation
4424 This property holds the rotation of the item in degrees clockwise around
4425 its transformOrigin.
4427 The default value is 0 degrees (that is, no rotation).
4431 \li \image declarative-rotation.png
4436 width: 100; height: 100
4439 x: 25; y: 25; width: 50; height: 50
4446 \sa transform, Rotation
4449 \property QQuickItem::rotation
4450 This property holds the rotation of the item in degrees clockwise around
4451 its transformOrigin.
4453 The default value is 0 degrees (that is, no rotation).
4457 \li \image declarative-rotation.png
4462 width: 100; height: 100
4465 x: 25; y: 25; width: 50; height: 50
4472 \sa transform, Rotation
4474 qreal QQuickItem::rotation() const
4476 Q_D(const QQuickItem);
4477 return d->rotation();
4480 void QQuickItem::setRotation(qreal r)
4483 if (d->rotation() == r)
4486 d->extra.value().rotation = r;
4488 d->dirty(QQuickItemPrivate::BasicTransform);
4490 d->itemChange(ItemRotationHasChanged, r);
4492 emit rotationChanged();
4496 \qmlproperty real QtQuick2::Item::scale
4497 This property holds the scale factor for this item.
4499 A scale of less than 1.0 causes the item to be rendered at a smaller
4500 size, and a scale greater than 1.0 renders the item at a larger size.
4501 A negative scale causes the item to be mirrored when rendered.
4503 The default value is 1.0.
4505 Scaling is applied from the transformOrigin.
4509 \li \image declarative-scale.png
4516 width: 100; height: 100
4520 width: 25; height: 25
4525 x: 25; y: 25; width: 50; height: 50
4532 \sa transform, Scale
4535 \property QQuickItem::scale
4536 This property holds the scale factor for this item.
4538 A scale of less than 1.0 causes the item to be rendered at a smaller
4539 size, and a scale greater than 1.0 renders the item at a larger size.
4540 A negative scale causes the item to be mirrored when rendered.
4542 The default value is 1.0.
4544 Scaling is applied from the transformOrigin.
4548 \li \image declarative-scale.png
4555 width: 100; height: 100
4559 width: 25; height: 25
4564 x: 25; y: 25; width: 50; height: 50
4571 \sa transform, Scale
4573 qreal QQuickItem::scale() const
4575 Q_D(const QQuickItem);
4579 void QQuickItem::setScale(qreal s)
4582 if (d->scale() == s)
4585 d->extra.value().scale = s;
4587 d->dirty(QQuickItemPrivate::BasicTransform);
4589 emit scaleChanged();
4593 \qmlproperty real QtQuick2::Item::opacity
4595 This property holds the opacity of the item. Opacity is specified as a
4596 number between 0.0 (fully transparent) and 1.0 (fully opaque). The default
4599 When this property is set, the specified opacity is also applied
4600 individually to child items. This may have an unintended effect in some
4601 circumstances. For example in the second set of rectangles below, the red
4602 rectangle has specified an opacity of 0.5, which affects the opacity of
4603 its blue child rectangle even though the child has not specified an opacity.
4607 \li \image declarative-item_opacity1.png
4613 width: 100; height: 100
4616 x: 50; y: 50; width: 100; height: 100
4622 \li \image declarative-item_opacity2.png
4629 width: 100; height: 100
4632 x: 50; y: 50; width: 100; height: 100
4639 Changing an item's opacity does not affect whether the item receives user
4640 input events. (In contrast, setting \l visible property to \c false stops
4641 mouse events, and setting the \l enabled property to \c false stops mouse
4642 and keyboard events, and also removes active focus from the item.)
4647 \property QQuickItem::opacity
4649 This property holds the opacity of the item. Opacity is specified as a
4650 number between 0.0 (fully transparent) and 1.0 (fully opaque). The default
4653 When this property is set, the specified opacity is also applied
4654 individually to child items. This may have an unintended effect in some
4655 circumstances. For example in the second set of rectangles below, the red
4656 rectangle has specified an opacity of 0.5, which affects the opacity of
4657 its blue child rectangle even though the child has not specified an opacity.
4661 \li \image declarative-item_opacity1.png
4667 width: 100; height: 100
4670 x: 50; y: 50; width: 100; height: 100
4676 \li \image declarative-item_opacity2.png
4683 width: 100; height: 100
4686 x: 50; y: 50; width: 100; height: 100
4693 Changing an item's opacity does not affect whether the item receives user
4694 input events. (In contrast, setting \l visible property to \c false stops
4695 mouse events, and setting the \l enabled property to \c false stops mouse
4696 and keyboard events, and also removes active focus from the item.)
4700 qreal QQuickItem::opacity() const
4702 Q_D(const QQuickItem);
4703 return d->opacity();
4706 void QQuickItem::setOpacity(qreal o)
4709 if (d->opacity() == o)
4712 d->extra.value().opacity = o;
4714 d->dirty(QQuickItemPrivate::OpacityValue);
4716 d->itemChange(ItemOpacityHasChanged, o);
4718 emit opacityChanged();
4722 \qmlproperty bool QtQuick2::Item::visible
4724 This property holds whether the item is visible. By default this is true.
4726 Setting this property directly affects the \c visible value of child
4727 items. When set to \c false, the \c visible values of all child items also
4728 become \c false. When set to \c true, the \c visible values of child items
4729 are returned to \c true, unless they have explicitly been set to \c false.
4731 (Because of this flow-on behavior, using the \c visible property may not
4732 have the intended effect if a property binding should only respond to
4733 explicit property changes. In such cases it may be better to use the
4734 \l opacity property instead.)
4736 If this property is set to \c false, the item will no longer receive mouse
4737 events, but will continue to receive key events and will retain the keyboard
4738 \l focus if it has been set. (In contrast, setting the \l enabled property
4739 to \c false stops both mouse and keyboard events, and also removes focus
4742 \note This property's value is only affected by changes to this property or
4743 the parent's \c visible property. It does not change, for example, if this
4744 item moves off-screen, or if the \l opacity changes to 0.
4746 \sa opacity, enabled
4749 \property QQuickItem::visible
4751 This property holds whether the item is visible. By default this is true.
4753 Setting this property directly affects the \c visible value of child
4754 items. When set to \c false, the \c visible values of all child items also
4755 become \c false. When set to \c true, the \c visible values of child items
4756 are returned to \c true, unless they have explicitly been set to \c false.
4758 (Because of this flow-on behavior, using the \c visible property may not
4759 have the intended effect if a property binding should only respond to
4760 explicit property changes. In such cases it may be better to use the
4761 \l opacity property instead.)
4763 If this property is set to \c false, the item will no longer receive mouse
4764 events, but will continue to receive key events and will retain the keyboard
4765 \l focus if it has been set. (In contrast, setting the \l enabled property
4766 to \c false stops both mouse and keyboard events, and also removes focus
4769 \note This property's value is only affected by changes to this property or
4770 the parent's \c visible property. It does not change, for example, if this
4771 item moves off-screen, or if the \l opacity changes to 0.
4773 \sa opacity, enabled
4775 bool QQuickItem::isVisible() const
4777 Q_D(const QQuickItem);
4778 return d->effectiveVisible;
4781 void QQuickItem::setVisible(bool v)
4784 if (v == d->explicitVisible)
4787 d->explicitVisible = v;
4789 d->dirty(QQuickItemPrivate::Visible);
4791 const bool childVisibilityChanged = d->setEffectiveVisibleRecur(d->calcEffectiveVisible());
4792 if (childVisibilityChanged && d->parentItem)
4793 emit d->parentItem->visibleChildrenChanged(); // signal the parent, not this!
4797 \qmlproperty bool QtQuick2::Item::enabled
4799 This property holds whether the item receives mouse and keyboard events.
4800 By default this is true.
4802 Setting this property directly affects the \c enabled value of child
4803 items. When set to \c false, the \c enabled values of all child items also
4804 become \c false. When set to \c true, the \c enabled values of child items
4805 are returned to \c true, unless they have explicitly been set to \c false.
4807 Setting this property to \c false automatically causes \l activeFocus to be
4808 set to \c false, and this item will longer receive keyboard events.
4813 \property QQuickItem::enabled
4815 This property holds whether the item receives mouse and keyboard events.
4816 By default this is true.
4818 Setting this property directly affects the \c enabled value of child
4819 items. When set to \c false, the \c enabled values of all child items also
4820 become \c false. When set to \c true, the \c enabled values of child items
4821 are returned to \c true, unless they have explicitly been set to \c false.
4823 Setting this property to \c false automatically causes \l activeFocus to be
4824 set to \c false, and this item will longer receive keyboard events.
4828 bool QQuickItem::isEnabled() const
4830 Q_D(const QQuickItem);
4831 return d->effectiveEnable;
4834 void QQuickItem::setEnabled(bool e)
4837 if (e == d->explicitEnable)
4840 d->explicitEnable = e;
4842 QQuickItem *scope = parentItem();
4843 while (scope && !scope->isFocusScope())
4844 scope = scope->parentItem();
4846 d->setEffectiveEnableRecur(scope, d->calcEffectiveEnable());
4849 bool QQuickItemPrivate::calcEffectiveVisible() const
4851 // XXX todo - Should the effective visible of an element with no parent just be the current
4852 // effective visible? This would prevent pointless re-processing in the case of an element
4853 // moving to/from a no-parent situation, but it is different from what graphics view does.
4854 return explicitVisible && (!parentItem || QQuickItemPrivate::get(parentItem)->effectiveVisible);
4857 bool QQuickItemPrivate::setEffectiveVisibleRecur(bool newEffectiveVisible)
4861 if (newEffectiveVisible && !explicitVisible) {
4862 // This item locally overrides visibility
4863 return false; // effective visibility didn't change
4866 if (newEffectiveVisible == effectiveVisible) {
4867 // No change necessary
4868 return false; // effective visibility didn't change
4871 effectiveVisible = newEffectiveVisible;
4873 if (parentItem) QQuickItemPrivate::get(parentItem)->dirty(ChildrenStackingChanged);
4876 QQuickWindowPrivate *windowPriv = QQuickWindowPrivate::get(window);
4877 if (windowPriv->mouseGrabberItem == q)
4881 bool childVisibilityChanged = false;
4882 for (int ii = 0; ii < childItems.count(); ++ii)
4883 childVisibilityChanged |= QQuickItemPrivate::get(childItems.at(ii))->setEffectiveVisibleRecur(newEffectiveVisible);
4885 itemChange(QQuickItem::ItemVisibleHasChanged, effectiveVisible);
4886 #ifndef QT_NO_ACCESSIBILITY
4888 QAccessibleEvent ev(q, effectiveVisible ? QAccessible::ObjectShow : QAccessible::ObjectHide);
4889 QAccessible::updateAccessibility(&ev);
4892 emit q->visibleChanged();
4893 if (childVisibilityChanged)
4894 emit q->visibleChildrenChanged();
4896 return true; // effective visibility DID change
4899 bool QQuickItemPrivate::calcEffectiveEnable() const
4901 // XXX todo - Should the effective enable of an element with no parent just be the current
4902 // effective enable? This would prevent pointless re-processing in the case of an element
4903 // moving to/from a no-parent situation, but it is different from what graphics view does.
4904 return explicitEnable && (!parentItem || QQuickItemPrivate::get(parentItem)->effectiveEnable);
4907 void QQuickItemPrivate::setEffectiveEnableRecur(QQuickItem *scope, bool newEffectiveEnable)
4911 if (newEffectiveEnable && !explicitEnable) {
4912 // This item locally overrides enable
4916 if (newEffectiveEnable == effectiveEnable) {
4917 // No change necessary
4921 effectiveEnable = newEffectiveEnable;
4924 QQuickWindowPrivate *windowPriv = QQuickWindowPrivate::get(window);
4925 if (windowPriv->mouseGrabberItem == q)
4927 if (scope && !effectiveEnable && activeFocus) {
4928 windowPriv->clearFocusInScope(
4929 scope, q, QQuickWindowPrivate::DontChangeFocusProperty | QQuickWindowPrivate::DontChangeSubFocusItem);
4933 for (int ii = 0; ii < childItems.count(); ++ii) {
4934 QQuickItemPrivate::get(childItems.at(ii))->setEffectiveEnableRecur(
4935 (flags & QQuickItem::ItemIsFocusScope) && scope ? q : scope, newEffectiveEnable);
4938 if (window && scope && effectiveEnable && focus) {
4939 QQuickWindowPrivate::get(window)->setFocusInScope(
4940 scope, q, QQuickWindowPrivate::DontChangeFocusProperty | QQuickWindowPrivate::DontChangeSubFocusItem);
4943 emit q->enabledChanged();
4946 QString QQuickItemPrivate::dirtyToString() const
4948 #define DIRTY_TO_STRING(value) if (dirtyAttributes & value) { \
4949 if (!rv.isEmpty()) \
4950 rv.append(QLatin1String("|")); \
4951 rv.append(QLatin1String(#value)); \
4954 // QString rv = QLatin1String("0x") + QString::number(dirtyAttributes, 16);
4957 DIRTY_TO_STRING(TransformOrigin);
4958 DIRTY_TO_STRING(Transform);
4959 DIRTY_TO_STRING(BasicTransform);
4960 DIRTY_TO_STRING(Position);
4961 DIRTY_TO_STRING(Size);
4962 DIRTY_TO_STRING(ZValue);
4963 DIRTY_TO_STRING(Content);
4964 DIRTY_TO_STRING(Smooth);
4965 DIRTY_TO_STRING(OpacityValue);
4966 DIRTY_TO_STRING(ChildrenChanged);
4967 DIRTY_TO_STRING(ChildrenStackingChanged);
4968 DIRTY_TO_STRING(ParentChanged);
4969 DIRTY_TO_STRING(Clip);
4970 DIRTY_TO_STRING(Window);
4971 DIRTY_TO_STRING(EffectReference);
4972 DIRTY_TO_STRING(Visible);
4973 DIRTY_TO_STRING(HideReference);
4974 DIRTY_TO_STRING(Antialiasing);
4979 void QQuickItemPrivate::dirty(DirtyType type)
4982 if (type & (TransformOrigin | Transform | BasicTransform | Position | Size))
4985 if (!(dirtyAttributes & type) || (window && !prevDirtyItem)) {
4986 dirtyAttributes |= type;
4987 if (window && componentComplete) {
4989 QQuickWindowPrivate::get(window)->dirtyItem(q);
4994 void QQuickItemPrivate::addToDirtyList()
4999 if (!prevDirtyItem) {
5000 Q_ASSERT(!nextDirtyItem);
5002 QQuickWindowPrivate *p = QQuickWindowPrivate::get(window);
5003 nextDirtyItem = p->dirtyItemList;
5004 if (nextDirtyItem) QQuickItemPrivate::get(nextDirtyItem)->prevDirtyItem = &nextDirtyItem;
5005 prevDirtyItem = &p->dirtyItemList;
5006 p->dirtyItemList = q;
5009 Q_ASSERT(prevDirtyItem);
5012 void QQuickItemPrivate::removeFromDirtyList()
5014 if (prevDirtyItem) {
5015 if (nextDirtyItem) QQuickItemPrivate::get(nextDirtyItem)->prevDirtyItem = prevDirtyItem;
5016 *prevDirtyItem = nextDirtyItem;
5020 Q_ASSERT(!prevDirtyItem);
5021 Q_ASSERT(!nextDirtyItem);
5024 void QQuickItemPrivate::refFromEffectItem(bool hide)
5026 ++extra.value().effectRefCount;
5027 if (1 == extra->effectRefCount) {
5028 dirty(EffectReference);
5029 if (parentItem) QQuickItemPrivate::get(parentItem)->dirty(ChildrenStackingChanged);
5032 if (++extra->hideRefCount == 1)
5033 dirty(HideReference);
5037 void QQuickItemPrivate::derefFromEffectItem(bool unhide)
5039 Q_ASSERT(extra->effectRefCount);
5040 --extra->effectRefCount;
5041 if (0 == extra->effectRefCount) {
5042 dirty(EffectReference);
5043 if (parentItem) QQuickItemPrivate::get(parentItem)->dirty(ChildrenStackingChanged);
5046 if (--extra->hideRefCount == 0)
5047 dirty(HideReference);
5051 void QQuickItemPrivate::setCulled(bool cull)
5057 if ((cull && ++extra.value().hideRefCount == 1) || (!cull && --extra.value().hideRefCount == 0))
5058 dirty(HideReference);
5061 void QQuickItemPrivate::itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &data)
5065 case QQuickItem::ItemChildAddedChange:
5066 q->itemChange(change, data);
5067 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5068 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5069 if (change.types & QQuickItemPrivate::Children) {
5070 change.listener->itemChildAdded(q, data.item);
5074 case QQuickItem::ItemChildRemovedChange:
5075 q->itemChange(change, data);
5076 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5077 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5078 if (change.types & QQuickItemPrivate::Children) {
5079 change.listener->itemChildRemoved(q, data.item);
5083 case QQuickItem::ItemSceneChange:
5084 q->itemChange(change, data);
5086 case QQuickItem::ItemVisibleHasChanged:
5087 q->itemChange(change, data);
5088 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5089 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5090 if (change.types & QQuickItemPrivate::Visibility) {
5091 change.listener->itemVisibilityChanged(q);
5095 case QQuickItem::ItemParentHasChanged:
5096 q->itemChange(change, data);
5097 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5098 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5099 if (change.types & QQuickItemPrivate::Parent) {
5100 change.listener->itemParentChanged(q, data.item);
5104 case QQuickItem::ItemOpacityHasChanged:
5105 q->itemChange(change, data);
5106 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5107 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5108 if (change.types & QQuickItemPrivate::Opacity) {
5109 change.listener->itemOpacityChanged(q);
5113 case QQuickItem::ItemActiveFocusHasChanged:
5114 q->itemChange(change, data);
5116 case QQuickItem::ItemRotationHasChanged:
5117 q->itemChange(change, data);
5118 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5119 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5120 if (change.types & QQuickItemPrivate::Rotation) {
5121 change.listener->itemRotationChanged(q);
5129 \qmlproperty bool QtQuick2::Item::smooth
5131 Primarily used in image based items to decide if the item should use smooth
5132 sampling or not. Smooth sampling is performed using linear interpolation, while
5133 non-smooth is performed using nearest neighbor.
5135 In Qt Quick 2.0, this property has minimal impact on performance.
5140 \property QQuickItem::smooth
5141 \brief Specifies whether the item is smoothed or not
5143 Primarily used in image based items to decide if the item should use smooth
5144 sampling or not. Smooth sampling is performed using linear interpolation, while
5145 non-smooth is performed using nearest neighbor.
5147 In Qt Quick 2.0, this property has minimal impact on performance.
5151 bool QQuickItem::smooth() const
5153 Q_D(const QQuickItem);
5156 void QQuickItem::setSmooth(bool smooth)
5159 if (d->smooth == smooth)
5163 d->dirty(QQuickItemPrivate::Smooth);
5165 emit smoothChanged(smooth);
5169 \qmlproperty bool QtQuick2::Item::antialiasing
5171 Primarily used in Rectangle and image based elements to decide if the item should
5172 use antialiasing or not. Items with antialiasing enabled require more memory and
5173 are potentially slower to render.
5175 The default is false.
5178 \property QQuickItem::antialiasing
5179 \brief Specifies whether the item is antialiased or not
5181 Primarily used in Rectangle and image based elements to decide if the item should
5182 use antialiasing or not. Items with antialiasing enabled require more memory and
5183 are potentially slower to render.
5185 The default is false.
5187 bool QQuickItem::antialiasing() const
5189 Q_D(const QQuickItem);
5190 return d->antialiasing;
5192 void QQuickItem::setAntialiasing(bool antialiasing)
5195 if (d->antialiasing == antialiasing)
5198 d->antialiasing = antialiasing;
5199 d->dirty(QQuickItemPrivate::Antialiasing);
5201 emit antialiasingChanged(antialiasing);
5205 Returns the item flags for this item.
5209 QQuickItem::Flags QQuickItem::flags() const
5211 Q_D(const QQuickItem);
5212 return (QQuickItem::Flags)d->flags;
5216 Enables the specified \a flag for this item if \a enabled is true;
5217 if \a enabled is false, the flag is disabled.
5219 These provide various hints for the item; for example, the
5220 ItemClipsChildrenToShape flag indicates that all children of this
5221 item should be clipped to fit within the item area.
5223 void QQuickItem::setFlag(Flag flag, bool enabled)
5227 setFlags((Flags)(d->flags | (quint32)flag));
5229 setFlags((Flags)(d->flags & ~(quint32)flag));
5233 Enables the specified \a flags for this item.
5237 void QQuickItem::setFlags(Flags flags)
5241 if ((flags & ItemIsFocusScope) != (d->flags & ItemIsFocusScope)) {
5242 if (flags & ItemIsFocusScope && !d->childItems.isEmpty() && d->window) {
5243 qWarning("QQuickItem: Cannot set FocusScope once item has children and is in a window.");
5244 flags &= ~ItemIsFocusScope;
5245 } else if (d->flags & ItemIsFocusScope) {
5246 qWarning("QQuickItem: Cannot unset FocusScope flag.");
5247 flags |= ItemIsFocusScope;
5251 if ((flags & ItemClipsChildrenToShape ) != (d->flags & ItemClipsChildrenToShape))
5252 d->dirty(QQuickItemPrivate::Clip);
5258 \qmlproperty real QtQuick2::Item::x
5259 \qmlproperty real QtQuick2::Item::y
5260 \qmlproperty real QtQuick2::Item::width
5261 \qmlproperty real QtQuick2::Item::height
5263 Defines the item's position and size.
5265 The (x,y) position is relative to the \l parent.
5268 Item { x: 100; y: 100; width: 100; height: 100 }
5272 \property QQuickItem::x
5274 Defines the item's x position relative to its parent.
5277 \property QQuickItem::y
5279 Defines the item's y position relative to its parent.
5281 qreal QQuickItem::x() const
5283 Q_D(const QQuickItem);
5287 qreal QQuickItem::y() const
5289 Q_D(const QQuickItem);
5294 \property QQuickItem::pos
5300 QPointF QQuickItem::pos() const
5302 Q_D(const QQuickItem);
5303 return QPointF(d->x, d->y);
5306 void QQuickItem::setX(qreal v)
5315 d->dirty(QQuickItemPrivate::Position);
5317 geometryChanged(QRectF(x(), y(), width(), height()),
5318 QRectF(oldx, y(), width(), height()));
5321 void QQuickItem::setY(qreal v)
5330 d->dirty(QQuickItemPrivate::Position);
5332 geometryChanged(QRectF(x(), y(), width(), height()),
5333 QRectF(x(), oldy, width(), height()));
5339 void QQuickItem::setPos(const QPointF &pos)
5342 if (QPointF(d->x, d->y) == pos)
5351 d->dirty(QQuickItemPrivate::Position);
5353 geometryChanged(QRectF(x(), y(), width(), height()),
5354 QRectF(oldx, oldy, width(), height()));
5358 \property QQuickItem::width
5360 This property holds the width of this item.
5362 qreal QQuickItem::width() const
5364 Q_D(const QQuickItem);
5368 void QQuickItem::setWidth(qreal w)
5374 d->widthValid = true;
5378 qreal oldWidth = d->width;
5381 d->dirty(QQuickItemPrivate::Size);
5383 geometryChanged(QRectF(x(), y(), width(), height()),
5384 QRectF(x(), y(), oldWidth, height()));
5387 void QQuickItem::resetWidth()
5390 d->widthValid = false;
5391 setImplicitWidth(implicitWidth());
5394 void QQuickItemPrivate::implicitWidthChanged()
5397 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5398 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5399 if (change.types & QQuickItemPrivate::ImplicitWidth) {
5400 change.listener->itemImplicitWidthChanged(q);
5403 emit q->implicitWidthChanged();
5406 qreal QQuickItemPrivate::getImplicitWidth() const
5408 return implicitWidth;
5411 Returns the width of the item that is implied by other properties that determine the content.
5413 qreal QQuickItem::implicitWidth() const
5415 Q_D(const QQuickItem);
5416 return d->getImplicitWidth();
5420 \qmlproperty real QtQuick2::Item::implicitWidth
5421 \qmlproperty real QtQuick2::Item::implicitHeight
5423 Defines the natural width or height of the Item if no \l width or \l height is specified.
5425 The default implicit size for most items is 0x0, however some items have an inherent
5426 implicit size which cannot be overridden, e.g. Image, Text.
5428 Setting the implicit size is useful for defining components that have a preferred size
5429 based on their content, for example:
5436 property alias icon: image.source
5437 property alias label: text.text
5438 implicitWidth: text.implicitWidth + image.implicitWidth
5439 implicitHeight: Math.max(text.implicitHeight, image.implicitHeight)
5444 anchors.left: image.right; anchors.right: parent.right
5445 anchors.verticalCenter: parent.verticalCenter
5450 \b Note: using implicitWidth of Text or TextEdit and setting the width explicitly
5451 incurs a performance penalty as the text must be laid out twice.
5454 \property QQuickItem::implicitWidth
5455 \property QQuickItem::implicitHeight
5457 Defines the natural width or height of the Item if no \l width or \l height is specified.
5459 The default implicit size for most items is 0x0, however some items have an inherent
5460 implicit size which cannot be overridden, e.g. Image, Text.
5462 Setting the implicit size is useful for defining components that have a preferred size
5463 based on their content, for example:
5470 property alias icon: image.source
5471 property alias label: text.text
5472 implicitWidth: text.implicitWidth + image.implicitWidth
5473 implicitHeight: Math.max(text.implicitHeight, image.implicitHeight)
5478 anchors.left: image.right; anchors.right: parent.right
5479 anchors.verticalCenter: parent.verticalCenter
5484 \b Note: using implicitWidth of Text or TextEdit and setting the width explicitly
5485 incurs a performance penalty as the text must be laid out twice.
5487 void QQuickItem::setImplicitWidth(qreal w)
5490 bool changed = w != d->implicitWidth;
5491 d->implicitWidth = w;
5492 if (d->width == w || widthValid()) {
5494 d->implicitWidthChanged();
5495 if (d->width == w || widthValid())
5500 qreal oldWidth = d->width;
5503 d->dirty(QQuickItemPrivate::Size);
5505 geometryChanged(QRectF(x(), y(), width(), height()),
5506 QRectF(x(), y(), oldWidth, height()));
5509 d->implicitWidthChanged();
5513 Returns whether the width property has been set explicitly.
5515 bool QQuickItem::widthValid() const
5517 Q_D(const QQuickItem);
5518 return d->widthValid;
5522 \property QQuickItem::height
5524 This property holds the height of this item.
5526 qreal QQuickItem::height() const
5528 Q_D(const QQuickItem);
5532 void QQuickItem::setHeight(qreal h)
5538 d->heightValid = true;
5542 qreal oldHeight = d->height;
5545 d->dirty(QQuickItemPrivate::Size);
5547 geometryChanged(QRectF(x(), y(), width(), height()),
5548 QRectF(x(), y(), width(), oldHeight));
5551 void QQuickItem::resetHeight()
5554 d->heightValid = false;
5555 setImplicitHeight(implicitHeight());
5558 void QQuickItemPrivate::implicitHeightChanged()
5561 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5562 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5563 if (change.types & QQuickItemPrivate::ImplicitHeight) {
5564 change.listener->itemImplicitHeightChanged(q);
5567 emit q->implicitHeightChanged();
5570 qreal QQuickItemPrivate::getImplicitHeight() const
5572 return implicitHeight;
5575 qreal QQuickItem::implicitHeight() const
5577 Q_D(const QQuickItem);
5578 return d->getImplicitHeight();
5581 void QQuickItem::setImplicitHeight(qreal h)
5584 bool changed = h != d->implicitHeight;
5585 d->implicitHeight = h;
5586 if (d->height == h || heightValid()) {
5588 d->implicitHeightChanged();
5589 if (d->height == h || heightValid())
5594 qreal oldHeight = d->height;
5597 d->dirty(QQuickItemPrivate::Size);
5599 geometryChanged(QRectF(x(), y(), width(), height()),
5600 QRectF(x(), y(), width(), oldHeight));
5603 d->implicitHeightChanged();
5609 void QQuickItem::setImplicitSize(qreal w, qreal h)
5612 bool wChanged = w != d->implicitWidth;
5613 bool hChanged = h != d->implicitHeight;
5615 d->implicitWidth = w;
5616 d->implicitHeight = h;
5620 if (d->width == w || widthValid()) {
5622 d->implicitWidthChanged();
5623 wDone = d->width == w || widthValid();
5626 if (d->height == h || heightValid()) {
5628 d->implicitHeightChanged();
5629 hDone = d->height == h || heightValid();
5635 qreal oldWidth = d->width;
5636 qreal oldHeight = d->height;
5642 d->dirty(QQuickItemPrivate::Size);
5644 geometryChanged(QRectF(x(), y(), width(), height()),
5645 QRectF(x(), y(), oldWidth, oldHeight));
5647 if (!wDone && wChanged)
5648 d->implicitWidthChanged();
5649 if (!hDone && hChanged)
5650 d->implicitHeightChanged();
5654 Returns whether the height property has been set explicitly.
5656 bool QQuickItem::heightValid() const
5658 Q_D(const QQuickItem);
5659 return d->heightValid;
5665 void QQuickItem::setSize(const QSizeF &size)
5668 d->heightValid = true;
5669 d->widthValid = true;
5671 if (QSizeF(d->width, d->height) == size)
5674 qreal oldHeight = d->height;
5675 qreal oldWidth = d->width;
5676 d->height = size.height();
5677 d->width = size.width();
5679 d->dirty(QQuickItemPrivate::Size);
5681 geometryChanged(QRectF(x(), y(), width(), height()),
5682 QRectF(x(), y(), oldWidth, oldHeight));
5686 \qmlproperty bool QtQuick2::Item::activeFocus
5688 This read-only property indicates whether the item has active focus.
5690 If activeFocus is true, either this item is the one that currently
5691 receives keyboard input, or it is a FocusScope ancestor of the item
5692 that currently receives keyboard input.
5694 Usually, activeFocus is gained by setting \l focus on an item and its
5695 enclosing FocusScope objects. In the following example, the \c input
5696 and \c focusScope objects will have active focus, while the root
5697 rectangle object will not.
5703 width: 100; height: 100
5717 \sa focus, {Keyboard Focus in Qt Quick}
5720 \property QQuickItem::activeFocus
5722 This read-only property indicates whether the item has active focus.
5724 If activeFocus is true, either this item is the one that currently
5725 receives keyboard input, or it is a FocusScope ancestor of the item
5726 that currently receives keyboard input.
5728 Usually, activeFocus is gained by setting \l focus on an item and its
5729 enclosing FocusScope objects. In the following example, the \c input
5730 and \c focusScope objects will have active focus, while the root
5731 rectangle object will not.
5737 width: 100; height: 100
5750 \sa focus, {Keyboard Focus in Qt Quick}
5752 bool QQuickItem::hasActiveFocus() const
5754 Q_D(const QQuickItem);
5755 return d->activeFocus;
5759 \qmlproperty bool QtQuick2::Item::focus
5761 This property holds whether the item has focus within the enclosing
5762 FocusScope. If true, this item will gain active focus when the
5763 enclosing FocusScope gains active focus.
5765 In the following example, \c input will be given active focus when
5766 \c scope gains active focus:
5772 width: 100; height: 100
5785 For the purposes of this property, the scene as a whole is assumed
5786 to act like a focus scope. On a practical level, that means the
5787 following QML will give active focus to \c input on startup.
5791 width: 100; height: 100
5800 \sa activeFocus, {Keyboard Focus in Qt Quick}
5803 \property QQuickItem::focus
5805 This property holds whether the item has focus within the enclosing
5806 FocusScope. If true, this item will gain active focus when the
5807 enclosing FocusScope gains active focus.
5809 In the following example, \c input will be given active focus when
5810 \c scope gains active focus:
5816 width: 100; height: 100
5829 For the purposes of this property, the scene as a whole is assumed
5830 to act like a focus scope. On a practical level, that means the
5831 following QML will give active focus to \c input on startup.
5835 width: 100; height: 100
5844 \sa activeFocus, {Keyboard Focus in Qt Quick}
5846 bool QQuickItem::hasFocus() const
5848 Q_D(const QQuickItem);
5852 void QQuickItem::setFocus(bool focus)
5855 if (d->focus == focus)
5858 if (d->window || d->parentItem) {
5859 // Need to find our nearest focus scope
5860 QQuickItem *scope = parentItem();
5861 while (scope && !scope->isFocusScope() && scope->parentItem())
5862 scope = scope->parentItem();
5865 QQuickWindowPrivate::get(d->window)->setFocusInScope(scope, this);
5867 QQuickWindowPrivate::get(d->window)->clearFocusInScope(scope, this);
5869 // do the focus changes from setFocusInScope/clearFocusInScope that are
5870 // unrelated to a window
5871 QVarLengthArray<QQuickItem *, 20> changed;
5872 QQuickItem *oldSubFocusItem = QQuickItemPrivate::get(scope)->subFocusItem;
5873 if (oldSubFocusItem) {
5874 QQuickItemPrivate::get(oldSubFocusItem)->updateSubFocusItem(scope, false);
5875 QQuickItemPrivate::get(oldSubFocusItem)->focus = false;
5876 changed << oldSubFocusItem;
5877 } else if (!scope->isFocusScope() && scope->hasFocus()) {
5878 QQuickItemPrivate::get(scope)->focus = false;
5881 d->updateSubFocusItem(scope, focus);
5885 emit focusChanged(focus);
5887 QQuickWindowPrivate::notifyFocusChangesRecur(changed.data(), changed.count() - 1);
5890 QVarLengthArray<QQuickItem *, 20> changed;
5891 QQuickItem *oldSubFocusItem = d->subFocusItem;
5892 if (!isFocusScope() && oldSubFocusItem) {
5893 QQuickItemPrivate::get(oldSubFocusItem)->updateSubFocusItem(this, false);
5894 QQuickItemPrivate::get(oldSubFocusItem)->focus = false;
5895 changed << oldSubFocusItem;
5900 emit focusChanged(focus);
5902 QQuickWindowPrivate::notifyFocusChangesRecur(changed.data(), changed.count() - 1);
5907 Returns true if this item is a focus scope, and false otherwise.
5909 bool QQuickItem::isFocusScope() const
5911 return flags() & ItemIsFocusScope;
5915 If this item is a focus scope, this returns the item in its focus chain
5916 that currently has focus.
5918 Returns 0 if this item is not a focus scope.
5920 QQuickItem *QQuickItem::scopedFocusItem() const
5922 Q_D(const QQuickItem);
5923 if (!isFocusScope())
5926 return d->subFocusItem;
5930 Returns the mouse buttons accepted by this item.
5932 The default value is Qt::NoButton; that is, no mouse buttons are accepted.
5934 If an item does not accept the mouse button for a particular mouse event,
5935 the mouse event will not be delivered to the item and will be delivered
5936 to the next item in the item hierarchy instead.
5938 Qt::MouseButtons QQuickItem::acceptedMouseButtons() const
5940 Q_D(const QQuickItem);
5941 return d->acceptedMouseButtons();
5945 Sets the mouse buttons accepted by this item to \a buttons.
5947 void QQuickItem::setAcceptedMouseButtons(Qt::MouseButtons buttons)
5950 if (buttons & Qt::LeftButton)
5953 d->extra.clearFlag();
5955 buttons &= ~Qt::LeftButton;
5956 if (buttons || d->extra.isAllocated())
5957 d->extra.value().acceptedMouseButtons = buttons;
5961 Returns whether mouse events of this item's children should be filtered
5964 \sa setFiltersChildMouseEvents(), childMouseEventFilter()
5966 bool QQuickItem::filtersChildMouseEvents() const
5968 Q_D(const QQuickItem);
5969 return d->filtersChildMouseEvents;
5973 Sets whether mouse events of this item's children should be filtered
5976 If \a filter is true, childMouseEventFilter() will be called when
5977 a mouse event is triggered for a child item.
5979 \sa filtersChildMouseEvents()
5981 void QQuickItem::setFiltersChildMouseEvents(bool filter)
5984 d->filtersChildMouseEvents = filter;
5990 bool QQuickItem::isUnderMouse() const
5992 Q_D(const QQuickItem);
5996 QPointF cursorPos = QGuiApplicationPrivate::lastCursorPosition;
5997 return contains(mapFromScene(d->window->mapFromGlobal(cursorPos.toPoint())));
6001 Returns whether hover events are accepted by this item.
6003 The default value is false.
6005 If this is false, then the item will not receive any hover events through
6006 the hoverEnterEvent(), hoverMoveEvent() and hoverLeaveEvent() functions.
6008 bool QQuickItem::acceptHoverEvents() const
6010 Q_D(const QQuickItem);
6011 return d->hoverEnabled;
6015 If \a enabled is true, this sets the item to accept hover events;
6016 otherwise, hover events are not accepted by this item.
6018 \sa acceptHoverEvents()
6020 void QQuickItem::setAcceptHoverEvents(bool enabled)
6023 d->hoverEnabled = enabled;
6026 #ifndef QT_NO_CURSOR
6030 Returns the cursor shape for this item.
6032 The mouse cursor will assume this shape when it is over this
6033 item, unless an override cursor is set.
6034 See the \l{Qt::CursorShape}{list of predefined cursor objects} for a
6035 range of useful shapes.
6037 If no cursor shape has been set this returns a cursor with the Qt::ArrowCursor shape, however
6038 another cursor shape may be displayed if an overlapping item has a valid cursor.
6040 \sa setCursor(), unsetCursor()
6043 QCursor QQuickItem::cursor() const
6045 Q_D(const QQuickItem);
6046 return d->extra.isAllocated()
6052 Sets the \a cursor shape for this item.
6054 \sa cursor(), unsetCursor()
6057 void QQuickItem::setCursor(const QCursor &cursor)
6061 Qt::CursorShape oldShape = d->extra.isAllocated() ? d->extra->cursor.shape() : Qt::ArrowCursor;
6063 if (oldShape != cursor.shape() || oldShape >= Qt::LastCursor || cursor.shape() >= Qt::LastCursor) {
6064 d->extra.value().cursor = cursor;
6066 QQuickWindowPrivate *windowPrivate = QQuickWindowPrivate::get(d->window);
6067 if (windowPrivate->cursorItem == this)
6068 d->window->setCursor(cursor);
6072 if (!d->hasCursor) {
6073 d->hasCursor = true;
6075 QPointF pos = d->window->mapFromGlobal(QGuiApplicationPrivate::lastCursorPosition.toPoint());
6076 if (contains(mapFromScene(pos)))
6077 QQuickWindowPrivate::get(d->window)->updateCursor(pos);
6083 Clears the cursor shape for this item.
6085 \sa cursor(), setCursor()
6088 void QQuickItem::unsetCursor()
6093 d->hasCursor = false;
6094 if (d->extra.isAllocated())
6095 d->extra->cursor = QCursor();
6098 QQuickWindowPrivate *windowPrivate = QQuickWindowPrivate::get(d->window);
6099 if (windowPrivate->cursorItem == this) {
6100 QPointF pos = d->window->mapFromGlobal(QGuiApplicationPrivate::lastCursorPosition.toPoint());
6101 windowPrivate->updateCursor(pos);
6109 Grabs the mouse input.
6111 This item will receive all mouse events until ungrabMouse() is called.
6113 \warning This function should be used with caution.
6115 void QQuickItem::grabMouse()
6120 QQuickWindowPrivate *windowPriv = QQuickWindowPrivate::get(d->window);
6121 if (windowPriv->mouseGrabberItem == this)
6124 QQuickItem *oldGrabber = windowPriv->mouseGrabberItem;
6125 windowPriv->mouseGrabberItem = this;
6127 QEvent ev(QEvent::UngrabMouse);
6128 d->window->sendEvent(oldGrabber, &ev);
6133 Releases the mouse grab following a call to grabMouse().
6135 void QQuickItem::ungrabMouse()
6140 QQuickWindowPrivate *windowPriv = QQuickWindowPrivate::get(d->window);
6141 if (windowPriv->mouseGrabberItem != this) {
6142 qWarning("QQuickItem::ungrabMouse(): Item is not the mouse grabber.");
6146 windowPriv->mouseGrabberItem = 0;
6148 QEvent ev(QEvent::UngrabMouse);
6149 d->window->sendEvent(this, &ev);
6154 Returns whether mouse input should exclusively remain with this item.
6156 \sa setKeepMouseGrab()
6158 bool QQuickItem::keepMouseGrab() const
6160 Q_D(const QQuickItem);
6161 return d->keepMouse;
6165 Sets whether the mouse input should remain exclusively with this item.
6167 This is useful for items that wish to grab and keep mouse
6168 interaction following a predefined gesture. For example,
6169 an item that is interested in horizontal mouse movement
6170 may set keepMouseGrab to true once a threshold has been
6171 exceeded. Once keepMouseGrab has been set to true, filtering
6172 items will not react to mouse events.
6174 If \a keep is false, a filtering item may steal the grab. For example,
6175 \l Flickable may attempt to steal a mouse grab if it detects that the
6176 user has begun to move the viewport.
6180 void QQuickItem::setKeepMouseGrab(bool keep)
6183 d->keepMouse = keep;
6187 Grabs the touch points specified by \a ids.
6189 These touch points will be owned by the item until
6190 they are released. Alternatively, the grab can be stolen
6191 by a filtering item like Flickable. Use setKeepTouchGrab()
6192 to prevent the grab from being stolen.
6194 \sa ungrabTouchPoints(), setKeepTouchGrab()
6196 void QQuickItem::grabTouchPoints(const QVector<int> &ids)
6201 QQuickWindowPrivate *windowPriv = QQuickWindowPrivate::get(d->window);
6203 QSet<QQuickItem*> ungrab;
6204 for (int i = 0; i < ids.count(); ++i) {
6205 QQuickItem *oldGrabber = windowPriv->itemForTouchPointId.value(ids.at(i));
6206 if (oldGrabber == this)
6209 windowPriv->itemForTouchPointId[ids.at(i)] = this;
6211 ungrab.insert(oldGrabber);
6213 foreach (QQuickItem *oldGrabber, ungrab)
6214 oldGrabber->touchUngrabEvent();
6218 Ungrabs the touch points owned by this item.
6220 \sa grabTouchPoints()
6222 void QQuickItem::ungrabTouchPoints()
6227 QQuickWindowPrivate *windowPriv = QQuickWindowPrivate::get(d->window);
6229 QMutableHashIterator<int, QQuickItem*> i(windowPriv->itemForTouchPointId);
6230 while (i.hasNext()) {
6232 if (i.value() == this)
6239 Returns whether the touch points grabbed by this item should exclusively
6240 remain with this item.
6242 \sa setKeepTouchGrab(), keepMouseGrab()
6244 bool QQuickItem::keepTouchGrab() const
6246 Q_D(const QQuickItem);
6247 return d->keepTouch;
6251 Sets whether the touch points grabbed by this item should remain
6252 exclusively with this item.
6254 This is useful for items that wish to grab and keep specific touch
6255 points following a predefined gesture. For example,
6256 an item that is interested in horizontal touch point movement
6257 may set setKeepTouchGrab to true once a threshold has been
6258 exceeded. Once setKeepTouchGrab has been set to true, filtering
6259 items will not react to the relevant touch points.
6261 If \a keep is false, a filtering item may steal the grab. For example,
6262 \l Flickable may attempt to steal a touch point grab if it detects that the
6263 user has begun to move the viewport.
6265 \sa keepTouchGrab(), setKeepMouseGrab()
6267 void QQuickItem::setKeepTouchGrab(bool keep)
6270 d->keepTouch = keep;
6274 \qmlmethod object QtQuick2::Item::contains(point point)
6276 Returns true if this item contains \a point, which is in local coordinates;
6277 returns false otherwise.
6280 Returns true if this item contains \a point, which is in local coordinates;
6281 returns false otherwise.
6283 This function can be overwritten in order to handle point collisions in items
6284 with custom shapes. The default implementation checks if the point is inside
6285 the item's bounding rect.
6287 Note that this method is generally used to check whether the item is under the mouse cursor,
6288 and for that reason, the implementation of this function should be as light-weight
6291 bool QQuickItem::contains(const QPointF &point) const
6293 Q_D(const QQuickItem);
6294 return QRectF(0, 0, d->width, d->height).contains(point);
6298 Maps the given \a point in this item's coordinate system to the equivalent
6299 point within \a item's coordinate system, and returns the mapped
6302 If \a item is 0, this maps \a point to the coordinate system of the
6305 \sa {Concepts - Visual Coordinates in Qt Quick}
6307 QPointF QQuickItem::mapToItem(const QQuickItem *item, const QPointF &point) const
6309 QPointF p = mapToScene(point);
6311 p = item->mapFromScene(p);
6316 Maps the given \a point in this item's coordinate system to the equivalent
6317 point within the scene's coordinate system, and returns the mapped
6320 \sa {Concepts - Visual Coordinates in Qt Quick}
6322 QPointF QQuickItem::mapToScene(const QPointF &point) const
6324 Q_D(const QQuickItem);
6325 return d->itemToWindowTransform().map(point);
6329 Maps the given \a rect in this item's coordinate system to the equivalent
6330 rectangular area within \a item's coordinate system, and returns the mapped
6333 If \a item is 0, this maps \a rect to the coordinate system of the
6336 \sa {Concepts - Visual Coordinates in Qt Quick}
6338 QRectF QQuickItem::mapRectToItem(const QQuickItem *item, const QRectF &rect) const
6340 Q_D(const QQuickItem);
6341 QTransform t = d->itemToWindowTransform();
6343 t *= QQuickItemPrivate::get(item)->windowToItemTransform();
6344 return t.mapRect(rect);
6348 Maps the given \a rect in this item's coordinate system to the equivalent
6349 rectangular area within the scene's coordinate system, and returns the mapped
6352 \sa {Concepts - Visual Coordinates in Qt Quick}
6354 QRectF QQuickItem::mapRectToScene(const QRectF &rect) const
6356 Q_D(const QQuickItem);
6357 return d->itemToWindowTransform().mapRect(rect);
6361 Maps the given \a point in \a item's coordinate system to the equivalent
6362 point within this item's coordinate system, and returns the mapped
6365 If \a item is 0, this maps \a point from the coordinate system of the
6368 \sa {Concepts - Visual Coordinates in Qt Quick}
6370 QPointF QQuickItem::mapFromItem(const QQuickItem *item, const QPointF &point) const
6372 QPointF p = item?item->mapToScene(point):point;
6373 return mapFromScene(p);
6377 Maps the given \a point in the scene's coordinate system to the equivalent
6378 point within this item's coordinate system, and returns the mapped
6381 \sa {Concepts - Visual Coordinates in Qt Quick}
6383 QPointF QQuickItem::mapFromScene(const QPointF &point) const
6385 Q_D(const QQuickItem);
6386 return d->windowToItemTransform().map(point);
6390 Maps the given \a rect in \a item's coordinate system to the equivalent
6391 rectangular area within this item's coordinate system, and returns the mapped
6394 If \a item is 0, this maps \a rect from the coordinate system of the
6397 \sa {Concepts - Visual Coordinates in Qt Quick}
6399 QRectF QQuickItem::mapRectFromItem(const QQuickItem *item, const QRectF &rect) const
6401 Q_D(const QQuickItem);
6402 QTransform t = item?QQuickItemPrivate::get(item)->itemToWindowTransform():QTransform();
6403 t *= d->windowToItemTransform();
6404 return t.mapRect(rect);
6408 Maps the given \a rect in the scene's coordinate system to the equivalent
6409 rectangular area within this item's coordinate system, and returns the mapped
6412 \sa {Concepts - Visual Coordinates in Qt Quick}
6414 QRectF QQuickItem::mapRectFromScene(const QRectF &rect) const
6416 Q_D(const QQuickItem);
6417 return d->windowToItemTransform().mapRect(rect);
6421 \property QQuickItem::anchors
6426 \property QQuickItem::left
6431 \property QQuickItem::right
6436 \property QQuickItem::horizontalCenter
6441 \property QQuickItem::top
6446 \property QQuickItem::bottom
6451 \property QQuickItem::verticalCenter
6456 \property QQuickItem::baseline
6461 \property QQuickItem::data
6466 \property QQuickItem::resources
6473 bool QQuickItem::event(QEvent *ev)
6476 if (ev->type() == QEvent::PolishRequest) {
6478 d->polishScheduled = false;
6482 return QObject::event(ev);
6485 if (ev->type() == QEvent::InputMethodQuery) {
6486 QInputMethodQueryEvent *query = static_cast<QInputMethodQueryEvent *>(ev);
6487 Qt::InputMethodQueries queries = query->queries();
6488 for (uint i = 0; i < 32; ++i) {
6489 Qt::InputMethodQuery q = (Qt::InputMethodQuery)(int)(queries & (1<<i));
6491 QVariant v = inputMethodQuery(q);
6492 query->setValue(q, v);
6497 } else if (ev->type() == QEvent::InputMethod) {
6498 inputMethodEvent(static_cast<QInputMethodEvent *>(ev));
6501 return QObject::event(ev);
6504 #ifndef QT_NO_DEBUG_STREAM
6505 QDebug operator<<(QDebug debug, QQuickItem *item)
6508 debug << "QQuickItem(0)";
6512 debug << item->metaObject()->className() << "(this =" << ((void*)item)
6513 << ", name=" << item->objectName()
6514 << ", parent =" << ((void*)item->parentItem())
6515 << ", geometry =" << QRectF(item->pos(), QSizeF(item->width(), item->height()))
6516 << ", z =" << item->z() << ')';
6521 qint64 QQuickItemPrivate::consistentTime = -1;
6522 void QQuickItemPrivate::setConsistentTime(qint64 t)
6527 class QElapsedTimerConsistentTimeHack
6531 t1 = QQuickItemPrivate::consistentTime;
6535 return QQuickItemPrivate::consistentTime - t1;
6538 qint64 val = QQuickItemPrivate::consistentTime - t1;
6539 t1 = QQuickItemPrivate::consistentTime;
6549 void QQuickItemPrivate::start(QElapsedTimer &t)
6551 if (QQuickItemPrivate::consistentTime == -1)
6554 ((QElapsedTimerConsistentTimeHack*)&t)->start();
6557 qint64 QQuickItemPrivate::elapsed(QElapsedTimer &t)
6559 if (QQuickItemPrivate::consistentTime == -1)
6562 return ((QElapsedTimerConsistentTimeHack*)&t)->elapsed();
6565 qint64 QQuickItemPrivate::restart(QElapsedTimer &t)
6567 if (QQuickItemPrivate::consistentTime == -1)
6570 return ((QElapsedTimerConsistentTimeHack*)&t)->restart();
6574 \fn bool QQuickItem::isTextureProvider() const
6576 Returns true if this item is a texture provider. The default
6577 implementation returns false.
6579 This function can be called from any thread.
6582 bool QQuickItem::isTextureProvider() const
6584 Q_D(const QQuickItem);
6585 return d->extra.isAllocated() && d->extra->layer && d->extra->layer->effectSource() ?
6586 d->extra->layer->effectSource()->isTextureProvider() : false;
6590 \fn QSGTextureProvider *QQuickItem::textureProvider() const
6592 Returns the texture provider for an item. The default implementation
6595 This function may only be called on the rendering thread.
6598 QSGTextureProvider *QQuickItem::textureProvider() const
6600 Q_D(const QQuickItem);
6601 return d->extra.isAllocated() && d->extra->layer && d->extra->layer->effectSource() ?
6602 d->extra->layer->effectSource()->textureProvider() : 0;
6606 \property QQuickItem::layer
6609 QQuickItemLayer *QQuickItemPrivate::layer() const
6611 if (!extra.isAllocated() || !extra->layer) {
6612 extra.value().layer = new QQuickItemLayer(const_cast<QQuickItem *>(q_func()));
6613 if (!componentComplete)
6614 extra->layer->classBegin();
6616 return extra->layer;
6619 QQuickItemLayer::QQuickItemLayer(QQuickItem *item)
6624 , m_componentComplete(true)
6625 , m_wrapMode(QQuickShaderEffectSource::ClampToEdge)
6626 , m_format(QQuickShaderEffectSource::RGBA)
6628 , m_effectComponent(0)
6634 QQuickItemLayer::~QQuickItemLayer()
6636 delete m_effectSource;
6641 \qmlproperty bool QtQuick2::Item::layer.enabled
6643 Holds whether the item is layered or not. Layering is disabled by default.
6645 A layered item is rendered into an offscreen surface and cached until
6646 it is changed. Enabling layering for complex QML item hierarchies can
6647 sometimes be an optimization.
6649 None of the other layer properties have any effect when the layer
6652 void QQuickItemLayer::setEnabled(bool e)
6657 if (m_componentComplete) {
6664 emit enabledChanged(e);
6667 void QQuickItemLayer::classBegin()
6669 Q_ASSERT(!m_effectSource);
6670 Q_ASSERT(!m_effect);
6671 m_componentComplete = false;
6674 void QQuickItemLayer::componentComplete()
6676 Q_ASSERT(!m_componentComplete);
6677 m_componentComplete = true;
6682 void QQuickItemLayer::activate()
6684 Q_ASSERT(!m_effectSource);
6685 m_effectSource = new QQuickShaderEffectSource();
6687 QQuickItem *parentItem = m_item->parentItem();
6689 m_effectSource->setParentItem(parentItem);
6690 m_effectSource->stackAfter(m_item);
6693 m_effectSource->setSourceItem(m_item);
6694 m_effectSource->setHideSource(true);
6695 m_effectSource->setSmooth(m_smooth);
6696 m_effectSource->setTextureSize(m_size);
6697 m_effectSource->setSourceRect(m_sourceRect);
6698 m_effectSource->setMipmap(m_mipmap);
6699 m_effectSource->setWrapMode(m_wrapMode);
6700 m_effectSource->setFormat(m_format);
6702 if (m_effectComponent)
6705 m_effectSource->setVisible(m_item->isVisible() && !m_effect);
6712 QQuickItemPrivate *id = QQuickItemPrivate::get(m_item);
6713 id->addItemChangeListener(this, QQuickItemPrivate::Geometry | QQuickItemPrivate::Opacity | QQuickItemPrivate::Parent | QQuickItemPrivate::Visibility | QQuickItemPrivate::SiblingOrder);
6716 void QQuickItemLayer::deactivate()
6718 Q_ASSERT(m_effectSource);
6720 if (m_effectComponent)
6723 delete m_effectSource;
6726 QQuickItemPrivate *id = QQuickItemPrivate::get(m_item);
6727 id->removeItemChangeListener(this, QQuickItemPrivate::Geometry | QQuickItemPrivate::Opacity | QQuickItemPrivate::Parent | QQuickItemPrivate::Visibility | QQuickItemPrivate::SiblingOrder);
6730 void QQuickItemLayer::activateEffect()
6732 Q_ASSERT(m_effectSource);
6733 Q_ASSERT(m_effectComponent);
6734 Q_ASSERT(!m_effect);
6736 QObject *created = m_effectComponent->beginCreate(m_effectComponent->creationContext());
6737 m_effect = qobject_cast<QQuickItem *>(created);
6739 qWarning("Item: layer.effect is not a QML Item.");
6740 m_effectComponent->completeCreate();
6744 QQuickItem *parentItem = m_item->parentItem();
6746 m_effect->setParentItem(parentItem);
6747 m_effect->stackAfter(m_effectSource);
6749 m_effect->setVisible(m_item->isVisible());
6750 m_effect->setProperty(m_name, qVariantFromValue<QObject *>(m_effectSource));
6751 m_effectComponent->completeCreate();
6754 void QQuickItemLayer::deactivateEffect()
6756 Q_ASSERT(m_effectSource);
6757 Q_ASSERT(m_effectComponent);
6765 \qmlproperty Component QtQuick2::Item::layer.effect
6767 Holds the effect that is applied to this layer.
6769 The effect is typically a \l ShaderEffect component, although any \l Item component can be
6770 assigned. The effect should have a source texture property with a name matching \l layer.samplerName.
6772 \sa layer.samplerName
6775 void QQuickItemLayer::setEffect(QQmlComponent *component)
6777 if (component == m_effectComponent)
6780 bool updateNeeded = false;
6781 if (m_effectSource && m_effectComponent) {
6783 updateNeeded = true;
6786 m_effectComponent = component;
6788 if (m_effectSource && m_effectComponent) {
6790 updateNeeded = true;
6798 m_effectSource->setVisible(m_item->isVisible() && !m_effect);
6801 emit effectChanged(component);
6806 \qmlproperty bool QtQuick2::Item::layer.mipmap
6808 If this property is true, mipmaps are generated for the texture.
6810 \note Some OpenGL ES 2 implementations do not support mipmapping of
6811 non-power-of-two textures.
6814 void QQuickItemLayer::setMipmap(bool mipmap)
6816 if (mipmap == m_mipmap)
6821 m_effectSource->setMipmap(m_mipmap);
6823 emit mipmapChanged(mipmap);
6828 \qmlproperty enumeration QtQuick2::Item::layer.format
6830 This property defines the internal OpenGL format of the texture.
6831 Modifying this property makes most sense when the \a layer.effect is also
6832 specified. Depending on the OpenGL implementation, this property might
6833 allow you to save some texture memory.
6836 \li ShaderEffectSource.Alpha - GL_ALPHA
6837 \li ShaderEffectSource.RGB - GL_RGB
6838 \li ShaderEffectSource.RGBA - GL_RGBA
6841 \note Some OpenGL implementations do not support the GL_ALPHA format.
6844 void QQuickItemLayer::setFormat(QQuickShaderEffectSource::Format f)
6851 m_effectSource->setFormat(m_format);
6853 emit formatChanged(m_format);
6858 \qmlproperty enumeration QtQuick2::Item::layer.sourceRect
6860 This property defines the rectangular area of the item that should be
6861 rendered into the texture. The source rectangle can be larger than
6862 the item itself. If the rectangle is null, which is the default,
6863 then the whole item is rendered to the texture.
6866 void QQuickItemLayer::setSourceRect(const QRectF &sourceRect)
6868 if (sourceRect == m_sourceRect)
6870 m_sourceRect = sourceRect;
6873 m_effectSource->setSourceRect(m_sourceRect);
6875 emit sourceRectChanged(sourceRect);
6879 \qmlproperty bool QtQuick2::Item::layer.smooth
6881 Holds whether the layer is smoothly transformed.
6884 void QQuickItemLayer::setSmooth(bool s)
6891 m_effectSource->setSmooth(m_smooth);
6893 emit smoothChanged(s);
6897 \qmlproperty size QtQuick2::Item::layer.textureSize
6899 This property holds the requested pixel size of the layers texture. If it is empty,
6900 which is the default, the size of the item is used.
6902 \note Some platforms have a limit on how small framebuffer objects can be,
6903 which means the actual texture size might be larger than the requested
6907 void QQuickItemLayer::setSize(const QSize &size)
6914 m_effectSource->setTextureSize(size);
6916 emit sizeChanged(size);
6920 \qmlproperty enumeration QtQuick2::Item::layer.wrapMode
6922 This property defines the OpenGL wrap modes associated with the texture.
6923 Modifying this property makes most sense when the \a layer.effect is
6927 \li ShaderEffectSource.ClampToEdge - GL_CLAMP_TO_EDGE both horizontally and vertically
6928 \li ShaderEffectSource.RepeatHorizontally - GL_REPEAT horizontally, GL_CLAMP_TO_EDGE vertically
6929 \li ShaderEffectSource.RepeatVertically - GL_CLAMP_TO_EDGE horizontally, GL_REPEAT vertically
6930 \li ShaderEffectSource.Repeat - GL_REPEAT both horizontally and vertically
6933 \note Some OpenGL ES 2 implementations do not support the GL_REPEAT
6934 wrap mode with non-power-of-two textures.
6937 void QQuickItemLayer::setWrapMode(QQuickShaderEffectSource::WrapMode mode)
6939 if (mode == m_wrapMode)
6944 m_effectSource->setWrapMode(m_wrapMode);
6946 emit wrapModeChanged(mode);
6950 \qmlproperty string QtQuick2::Item::layer.samplerName
6952 Holds the name of the effect's source texture property.
6954 This value must match the name of the effect's source texture property
6955 so that the Item can pass the layer's offscreen surface to the effect correctly.
6957 \sa layer.effect, ShaderEffect
6960 void QQuickItemLayer::setName(const QByteArray &name) {
6964 m_effect->setProperty(m_name, QVariant());
6965 m_effect->setProperty(name, qVariantFromValue<QObject *>(m_effectSource));
6968 emit nameChanged(name);
6971 void QQuickItemLayer::itemOpacityChanged(QQuickItem *item)
6977 void QQuickItemLayer::itemGeometryChanged(QQuickItem *, const QRectF &, const QRectF &)
6982 void QQuickItemLayer::itemParentChanged(QQuickItem *item, QQuickItem *parent)
6985 Q_ASSERT(item == m_item);
6986 Q_ASSERT(parent != m_effectSource);
6987 Q_ASSERT(parent == 0 || parent != m_effect);
6989 m_effectSource->setParentItem(parent);
6991 m_effectSource->stackAfter(m_item);
6994 m_effect->setParentItem(parent);
6996 m_effect->stackAfter(m_effectSource);
7000 void QQuickItemLayer::itemSiblingOrderChanged(QQuickItem *)
7002 m_effectSource->stackAfter(m_item);
7004 m_effect->stackAfter(m_effectSource);
7007 void QQuickItemLayer::itemVisibilityChanged(QQuickItem *)
7009 QQuickItem *l = m_effect ? (QQuickItem *) m_effect : (QQuickItem *) m_effectSource;
7011 l->setVisible(m_item->isVisible());
7014 void QQuickItemLayer::updateZ()
7016 if (!m_componentComplete || !m_enabled)
7018 QQuickItem *l = m_effect ? (QQuickItem *) m_effect : (QQuickItem *) m_effectSource;
7020 l->setZ(m_item->z());
7023 void QQuickItemLayer::updateOpacity()
7025 QQuickItem *l = m_effect ? (QQuickItem *) m_effect : (QQuickItem *) m_effectSource;
7027 l->setOpacity(m_item->opacity());
7030 void QQuickItemLayer::updateGeometry()
7032 QQuickItem *l = m_effect ? (QQuickItem *) m_effect : (QQuickItem *) m_effectSource;
7034 QRectF bounds = m_item->clipRect();
7035 l->setWidth(bounds.width());
7036 l->setHeight(bounds.height());
7037 l->setX(bounds.x() + m_item->x());
7038 l->setY(bounds.y() + m_item->y());
7041 void QQuickItemLayer::updateMatrix()
7043 // Called directly from transformChanged(), so needs some extra
7045 if (!m_componentComplete || !m_enabled)
7047 QQuickItem *l = m_effect ? (QQuickItem *) m_effect : (QQuickItem *) m_effectSource;
7049 QQuickItemPrivate *ld = QQuickItemPrivate::get(l);
7050 l->setScale(m_item->scale());
7051 l->setRotation(m_item->rotation());
7052 ld->transforms = QQuickItemPrivate::get(m_item)->transforms;
7053 if (ld->origin() != QQuickItemPrivate::get(m_item)->origin())
7054 ld->extra.value().origin = QQuickItemPrivate::get(m_item)->origin();
7055 ld->dirty(QQuickItemPrivate::Transform);
7058 QQuickItemPrivate::ExtraData::ExtraData()
7059 : z(0), scale(1), rotation(0), opacity(1),
7060 contents(0), screenAttached(0), layoutDirectionAttached(0),
7061 keyHandler(0), layer(0), effectRefCount(0), hideRefCount(0),
7062 opacityNode(0), clipNode(0), rootNode(0), beforePaintNode(0),
7063 acceptedMouseButtons(0), origin(QQuickItem::Center)
7069 #include <moc_qquickitem.cpp>