1 /****************************************************************************
3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/legal
6 ** This file is part of the QtQml module of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and Digia. For licensing terms and
14 ** conditions see http://qt.digia.com/licensing. For further information
15 ** use the contact form at http://qt.digia.com/contact-us.
17 ** GNU Lesser General Public License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Lesser
19 ** General Public License version 2.1 as published by the Free Software
20 ** Foundation and appearing in the file LICENSE.LGPL included in the
21 ** packaging of this file. Please review the following information to
22 ** ensure the GNU Lesser General Public License version 2.1 requirements
23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25 ** In addition, as a special exception, Digia gives you certain additional
26 ** rights. These rights are described in the Digia Qt LGPL Exception
27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29 ** GNU General Public License Usage
30 ** Alternatively, this file may be used under the terms of the GNU
31 ** General Public License version 3.0 as published by the Free Software
32 ** Foundation and appearing in the file LICENSE.GPL included in the
33 ** packaging of this file. Please review the following information to
34 ** ensure the GNU General Public License version 3.0 requirements will be
35 ** met: http://www.gnu.org/copyleft/gpl.html.
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 specifying
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 QQuickItem::ItemChangeData
1692 \enum QQuickItem::TransformOrigin
1694 Controls the point about which simple transforms like scale apply.
1696 \value TopLeft The top-left corner of the item.
1697 \value Top The center point of the top of the item.
1698 \value TopRight The top-right corner of the item.
1699 \value Left The left most point of the vertical middle.
1700 \value Center The center of the item.
1701 \value Right The right most point of the vertical middle.
1702 \value BottomLeft The bottom-left corner of the item.
1703 \value Bottom The center point of the bottom of the item.
1704 \value BottomRight The bottom-right corner of the item.
1710 \fn void QQuickItem::childrenRectChanged(const QRectF &)
1715 \fn void QQuickItem::baselineOffsetChanged(qreal)
1720 \fn void QQuickItem::stateChanged(const QString &state)
1725 \fn void QQuickItem::parentChanged(QQuickItem *)
1730 \fn void QQuickItem::smoothChanged(bool)
1735 \fn void QQuickItem::antialiasingChanged(bool)
1740 \fn void QQuickItem::clipChanged(bool)
1745 \fn void QQuickItem::transformOriginChanged(TransformOrigin)
1750 \fn void QQuickItem::focusChanged(bool)
1755 \fn void QQuickItem::activeFocusChanged(bool)
1760 \fn void QQuickItem::childrenChanged()
1765 \fn void QQuickItem::opacityChanged()
1770 \fn void QQuickItem::enabledChanged()
1775 \fn void QQuickItem::visibleChanged()
1780 \fn void QQuickItem::visibleChildrenChanged()
1785 \fn void QQuickItem::rotationChanged()
1790 \fn void QQuickItem::scaleChanged()
1795 \fn void QQuickItem::xChanged()
1800 \fn void QQuickItem::yChanged()
1805 \fn void QQuickItem::widthChanged()
1810 \fn void QQuickItem::heightChanged()
1815 \fn void QQuickItem::zChanged()
1820 \fn void QQuickItem::implicitWidthChanged()
1825 \fn void QQuickItem::implicitHeightChanged()
1830 \fn QQuickItem::QQuickItem(QQuickItem *parent)
1832 Constructs a QQuickItem with the given \a parent.
1834 QQuickItem::QQuickItem(QQuickItem* parent)
1835 : QObject(*(new QQuickItemPrivate), parent)
1843 QQuickItem::QQuickItem(QQuickItemPrivate &dd, QQuickItem *parent)
1844 : QObject(dd, parent)
1851 static int qt_item_count = 0;
1853 static void qt_print_item_count()
1855 qDebug("Number of leaked items: %i", qt_item_count);
1861 Destroys the QQuickItem.
1863 QQuickItem::~QQuickItem()
1867 if (qt_item_count < 0)
1868 qDebug("Item destroyed after qt_print_item_count() was called.");
1873 if (d->windowRefCount > 1)
1874 d->windowRefCount = 1; // Make sure window is set to null in next call to derefWindow().
1880 // XXX todo - optimize
1881 while (!d->childItems.isEmpty())
1882 d->childItems.first()->setParentItem(0);
1884 for (int ii = 0; ii < d->changeListeners.count(); ++ii) {
1885 QQuickAnchorsPrivate *anchor = d->changeListeners.at(ii).listener->anchorPrivate();
1887 anchor->clearItem(this);
1891 update item anchors that depended on us unless they are our child (and will also be destroyed),
1892 or our sibling, and our parent is also being destroyed.
1894 for (int ii = 0; ii < d->changeListeners.count(); ++ii) {
1895 QQuickAnchorsPrivate *anchor = d->changeListeners.at(ii).listener->anchorPrivate();
1896 if (anchor && anchor->item && anchor->item->parentItem() && anchor->item->parentItem() != this)
1900 for (int ii = 0; ii < d->changeListeners.count(); ++ii) {
1901 const QQuickItemPrivate::ChangeListener &change = d->changeListeners.at(ii);
1902 if (change.types & QQuickItemPrivate::Destroyed)
1903 change.listener->itemDestroyed(this);
1906 d->changeListeners.clear();
1908 if (d->extra.isAllocated()) {
1909 delete d->extra->contents; d->extra->contents = 0;
1910 delete d->extra->layer; d->extra->layer = 0;
1913 delete d->_anchors; d->_anchors = 0;
1914 delete d->_stateGroup; d->_stateGroup = 0;
1918 \qmlproperty Item QtQuick2::Item::parent
1919 This property holds the visual parent of the item.
1921 \note The concept of the \e {visual parent} differs from that of the
1922 \e {QObject parent}. An item's visual parent may not necessarily be the
1923 same as its object parent. See \l {Concepts - Visual Parent in Qt Quick}
1927 \property QQuickItem::parent
1928 This property holds the visual parent of the item.
1930 \note The concept of the \e {visual parent} differs from that of the
1931 \e {QObject parent}. An item's visual parent may not necessarily be the
1932 same as its object parent. See \l {Concepts - Visual Parent in Qt Quick}
1935 QQuickItem *QQuickItem::parentItem() const
1937 Q_D(const QQuickItem);
1938 return d->parentItem;
1941 void QQuickItem::setParentItem(QQuickItem *parentItem)
1944 if (parentItem == d->parentItem)
1948 QQuickItem *itemAncestor = parentItem->parentItem();
1949 while (itemAncestor != 0) {
1950 if (itemAncestor == this) {
1951 qWarning("QQuickItem::setParentItem: Parent is already part of this items subtree.");
1954 itemAncestor = itemAncestor->parentItem();
1958 d->removeFromDirtyList();
1960 QQuickItem *oldParentItem = d->parentItem;
1961 QQuickItem *scopeFocusedItem = 0;
1963 if (oldParentItem) {
1964 QQuickItemPrivate *op = QQuickItemPrivate::get(oldParentItem);
1966 QQuickItem *scopeItem = 0;
1969 scopeFocusedItem = this;
1970 else if (!isFocusScope() && d->subFocusItem)
1971 scopeFocusedItem = d->subFocusItem;
1973 if (scopeFocusedItem) {
1974 scopeItem = oldParentItem;
1975 while (!scopeItem->isFocusScope() && scopeItem->parentItem())
1976 scopeItem = scopeItem->parentItem();
1978 QQuickWindowPrivate::get(d->window)->clearFocusInScope(scopeItem, scopeFocusedItem,
1979 QQuickWindowPrivate::DontChangeFocusProperty);
1980 if (scopeFocusedItem != this)
1981 QQuickItemPrivate::get(scopeFocusedItem)->updateSubFocusItem(this, true);
1983 QQuickItemPrivate::get(scopeFocusedItem)->updateSubFocusItem(scopeItem, false);
1987 const bool wasVisible = isVisible();
1988 op->removeChild(this);
1990 emit oldParentItem->visibleChildrenChanged();
1992 } else if (d->window) {
1993 QQuickWindowPrivate::get(d->window)->parentlessItems.remove(this);
1996 QQuickWindow *oldParentWindow = oldParentItem ? QQuickItemPrivate::get(oldParentItem)->window : 0;
1997 QQuickWindow *parentWindow = parentItem ? QQuickItemPrivate::get(parentItem)->window : 0;
1998 if (oldParentWindow == parentWindow) {
1999 // Avoid freeing and reallocating resources if the window stays the same.
2000 d->parentItem = parentItem;
2002 if (oldParentWindow)
2004 d->parentItem = parentItem;
2006 d->refWindow(parentWindow);
2009 d->dirty(QQuickItemPrivate::ParentChanged);
2012 QQuickItemPrivate::get(d->parentItem)->addChild(this);
2014 QQuickWindowPrivate::get(d->window)->parentlessItems.insert(this);
2016 d->setEffectiveVisibleRecur(d->calcEffectiveVisible());
2017 d->setEffectiveEnableRecur(0, d->calcEffectiveEnable());
2019 if (d->parentItem) {
2020 if (!scopeFocusedItem) {
2022 scopeFocusedItem = this;
2023 else if (!isFocusScope() && d->subFocusItem)
2024 scopeFocusedItem = d->subFocusItem;
2027 if (scopeFocusedItem) {
2028 // We need to test whether this item becomes scope focused
2029 QQuickItem *scopeItem = d->parentItem;
2030 while (!scopeItem->isFocusScope() && scopeItem->parentItem())
2031 scopeItem = scopeItem->parentItem();
2033 if (QQuickItemPrivate::get(scopeItem)->subFocusItem
2034 || (!scopeItem->isFocusScope() && scopeItem->hasFocus())) {
2035 if (scopeFocusedItem != this)
2036 QQuickItemPrivate::get(scopeFocusedItem)->updateSubFocusItem(this, false);
2037 QQuickItemPrivate::get(scopeFocusedItem)->focus = false;
2038 emit scopeFocusedItem->focusChanged(false);
2041 QQuickWindowPrivate::get(d->window)->setFocusInScope(scopeItem, scopeFocusedItem,
2042 QQuickWindowPrivate::DontChangeFocusProperty);
2044 QQuickItemPrivate::get(scopeFocusedItem)->updateSubFocusItem(scopeItem, true);
2050 d->resolveLayoutMirror();
2052 d->itemChange(ItemParentHasChanged, d->parentItem);
2054 d->parentNotifier.notify();
2055 if (d->isAccessible && d->parentItem) {
2056 d->parentItem->d_func()->setAccessibleFlagAndListener();
2059 emit parentChanged(d->parentItem);
2060 if (isVisible() && d->parentItem)
2061 emit d->parentItem->visibleChildrenChanged();
2065 Moves the specified \a sibling item to the index before this item
2066 within the visual stacking order.
2068 The given \a sibling must be a sibling of this item; that is, they must
2069 have the same immediate \l parent.
2071 \sa {Concepts - Visual Parent in Qt Quick}
2073 void QQuickItem::stackBefore(const QQuickItem *sibling)
2076 if (!sibling || sibling == this || !d->parentItem || d->parentItem != QQuickItemPrivate::get(sibling)->parentItem) {
2077 qWarning("QQuickItem::stackBefore: Cannot stack before %p, which must be a sibling", sibling);
2081 QQuickItemPrivate *parentPrivate = QQuickItemPrivate::get(d->parentItem);
2083 int myIndex = parentPrivate->childItems.lastIndexOf(this);
2084 int siblingIndex = parentPrivate->childItems.lastIndexOf(const_cast<QQuickItem *>(sibling));
2086 Q_ASSERT(myIndex != -1 && siblingIndex != -1);
2088 if (myIndex == siblingIndex - 1)
2091 parentPrivate->childItems.move(myIndex, myIndex < siblingIndex ? siblingIndex - 1 : siblingIndex);
2093 parentPrivate->dirty(QQuickItemPrivate::ChildrenStackingChanged);
2094 parentPrivate->markSortedChildrenDirty(this);
2096 for (int ii = qMin(siblingIndex, myIndex); ii < parentPrivate->childItems.count(); ++ii)
2097 QQuickItemPrivate::get(parentPrivate->childItems.at(ii))->siblingOrderChanged();
2101 Moves the specified \a sibling item to the index after this item
2102 within the visual stacking order.
2104 The given \a sibling must be a sibling of this item; that is, they must
2105 have the same immediate \l parent.
2107 \sa {Concepts - Visual Parent in Qt Quick}
2109 void QQuickItem::stackAfter(const QQuickItem *sibling)
2112 if (!sibling || sibling == this || !d->parentItem || d->parentItem != QQuickItemPrivate::get(sibling)->parentItem) {
2113 qWarning("QQuickItem::stackAfter: Cannot stack after %p, which must be a sibling", sibling);
2117 QQuickItemPrivate *parentPrivate = QQuickItemPrivate::get(d->parentItem);
2119 int myIndex = parentPrivate->childItems.lastIndexOf(this);
2120 int siblingIndex = parentPrivate->childItems.lastIndexOf(const_cast<QQuickItem *>(sibling));
2122 Q_ASSERT(myIndex != -1 && siblingIndex != -1);
2124 if (myIndex == siblingIndex + 1)
2127 parentPrivate->childItems.move(myIndex, myIndex > siblingIndex ? siblingIndex + 1 : siblingIndex);
2129 parentPrivate->dirty(QQuickItemPrivate::ChildrenStackingChanged);
2130 parentPrivate->markSortedChildrenDirty(this);
2132 for (int ii = qMin(myIndex, siblingIndex + 1); ii < parentPrivate->childItems.count(); ++ii)
2133 QQuickItemPrivate::get(parentPrivate->childItems.at(ii))->siblingOrderChanged();
2137 Returns the window in which this item is rendered.
2139 QQuickWindow *QQuickItem::window() const
2141 Q_D(const QQuickItem);
2145 static bool itemZOrder_sort(QQuickItem *lhs, QQuickItem *rhs)
2147 return lhs->z() < rhs->z();
2150 QList<QQuickItem *> QQuickItemPrivate::paintOrderChildItems() const
2152 if (sortedChildItems)
2153 return *sortedChildItems;
2155 // If none of the items have set Z then the paint order list is the same as
2156 // the childItems list. This is by far the most common case.
2158 for (int i = 0; i < childItems.count(); ++i) {
2159 if (QQuickItemPrivate::get(childItems.at(i))->z() != 0.) {
2165 sortedChildItems = new QList<QQuickItem*>(childItems);
2166 qStableSort(sortedChildItems->begin(), sortedChildItems->end(), itemZOrder_sort);
2167 return *sortedChildItems;
2170 sortedChildItems = const_cast<QList<QQuickItem*>*>(&childItems);
2175 void QQuickItemPrivate::addChild(QQuickItem *child)
2179 Q_ASSERT(!childItems.contains(child));
2181 childItems.append(child);
2183 QQuickItemPrivate *childPrivate = QQuickItemPrivate::get(child);
2184 if (childPrivate->extra.isAllocated())
2185 incrementCursorCount(childPrivate->extra.value().numItemsWithCursor);
2187 markSortedChildrenDirty(child);
2188 dirty(QQuickItemPrivate::ChildrenChanged);
2190 itemChange(QQuickItem::ItemChildAddedChange, child);
2192 emit q->childrenChanged();
2195 void QQuickItemPrivate::removeChild(QQuickItem *child)
2200 Q_ASSERT(childItems.contains(child));
2201 childItems.removeOne(child);
2202 Q_ASSERT(!childItems.contains(child));
2204 QQuickItemPrivate *childPrivate = QQuickItemPrivate::get(child);
2205 if (childPrivate->extra.isAllocated())
2206 incrementCursorCount(-childPrivate->extra.value().numItemsWithCursor);
2208 markSortedChildrenDirty(child);
2209 dirty(QQuickItemPrivate::ChildrenChanged);
2211 itemChange(QQuickItem::ItemChildRemovedChange, child);
2213 emit q->childrenChanged();
2216 void QQuickItemPrivate::refWindow(QQuickWindow *c)
2218 // An item needs a window if it is referenced by another item which has a window.
2219 // Typically the item is referenced by a parent, but can also be referenced by a
2220 // ShaderEffect or ShaderEffectSource. 'windowRefCount' counts how many items with
2221 // a window is referencing this item. When the reference count goes from zero to one,
2222 // or one to zero, the window of this item is updated and propagated to the children.
2223 // As long as the reference count stays above zero, the window is unchanged.
2224 // refWindow() increments the reference count.
2225 // derefWindow() decrements the reference count.
2228 Q_ASSERT((window != 0) == (windowRefCount > 0));
2230 if (++windowRefCount > 1) {
2232 qWarning("QQuickItem: Cannot use same item on different windows at the same time.");
2233 return; // Window already set.
2236 Q_ASSERT(window == 0);
2239 if (polishScheduled)
2240 QQuickWindowPrivate::get(window)->itemsToPolish.insert(q);
2243 QQuickWindowPrivate::get(window)->parentlessItems.insert(q);
2245 for (int ii = 0; ii < childItems.count(); ++ii) {
2246 QQuickItem *child = childItems.at(ii);
2247 QQuickItemPrivate::get(child)->refWindow(c);
2252 if (extra.isAllocated() && extra->screenAttached)
2253 extra->screenAttached->windowChanged(c);
2254 itemChange(QQuickItem::ItemSceneChange, c);
2257 void QQuickItemPrivate::derefWindow()
2260 Q_ASSERT((window != 0) == (windowRefCount > 0));
2263 return; // This can happen when destroying recursive shader effect sources.
2265 if (--windowRefCount > 0)
2266 return; // There are still other references, so don't set window to null yet.
2268 q->releaseResources();
2269 removeFromDirtyList();
2270 QQuickWindowPrivate *c = QQuickWindowPrivate::get(window);
2271 if (polishScheduled)
2272 c->itemsToPolish.remove(q);
2273 QMutableHashIterator<int, QQuickItem *> itemTouchMapIt(c->itemForTouchPointId);
2274 while (itemTouchMapIt.hasNext()) {
2275 if (itemTouchMapIt.next().value() == q)
2276 itemTouchMapIt.remove();
2278 if (c->mouseGrabberItem == q)
2279 c->mouseGrabberItem = 0;
2280 #ifndef QT_NO_CURSOR
2281 if (c->cursorItem == q)
2285 c->hoverItems.removeAll(q);
2286 if (itemNodeInstance)
2287 c->cleanup(itemNodeInstance);
2289 c->parentlessItems.remove(q);
2293 itemNodeInstance = 0;
2295 if (extra.isAllocated()) {
2296 extra->opacityNode = 0;
2297 extra->clipNode = 0;
2298 extra->rootNode = 0;
2299 extra->beforePaintNode = 0;
2305 for (int ii = 0; ii < childItems.count(); ++ii) {
2306 QQuickItem *child = childItems.at(ii);
2307 QQuickItemPrivate::get(child)->derefWindow();
2312 if (extra.isAllocated() && extra->screenAttached)
2313 extra->screenAttached->windowChanged(0);
2314 itemChange(QQuickItem::ItemSceneChange, (QQuickWindow *)0);
2319 Returns a transform that maps points from window space into item space.
2321 QTransform QQuickItemPrivate::windowToItemTransform() const
2323 // XXX todo - optimize
2324 return itemToWindowTransform().inverted();
2328 Returns a transform that maps points from item space into window space.
2330 QTransform QQuickItemPrivate::itemToWindowTransform() const
2333 QTransform rv = parentItem?QQuickItemPrivate::get(parentItem)->itemToWindowTransform():QTransform();
2334 itemToParentTransform(rv);
2339 Motifies \a t with this items local transform relative to its parent.
2341 void QQuickItemPrivate::itemToParentTransform(QTransform &t) const
2346 if (!transforms.isEmpty()) {
2348 for (int ii = transforms.count() - 1; ii >= 0; --ii)
2349 transforms.at(ii)->applyTo(&m);
2350 t = m.toTransform();
2353 if (scale() != 1. || rotation() != 0.) {
2354 QPointF tp = computeTransformOrigin();
2355 t.translate(tp.x(), tp.y());
2356 t.scale(scale(), scale());
2357 t.rotate(rotation());
2358 t.translate(-tp.x(), -tp.y());
2363 Returns true if construction of the QML component is complete; otherwise
2366 It is often desirable to delay some processing until the component is
2369 \sa componentComplete()
2371 bool QQuickItem::isComponentComplete() const
2373 Q_D(const QQuickItem);
2374 return d->componentComplete;
2377 QQuickItemPrivate::QQuickItemPrivate()
2382 , heightValid(false)
2383 , baselineOffsetValid(false)
2384 , componentComplete(true)
2387 , hoverEnabled(false)
2389 , antialiasing(false)
2391 , activeFocus(false)
2392 , notifiedFocus(false)
2393 , notifiedActiveFocus(false)
2394 , filtersChildMouseEvents(false)
2395 , explicitVisible(true)
2396 , effectiveVisible(true)
2397 , explicitEnable(true)
2398 , effectiveEnable(true)
2399 , polishScheduled(false)
2400 , inheritedLayoutMirror(false)
2401 , effectiveLayoutMirror(false)
2402 , isMirrorImplicit(true)
2403 , inheritMirrorFromParent(false)
2404 , inheritMirrorFromItem(false)
2405 , isAccessible(false)
2408 , dirtyAttributes(0)
2414 , sortedChildItems(&childItems)
2423 , itemNodeInstance(0)
2429 QQuickItemPrivate::~QQuickItemPrivate()
2431 if (sortedChildItems != &childItems)
2432 delete sortedChildItems;
2435 void QQuickItemPrivate::init(QQuickItem *parent)
2439 static bool atexit_registered = false;
2440 if (!atexit_registered) {
2441 atexit(qt_print_item_count);
2442 atexit_registered = true;
2448 registerAccessorProperties();
2450 baselineOffsetValid = false;
2453 q->setParentItem(parent);
2454 QQuickItemPrivate *parentPrivate = QQuickItemPrivate::get(parent);
2455 setImplicitLayoutMirror(parentPrivate->inheritedLayoutMirror, parentPrivate->inheritMirrorFromParent);
2459 void QQuickItemPrivate::data_append(QQmlListProperty<QObject> *prop, QObject *o)
2464 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2466 if (QQuickItem *item = qmlobject_cast<QQuickItem *>(o)) {
2467 item->setParentItem(that);
2469 if (o->inherits("QGraphicsItem"))
2470 qWarning("Cannot add a QtQuick 1.0 item (%s) into a QtQuick 2.0 scene!", o->metaObject()->className());
2472 // XXX todo - do we really want this behavior?
2478 \qmlproperty list<Object> QtQuick2::Item::data
2481 The data property allows you to freely mix visual children and resources
2482 in an item. If you assign a visual item to the data list it becomes
2483 a child and if you assign any other object type, it is added as a resource.
2507 It should not generally be necessary to refer to the \c data property,
2508 as it is the default property for Item and thus all child items are
2509 automatically assigned to this property.
2512 int QQuickItemPrivate::data_count(QQmlListProperty<QObject> *property)
2514 QQuickItem *item = static_cast<QQuickItem*>(property->object);
2515 QQuickItemPrivate *privateItem = QQuickItemPrivate::get(item);
2516 QQmlListProperty<QObject> resourcesProperty = privateItem->resources();
2517 QQmlListProperty<QQuickItem> childrenProperty = privateItem->children();
2519 return resources_count(&resourcesProperty) + children_count(&childrenProperty);
2522 QObject *QQuickItemPrivate::data_at(QQmlListProperty<QObject> *property, int i)
2524 QQuickItem *item = static_cast<QQuickItem*>(property->object);
2525 QQuickItemPrivate *privateItem = QQuickItemPrivate::get(item);
2526 QQmlListProperty<QObject> resourcesProperty = privateItem->resources();
2527 QQmlListProperty<QQuickItem> childrenProperty = privateItem->children();
2529 int resourcesCount = resources_count(&resourcesProperty);
2530 if (i < resourcesCount)
2531 return resources_at(&resourcesProperty, i);
2532 const int j = i - resourcesCount;
2533 if (j < children_count(&childrenProperty))
2534 return children_at(&childrenProperty, j);
2538 void QQuickItemPrivate::data_clear(QQmlListProperty<QObject> *property)
2540 QQuickItem *item = static_cast<QQuickItem*>(property->object);
2541 QQuickItemPrivate *privateItem = QQuickItemPrivate::get(item);
2542 QQmlListProperty<QObject> resourcesProperty = privateItem->resources();
2543 QQmlListProperty<QQuickItem> childrenProperty = privateItem->children();
2545 resources_clear(&resourcesProperty);
2546 children_clear(&childrenProperty);
2549 QObject *QQuickItemPrivate::resources_at(QQmlListProperty<QObject> *prop, int index)
2551 const QObjectList children = prop->object->children();
2552 if (index < children.count())
2553 return children.at(index);
2558 void QQuickItemPrivate::resources_append(QQmlListProperty<QObject> *prop, QObject *o)
2560 // XXX todo - do we really want this behavior?
2561 o->setParent(prop->object);
2564 int QQuickItemPrivate::resources_count(QQmlListProperty<QObject> *prop)
2566 return prop->object->children().count();
2569 void QQuickItemPrivate::resources_clear(QQmlListProperty<QObject> *prop)
2571 // XXX todo - do we really want this behavior?
2572 const QObjectList children = prop->object->children();
2573 for (int index = 0; index < children.count(); index++)
2574 children.at(index)->setParent(0);
2577 QQuickItem *QQuickItemPrivate::children_at(QQmlListProperty<QQuickItem> *prop, int index)
2579 QQuickItemPrivate *p = QQuickItemPrivate::get(static_cast<QQuickItem *>(prop->object));
2580 if (index >= p->childItems.count() || index < 0)
2583 return p->childItems.at(index);
2586 void QQuickItemPrivate::children_append(QQmlListProperty<QQuickItem> *prop, QQuickItem *o)
2591 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2592 if (o->parentItem() == that)
2593 o->setParentItem(0);
2595 o->setParentItem(that);
2598 int QQuickItemPrivate::children_count(QQmlListProperty<QQuickItem> *prop)
2600 QQuickItemPrivate *p = QQuickItemPrivate::get(static_cast<QQuickItem *>(prop->object));
2601 return p->childItems.count();
2604 void QQuickItemPrivate::children_clear(QQmlListProperty<QQuickItem> *prop)
2606 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2607 QQuickItemPrivate *p = QQuickItemPrivate::get(that);
2608 while (!p->childItems.isEmpty())
2609 p->childItems.at(0)->setParentItem(0);
2612 void QQuickItemPrivate::visibleChildren_append(QQmlListProperty<QQuickItem>*, QQuickItem *self)
2615 qmlInfo(self) << "QQuickItem: visibleChildren property is readonly and cannot be assigned to.";
2618 int QQuickItemPrivate::visibleChildren_count(QQmlListProperty<QQuickItem> *prop)
2620 QQuickItemPrivate *p = QQuickItemPrivate::get(static_cast<QQuickItem *>(prop->object));
2621 int visibleCount = 0;
2622 int c = p->childItems.count();
2624 if (p->childItems.at(c)->isVisible()) visibleCount++;
2627 return visibleCount;
2630 QQuickItem *QQuickItemPrivate::visibleChildren_at(QQmlListProperty<QQuickItem> *prop, int index)
2632 QQuickItemPrivate *p = QQuickItemPrivate::get(static_cast<QQuickItem *>(prop->object));
2633 const int childCount = p->childItems.count();
2634 if (index >= childCount || index < 0)
2637 int visibleCount = -1;
2638 for (int i = 0; i < childCount; i++) {
2639 if (p->childItems.at(i)->isVisible()) visibleCount++;
2640 if (visibleCount == index) return p->childItems.at(i);
2645 int QQuickItemPrivate::transform_count(QQmlListProperty<QQuickTransform> *prop)
2647 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2648 QQuickItemPrivate *p = QQuickItemPrivate::get(that);
2650 return p->transforms.count();
2653 void QQuickTransform::appendToItem(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.append(this);
2665 p->transforms.append(this);
2666 d->items.append(item);
2669 p->dirty(QQuickItemPrivate::Transform);
2672 void QQuickTransform::prependToItem(QQuickItem *item)
2674 Q_D(QQuickTransform);
2678 QQuickItemPrivate *p = QQuickItemPrivate::get(item);
2680 if (!d->items.isEmpty() && !p->transforms.isEmpty() && p->transforms.contains(this)) {
2681 p->transforms.removeOne(this);
2682 p->transforms.prepend(this);
2684 p->transforms.prepend(this);
2685 d->items.append(item);
2688 p->dirty(QQuickItemPrivate::Transform);
2691 void QQuickItemPrivate::transform_append(QQmlListProperty<QQuickTransform> *prop, QQuickTransform *transform)
2696 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2697 transform->appendToItem(that);
2700 QQuickTransform *QQuickItemPrivate::transform_at(QQmlListProperty<QQuickTransform> *prop, int idx)
2702 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2703 QQuickItemPrivate *p = QQuickItemPrivate::get(that);
2705 if (idx < 0 || idx >= p->transforms.count())
2708 return p->transforms.at(idx);
2711 void QQuickItemPrivate::transform_clear(QQmlListProperty<QQuickTransform> *prop)
2713 QQuickItem *that = static_cast<QQuickItem *>(prop->object);
2714 QQuickItemPrivate *p = QQuickItemPrivate::get(that);
2716 for (int ii = 0; ii < p->transforms.count(); ++ii) {
2717 QQuickTransform *t = p->transforms.at(ii);
2718 QQuickTransformPrivate *tp = QQuickTransformPrivate::get(t);
2719 tp->items.removeOne(that);
2722 p->transforms.clear();
2724 p->dirty(QQuickItemPrivate::Transform);
2728 \qmlproperty AnchorLine QtQuick2::Item::anchors.top
2729 \qmlproperty AnchorLine QtQuick2::Item::anchors.bottom
2730 \qmlproperty AnchorLine QtQuick2::Item::anchors.left
2731 \qmlproperty AnchorLine QtQuick2::Item::anchors.right
2732 \qmlproperty AnchorLine QtQuick2::Item::anchors.horizontalCenter
2733 \qmlproperty AnchorLine QtQuick2::Item::anchors.verticalCenter
2734 \qmlproperty AnchorLine QtQuick2::Item::anchors.baseline
2736 \qmlproperty Item QtQuick2::Item::anchors.fill
2737 \qmlproperty Item QtQuick2::Item::anchors.centerIn
2739 \qmlproperty real QtQuick2::Item::anchors.margins
2740 \qmlproperty real QtQuick2::Item::anchors.topMargin
2741 \qmlproperty real QtQuick2::Item::anchors.bottomMargin
2742 \qmlproperty real QtQuick2::Item::anchors.leftMargin
2743 \qmlproperty real QtQuick2::Item::anchors.rightMargin
2744 \qmlproperty real QtQuick2::Item::anchors.horizontalCenterOffset
2745 \qmlproperty real QtQuick2::Item::anchors.verticalCenterOffset
2746 \qmlproperty real QtQuick2::Item::anchors.baselineOffset
2748 \qmlproperty bool QtQuick2::Item::anchors.alignWhenCentered
2750 Anchors provide a way to position an item by specifying its
2751 relationship with other items.
2753 Margins apply to top, bottom, left, right, and fill anchors.
2754 The \c anchors.margins property can be used to set all of the various margins at once, to the same value.
2755 It will not override a specific margin that has been previously set; to clear an explicit margin
2756 set it's value to \c undefined.
2757 Note that margins are anchor-specific and are not applied if an item does not
2760 Offsets apply for horizontal center, vertical center, and baseline anchors.
2764 \li \image declarative-anchors_example.png
2765 \li Text anchored to Image, horizontally centered and vertically below, with a margin.
2774 anchors.horizontalCenter: pic.horizontalCenter
2775 anchors.top: pic.bottom
2776 anchors.topMargin: 5
2782 \li \image declarative-anchors_example2.png
2784 Left of Text anchored to right of Image, with a margin. The y
2785 property of both defaults to 0.
2795 anchors.left: pic.right
2796 anchors.leftMargin: 5
2803 \c anchors.fill provides a convenient way for one item to have the
2804 same geometry as another item, and is equivalent to connecting all
2805 four directional anchors.
2807 To clear an anchor value, set it to \c undefined.
2809 \c anchors.alignWhenCentered (default true) forces centered anchors to align to a
2810 whole pixel, i.e. if the item being centered has an odd width/height the item
2811 will be positioned on a whole pixel rather than being placed on a half-pixel.
2812 This ensures the item is painted crisply. There are cases where this is not
2813 desirable, for example when rotating the item jitters may be apparent as the
2816 \note You can only anchor an item to siblings or a parent.
2818 For more information see \l {anchor-layout}{Anchor Layouts}.
2820 QQuickAnchors *QQuickItemPrivate::anchors() const
2823 Q_Q(const QQuickItem);
2824 _anchors = new QQuickAnchors(const_cast<QQuickItem *>(q));
2825 if (!componentComplete)
2826 _anchors->classBegin();
2831 void QQuickItemPrivate::siblingOrderChanged()
2834 for (int ii = 0; ii < changeListeners.count(); ++ii) {
2835 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
2836 if (change.types & QQuickItemPrivate::SiblingOrder) {
2837 change.listener->itemSiblingOrderChanged(q);
2842 QQmlListProperty<QObject> QQuickItemPrivate::data()
2844 return QQmlListProperty<QObject>(q_func(), 0, QQuickItemPrivate::data_append,
2845 QQuickItemPrivate::data_count,
2846 QQuickItemPrivate::data_at,
2847 QQuickItemPrivate::data_clear);
2851 \qmlproperty real QtQuick2::Item::childrenRect.x
2852 \qmlproperty real QtQuick2::Item::childrenRect.y
2853 \qmlproperty real QtQuick2::Item::childrenRect.width
2854 \qmlproperty real QtQuick2::Item::childrenRect.height
2856 This property holds the collective position and size of the item's
2859 This property is useful if you need to access the collective geometry
2860 of an item's children in order to correctly size the item.
2863 \property QQuickItem::childrenRect
2865 This property holds the collective position and size of the item's
2868 This property is useful if you need to access the collective geometry
2869 of an item's children in order to correctly size the item.
2871 QRectF QQuickItem::childrenRect()
2874 if (!d->extra.isAllocated() || !d->extra->contents) {
2875 d->extra.value().contents = new QQuickContents(this);
2876 if (d->componentComplete)
2877 d->extra->contents->complete();
2879 return d->extra->contents->rectF();
2883 Returns the children of this item.
2885 QList<QQuickItem *> QQuickItem::childItems() const
2887 Q_D(const QQuickItem);
2888 return d->childItems;
2892 \qmlproperty bool QtQuick2::Item::clip
2893 This property holds whether clipping is enabled. The default clip value is \c false.
2895 If clipping is enabled, an item will clip its own painting, as well
2896 as the painting of its children, to its bounding rectangle.
2898 Non-rectangular clipping regions are not supported for performance reasons.
2901 \property QQuickItem::clip
2902 This property holds whether clipping is enabled. The default clip value is \c false.
2904 If clipping is enabled, an item will clip its own painting, as well
2905 as the painting of its children, to its bounding rectangle. If you set
2906 clipping during an item's paint operation, remember to re-set it to
2907 prevent clipping the rest of your scene.
2909 Non-rectangular clipping regions are not supported for performance reasons.
2911 bool QQuickItem::clip() const
2913 return flags() & ItemClipsChildrenToShape;
2916 void QQuickItem::setClip(bool c)
2921 setFlag(ItemClipsChildrenToShape, c);
2923 emit clipChanged(c);
2928 This function is called to handle this item's changes in
2929 geometry from \a oldGeometry to \a newGeometry. If the two
2930 geometries are the same, it doesn't do anything.
2932 Derived classes must call the base class method within their implementation.
2934 void QQuickItem::geometryChanged(const QRectF &newGeometry, const QRectF &oldGeometry)
2939 QQuickAnchorsPrivate::get(d->_anchors)->updateMe();
2941 bool xChange = (newGeometry.x() != oldGeometry.x());
2942 bool yChange = (newGeometry.y() != oldGeometry.y());
2943 bool widthChange = (newGeometry.width() != oldGeometry.width());
2944 bool heightChange = (newGeometry.height() != oldGeometry.height());
2946 for (int ii = 0; ii < d->changeListeners.count(); ++ii) {
2947 const QQuickItemPrivate::ChangeListener &change = d->changeListeners.at(ii);
2948 if (change.types & QQuickItemPrivate::Geometry) {
2949 if (change.gTypes == QQuickItemPrivate::GeometryChange) {
2950 change.listener->itemGeometryChanged(this, newGeometry, oldGeometry);
2951 } else if ((xChange && (change.gTypes & QQuickItemPrivate::XChange)) ||
2952 (yChange && (change.gTypes & QQuickItemPrivate::YChange)) ||
2953 (widthChange && (change.gTypes & QQuickItemPrivate::WidthChange)) ||
2954 (heightChange && (change.gTypes & QQuickItemPrivate::HeightChange))) {
2955 change.listener->itemGeometryChanged(this, newGeometry, oldGeometry);
2965 emit widthChanged();
2967 emit heightChanged();
2971 Called by the rendering thread, as a result of
2972 QQuickItem::update(), when it is time to sync the state of the QML
2973 objects with the scene graph objects.
2975 The function should return the root of the scene graph subtree for
2976 this item. Most implementations will return a single
2977 QSGGeometryNode containing the visual representation of this item.
2978 \a oldNode is the node that was returned the last time the
2979 function was called. \a updatePaintNodeData provides a pointer to
2980 the QSGTransformNode associated with this QQuickItem.
2983 QSGNode *MyItem::updatePaintNode(QSGNode *node, UpdatePaintNodeData *)
2985 QSGSimpleRectNode *n = static_cast<QSGSimpleRectNode *>(node);
2987 n = new QSGSimpleRectNode();
2988 n->setColor(Qt::red);
2990 n->setRect(boundingRect());
2995 The main thread is blocked while this function is executed so it is safe to read
2996 values from the QQuickItem instance and other objects in the main thread.
2998 If no call to QQuickItem::updatePaintNode() result in actual scene graph
2999 changes, like QSGNode::markDirty() or adding and removing nodes, then
3000 the underlying implementation may decide to not render the scene again as
3001 the visual outcome is identical.
3003 \warning It is crucial that OpenGL operations and interaction with
3004 the scene graph happens exclusively on the rendering thread,
3005 primarily during the QQuickItem::updatePaintNode() call. The best
3006 rule of thumb is to only use classes with the "QSG" prefix inside
3007 the QQuickItem::updatePaintNode() function.
3009 \sa QSGMaterial, QSGSimpleMaterial, QSGGeometryNode, QSGGeometry,
3010 QSGFlatColorMaterial, QSGTextureMaterial, QSGNode::markDirty()
3013 QSGNode *QQuickItem::updatePaintNode(QSGNode *oldNode, UpdatePaintNodeData *updatePaintNodeData)
3015 Q_UNUSED(updatePaintNodeData)
3021 This function is called when the item's scene graph resources are no longer needed.
3022 It allows items to free its resources, for instance textures, that are not owned by scene graph
3023 nodes. Note that scene graph nodes are managed by QQuickWindow and should not be deleted by
3024 this function. Scene graph resources are no longer needed when the parent is set to null and
3025 the item is not used by any \l ShaderEffect or \l ShaderEffectSource.
3027 This function is called from the main thread. Therefore, resources used by the scene graph
3028 should not be deleted directly, but by calling \l QObject::deleteLater().
3030 \note The item destructor still needs to free its scene graph resources if not already done.
3033 void QQuickItem::releaseResources()
3037 QSGTransformNode *QQuickItemPrivate::createTransformNode()
3039 return new QSGTransformNode;
3043 This function should perform any layout as required for this item.
3045 When polish() is called, the scene graph schedules a polish event for this
3046 item. When the scene graph is ready to render this item, it calls
3047 updatePolish() to do any item layout as required before it renders the
3050 void QQuickItem::updatePolish()
3054 void QQuickItemPrivate::addItemChangeListener(QQuickItemChangeListener *listener, ChangeTypes types)
3056 changeListeners.append(ChangeListener(listener, types));
3059 void QQuickItemPrivate::removeItemChangeListener(QQuickItemChangeListener *listener, ChangeTypes types)
3061 ChangeListener change(listener, types);
3062 changeListeners.removeOne(change);
3065 void QQuickItemPrivate::updateOrAddGeometryChangeListener(QQuickItemChangeListener *listener, GeometryChangeTypes types)
3067 ChangeListener change(listener, types);
3068 int index = changeListeners.find(change);
3070 changeListeners[index].gTypes = change.gTypes; //we may have different GeometryChangeTypes
3072 changeListeners.append(change);
3075 void QQuickItemPrivate::updateOrRemoveGeometryChangeListener(QQuickItemChangeListener *listener,
3076 GeometryChangeTypes types)
3078 ChangeListener change(listener, types);
3079 if (types == NoChange) {
3080 changeListeners.removeOne(change);
3082 int index = changeListeners.find(change);
3084 changeListeners[index].gTypes = change.gTypes; //we may have different GeometryChangeTypes
3089 This event handler can be reimplemented in a subclass to receive key
3090 press events for an item. The event information is provided by the
3093 void QQuickItem::keyPressEvent(QKeyEvent *event)
3099 This event handler can be reimplemented in a subclass to receive key
3100 release events for an item. The event information is provided by the
3103 void QQuickItem::keyReleaseEvent(QKeyEvent *event)
3109 This event handler can be reimplemented in a subclass to receive input
3110 method events for an item. The event information is provided by the
3113 void QQuickItem::inputMethodEvent(QInputMethodEvent *event)
3119 This event handler can be reimplemented in a subclass to receive focus-in
3120 events for an item. The event information is provided by the
3123 void QQuickItem::focusInEvent(QFocusEvent * /*event*/)
3125 #ifndef QT_NO_ACCESSIBILITY
3126 QAccessibleEvent ev(this, QAccessible::Focus);
3127 QAccessible::updateAccessibility(&ev);
3132 This event handler can be reimplemented in a subclass to receive focus-out
3133 events for an item. The event information is provided by the
3136 void QQuickItem::focusOutEvent(QFocusEvent * /*event*/)
3141 This event handler can be reimplemented in a subclass to receive mouse
3142 press events for an item. The event information is provided by the
3145 void QQuickItem::mousePressEvent(QMouseEvent *event)
3151 This event handler can be reimplemented in a subclass to receive mouse
3152 move events for an item. The event information is provided by the
3155 void QQuickItem::mouseMoveEvent(QMouseEvent *event)
3161 This event handler can be reimplemented in a subclass to receive mouse
3162 release events for an item. The event information is provided by the
3165 void QQuickItem::mouseReleaseEvent(QMouseEvent *event)
3171 This event handler can be reimplemented in a subclass to receive mouse
3172 double-click events for an item. The event information is provided by the
3175 void QQuickItem::mouseDoubleClickEvent(QMouseEvent *)
3180 This event handler can be reimplemented in a subclass to be notified
3181 when a mouse ungrab event has occurred on this item.
3185 void QQuickItem::mouseUngrabEvent()
3191 This event handler can be reimplemented in a subclass to be notified
3192 when a touch ungrab event has occurred on this item.
3194 void QQuickItem::touchUngrabEvent()
3200 This event handler can be reimplemented in a subclass to receive
3201 wheel events for an item. The event information is provided by the
3204 void QQuickItem::wheelEvent(QWheelEvent *event)
3210 This event handler can be reimplemented in a subclass to receive touch
3211 events for an item. The event information is provided by the
3214 void QQuickItem::touchEvent(QTouchEvent *event)
3220 This event handler can be reimplemented in a subclass to receive hover-enter
3221 events for an item. The event information is provided by the
3224 Hover events are only provided if acceptHoverEvents() is true.
3226 void QQuickItem::hoverEnterEvent(QHoverEvent *event)
3232 This event handler can be reimplemented in a subclass to receive hover-move
3233 events for an item. The event information is provided by the
3236 Hover events are only provided if acceptHoverEvents() is true.
3238 void QQuickItem::hoverMoveEvent(QHoverEvent *event)
3244 This event handler can be reimplemented in a subclass to receive hover-leave
3245 events for an item. The event information is provided by the
3248 Hover events are only provided if acceptHoverEvents() is true.
3250 void QQuickItem::hoverLeaveEvent(QHoverEvent *event)
3255 #ifndef QT_NO_DRAGANDDROP
3257 This event handler can be reimplemented in a subclass to receive drag-enter
3258 events for an item. The event information is provided by the
3261 Drag and drop events are only provided if the ItemAcceptsDrops flag
3262 has been set for this item.
3264 \sa Drag, {Drag and Drop}
3266 void QQuickItem::dragEnterEvent(QDragEnterEvent *event)
3272 This event handler can be reimplemented in a subclass to receive drag-move
3273 events for an item. The event information is provided by the
3276 Drag and drop events are only provided if the ItemAcceptsDrops flag
3277 has been set for this item.
3279 \sa Drag, {Drag and Drop}
3281 void QQuickItem::dragMoveEvent(QDragMoveEvent *event)
3287 This event handler can be reimplemented in a subclass to receive drag-leave
3288 events for an item. The event information is provided by the
3291 Drag and drop events are only provided if the ItemAcceptsDrops flag
3292 has been set for this item.
3294 \sa Drag, {Drag and Drop}
3296 void QQuickItem::dragLeaveEvent(QDragLeaveEvent *event)
3302 This event handler can be reimplemented in a subclass to receive drop
3303 events for an item. The event information is provided by the
3306 Drag and drop events are only provided if the ItemAcceptsDrops flag
3307 has been set for this item.
3309 \sa Drag, {Drag and Drop}
3311 void QQuickItem::dropEvent(QDropEvent *event)
3315 #endif // QT_NO_DRAGANDDROP
3318 Reimplement this method to filter the mouse events that are received by
3319 this item's children.
3321 This method will only be called if filtersChildMouseEvents() is true.
3323 Return true if the specified \a event should not be passed onto the
3324 specified child \a item, and false otherwise.
3326 \sa setFiltersChildMouseEvents()
3328 bool QQuickItem::childMouseEventFilter(QQuickItem *item, QEvent *event)
3338 void QQuickItem::windowDeactivateEvent()
3340 foreach (QQuickItem* item, childItems()) {
3341 item->windowDeactivateEvent();
3346 This method is only relevant for input items.
3348 If this item is an input item, this method should be reimplemented to
3349 return the relevant input method flags for the given \a query.
3351 \sa QWidget::inputMethodQuery()
3353 QVariant QQuickItem::inputMethodQuery(Qt::InputMethodQuery query) const
3355 Q_D(const QQuickItem);
3360 v = (bool)(flags() & ItemAcceptsInputMethod);
3363 case Qt::ImCursorRectangle:
3365 case Qt::ImCursorPosition:
3366 case Qt::ImSurroundingText:
3367 case Qt::ImCurrentSelection:
3368 case Qt::ImMaximumTextLength:
3369 case Qt::ImAnchorPosition:
3370 case Qt::ImPreferredLanguage:
3371 if (d->extra.isAllocated() && d->extra->keyHandler)
3372 v = d->extra->keyHandler->inputMethodQuery(query);
3380 QQuickAnchorLine QQuickItemPrivate::left() const
3382 Q_Q(const QQuickItem);
3383 return QQuickAnchorLine(const_cast<QQuickItem *>(q), QQuickAnchorLine::Left);
3386 QQuickAnchorLine QQuickItemPrivate::right() const
3388 Q_Q(const QQuickItem);
3389 return QQuickAnchorLine(const_cast<QQuickItem *>(q), QQuickAnchorLine::Right);
3392 QQuickAnchorLine QQuickItemPrivate::horizontalCenter() const
3394 Q_Q(const QQuickItem);
3395 return QQuickAnchorLine(const_cast<QQuickItem *>(q), QQuickAnchorLine::HCenter);
3398 QQuickAnchorLine QQuickItemPrivate::top() const
3400 Q_Q(const QQuickItem);
3401 return QQuickAnchorLine(const_cast<QQuickItem *>(q), QQuickAnchorLine::Top);
3404 QQuickAnchorLine QQuickItemPrivate::bottom() const
3406 Q_Q(const QQuickItem);
3407 return QQuickAnchorLine(const_cast<QQuickItem *>(q), QQuickAnchorLine::Bottom);
3410 QQuickAnchorLine QQuickItemPrivate::verticalCenter() const
3412 Q_Q(const QQuickItem);
3413 return QQuickAnchorLine(const_cast<QQuickItem *>(q), QQuickAnchorLine::VCenter);
3416 QQuickAnchorLine QQuickItemPrivate::baseline() const
3418 Q_Q(const QQuickItem);
3419 return QQuickAnchorLine(const_cast<QQuickItem *>(q), QQuickAnchorLine::Baseline);
3423 \qmlproperty int QtQuick2::Item::baselineOffset
3425 Specifies the position of the item's baseline in local coordinates.
3427 The baseline of a \l Text item is the imaginary line on which the text
3428 sits. Controls containing text usually set their baseline to the
3429 baseline of their text.
3431 For non-text items, a default baseline offset of 0 is used.
3434 \property QQuickItem::baselineOffset
3436 Specifies the position of the item's baseline in local coordinates.
3438 The baseline of a \l Text item is the imaginary line on which the text
3439 sits. Controls containing text usually set their baseline to the
3440 baseline of their text.
3442 For non-text items, a default baseline offset of 0 is used.
3444 qreal QQuickItem::baselineOffset() const
3446 Q_D(const QQuickItem);
3447 if (d->baselineOffsetValid) {
3448 return d->baselineOffset;
3454 void QQuickItem::setBaselineOffset(qreal offset)
3457 if (offset == d->baselineOffset)
3460 d->baselineOffset = offset;
3461 d->baselineOffsetValid = true;
3463 for (int ii = 0; ii < d->changeListeners.count(); ++ii) {
3464 const QQuickItemPrivate::ChangeListener &change = d->changeListeners.at(ii);
3465 if (change.types & QQuickItemPrivate::Geometry) {
3466 QQuickAnchorsPrivate *anchor = change.listener->anchorPrivate();
3468 anchor->updateVerticalAnchors();
3472 if (d->_anchors && (d->_anchors->usedAnchors() & QQuickAnchors::BaselineAnchor))
3473 QQuickAnchorsPrivate::get(d->_anchors)->updateVerticalAnchors();
3475 emit baselineOffsetChanged(offset);
3480 * Schedules a call to updatePaintNode() for this item.
3482 * The call to QQuickItem::updatePaintNode() will always happen if the
3483 * item is showing in a QQuickWindow.
3485 * Only items which specifies QQuickItem::ItemHasContents are allowed
3486 * to call QQuickItem::update().
3488 void QQuickItem::update()
3491 Q_ASSERT(flags() & ItemHasContents);
3492 d->dirty(QQuickItemPrivate::Content);
3496 Schedules a polish event for this item.
3498 When the scene graph processes the request, it will call updatePolish()
3501 void QQuickItem::polish()
3504 if (!d->polishScheduled) {
3505 d->polishScheduled = true;
3507 QQuickWindowPrivate *p = QQuickWindowPrivate::get(d->window);
3508 bool maybeupdate = p->itemsToPolish.isEmpty();
3509 p->itemsToPolish.insert(this);
3510 if (maybeupdate) d->window->maybeUpdate();
3516 \qmlmethod object QtQuick2::Item::mapFromItem(Item item, real x, real y)
3517 \qmlmethod object QtQuick2::Item::mapFromItem(Item item, real x, real y, real width, real height)
3519 Maps the point (\a x, \a y) or rect (\a x, \a y, \a width, \a height), which is in \a
3520 item's coordinate system, to this item's coordinate system, and returns an object with \c x and
3521 \c y (and optionally \c width and \c height) properties matching the mapped coordinate.
3523 If \a item is a \c null value, this maps the point or rect from the coordinate system of
3529 void QQuickItem::mapFromItem(QQmlV8Function *args) const
3531 if (args->Length() != 0) {
3532 v8::Local<v8::Value> item = (*args)[0];
3533 QV8Engine *engine = args->engine();
3535 QQuickItem *itemObj = 0;
3536 if (!item->IsNull())
3537 itemObj = qobject_cast<QQuickItem*>(engine->toQObject(item));
3539 if (!itemObj && !item->IsNull()) {
3540 qmlInfo(this) << "mapFromItem() given argument \"" << engine->toString(item->ToString())
3541 << "\" which is neither null nor an Item";
3545 v8::Local<v8::Object> rv = v8::Object::New();
3546 args->returnValue(rv);
3548 qreal x = (args->Length() > 1)?(*args)[1]->NumberValue():0;
3549 qreal y = (args->Length() > 2)?(*args)[2]->NumberValue():0;
3551 if (args->Length() > 3) {
3552 qreal w = (*args)[3]->NumberValue();
3553 qreal h = (args->Length() > 4)?(*args)[4]->NumberValue():0;
3555 QRectF r = mapRectFromItem(itemObj, QRectF(x, y, w, h));
3557 rv->Set(v8::String::New("x"), v8::Number::New(r.x()));
3558 rv->Set(v8::String::New("y"), v8::Number::New(r.y()));
3559 rv->Set(v8::String::New("width"), v8::Number::New(r.width()));
3560 rv->Set(v8::String::New("height"), v8::Number::New(r.height()));
3562 QPointF p = mapFromItem(itemObj, QPointF(x, y));
3564 rv->Set(v8::String::New("x"), v8::Number::New(p.x()));
3565 rv->Set(v8::String::New("y"), v8::Number::New(p.y()));
3573 QTransform QQuickItem::itemTransform(QQuickItem *other, bool *ok) const
3575 Q_D(const QQuickItem);
3577 // XXX todo - we need to be able to handle common parents better and detect
3581 QTransform t = d->itemToWindowTransform();
3582 if (other) t *= QQuickItemPrivate::get(other)->windowToItemTransform();
3588 \qmlmethod object QtQuick2::Item::mapToItem(Item item, real x, real y)
3589 \qmlmethod object QtQuick2::Item::mapToItem(Item item, real x, real y, real width, real height)
3591 Maps the point (\a x, \a y) or rect (\a x, \a y, \a width, \a height), which is in this
3592 item's coordinate system, to \a item's coordinate system, and returns an object with \c x and
3593 \c y (and optionally \c width and \c height) properties matching the mapped coordinate.
3595 If \a item is a \c null value, this maps the point or rect to the coordinate system of the
3601 void QQuickItem::mapToItem(QQmlV8Function *args) const
3603 if (args->Length() != 0) {
3604 v8::Local<v8::Value> item = (*args)[0];
3605 QV8Engine *engine = args->engine();
3607 QQuickItem *itemObj = 0;
3608 if (!item->IsNull())
3609 itemObj = qobject_cast<QQuickItem*>(engine->toQObject(item));
3611 if (!itemObj && !item->IsNull()) {
3612 qmlInfo(this) << "mapToItem() given argument \"" << engine->toString(item->ToString())
3613 << "\" which is neither null nor an Item";
3617 v8::Local<v8::Object> rv = v8::Object::New();
3618 args->returnValue(rv);
3620 qreal x = (args->Length() > 1)?(*args)[1]->NumberValue():0;
3621 qreal y = (args->Length() > 2)?(*args)[2]->NumberValue():0;
3623 if (args->Length() > 3) {
3624 qreal w = (*args)[3]->NumberValue();
3625 qreal h = (args->Length() > 4)?(*args)[4]->NumberValue():0;
3627 QRectF r = mapRectToItem(itemObj, QRectF(x, y, w, h));
3629 rv->Set(v8::String::New("x"), v8::Number::New(r.x()));
3630 rv->Set(v8::String::New("y"), v8::Number::New(r.y()));
3631 rv->Set(v8::String::New("width"), v8::Number::New(r.width()));
3632 rv->Set(v8::String::New("height"), v8::Number::New(r.height()));
3634 QPointF p = mapToItem(itemObj, QPointF(x, y));
3636 rv->Set(v8::String::New("x"), v8::Number::New(p.x()));
3637 rv->Set(v8::String::New("y"), v8::Number::New(p.y()));
3643 \qmlmethod QtQuick2::Item::forceActiveFocus()
3645 Forces active focus on the item.
3647 This method sets focus on the item and ensures that all ancestor
3648 FocusScope objects in the object hierarchy are also given \l focus.
3653 Forces active focus on the item.
3655 This method sets focus on the item and ensures that all ancestor
3656 FocusScope objects in the object hierarchy are also given \l focus.
3660 void QQuickItem::forceActiveFocus()
3663 QQuickItem *parent = parentItem();
3665 if (parent->flags() & QQuickItem::ItemIsFocusScope) {
3666 parent->setFocus(true);
3668 parent = parent->parentItem();
3673 \qmlmethod QtQuick2::Item::childAt(real x, real y)
3675 Returns the first visible child item found at point (\a x, \a y) within
3676 the coordinate system of this item.
3678 Returns \c null if there is no such item.
3681 Returns the first visible child item found at point (\a x, \a y) within
3682 the coordinate system of this item.
3684 Returns 0 if there is no such item.
3686 QQuickItem *QQuickItem::childAt(qreal x, qreal y) const
3688 // XXX todo - should this include transform etc.?
3689 const QList<QQuickItem *> children = childItems();
3690 for (int i = children.count()-1; i >= 0; --i) {
3691 QQuickItem *child = children.at(i);
3692 if (child->isVisible() && child->x() <= x
3693 && child->x() + child->width() >= x
3695 && child->y() + child->height() >= y)
3701 QQmlListProperty<QObject> QQuickItemPrivate::resources()
3703 return QQmlListProperty<QObject>(q_func(), 0, QQuickItemPrivate::resources_append,
3704 QQuickItemPrivate::resources_count,
3705 QQuickItemPrivate::resources_at,
3706 QQuickItemPrivate::resources_clear);
3710 \qmlproperty list<Item> QtQuick2::Item::children
3711 \qmlproperty list<Object> QtQuick2::Item::resources
3713 The children property contains the list of visual children of this item.
3714 The resources property contains non-visual resources that you want to
3717 It is not generally necessary to refer to these properties when adding
3718 child items or resources, as the default \l data property will
3719 automatically assign child objects to the \c children and \c resources
3720 properties as appropriate. See the \l data documentation for details.
3723 \property QQuickItem::children
3726 QQmlListProperty<QQuickItem> QQuickItemPrivate::children()
3728 return QQmlListProperty<QQuickItem>(q_func(), 0, QQuickItemPrivate::children_append,
3729 QQuickItemPrivate::children_count,
3730 QQuickItemPrivate::children_at,
3731 QQuickItemPrivate::children_clear);
3736 \qmlproperty real QtQuick2::Item::visibleChildren
3737 This read-only property lists all of the item's children that are currently visible.
3738 Note that a child's visibility may have changed explicitly, or because the visibility
3739 of this (it's parent) item or another grandparent changed.
3742 \property QQuickItem::visibleChildren
3745 QQmlListProperty<QQuickItem> QQuickItemPrivate::visibleChildren()
3747 return QQmlListProperty<QQuickItem>(q_func(), 0, QQuickItemPrivate::visibleChildren_append,
3748 QQuickItemPrivate::visibleChildren_count,
3749 QQuickItemPrivate::visibleChildren_at);
3754 \qmlproperty list<State> QtQuick2::Item::states
3756 This property holds the list of possible states for this item. To change
3757 the state of this item, set the \l state property to one of these states,
3758 or set the \l state property to an empty string to revert the item to its
3761 This property is specified as a list of \l State objects. For example,
3762 below is an item with "red_color" and "blue_color" states:
3769 width: 100; height: 100
3774 PropertyChanges { target: root; color: "red" }
3778 PropertyChanges { target: root; color: "blue" }
3784 See \l{Qt Quick States} and \l{Animation and Transitions in Qt Quick} for
3785 more details on using states and transitions.
3790 \property QQuickItem::states
3793 QQmlListProperty<QQuickState> QQuickItemPrivate::states()
3795 return _states()->statesProperty();
3799 \qmlproperty list<Transition> QtQuick2::Item::transitions
3801 This property holds the list of transitions for this item. These define the
3802 transitions to be applied to the item whenever it changes its \l state.
3804 This property is specified as a list of \l Transition objects. For example:
3821 See \l{Qt Quick States} and \l{Animation and Transitions in Qt Quick} for
3822 more details on using states and transitions.
3827 \property QQuickItem::transitions
3830 QQmlListProperty<QQuickTransition> QQuickItemPrivate::transitions()
3832 return _states()->transitionsProperty();
3835 QString QQuickItemPrivate::state() const
3840 return _stateGroup->state();
3843 void QQuickItemPrivate::setState(const QString &state)
3845 _states()->setState(state);
3849 \qmlproperty string QtQuick2::Item::state
3851 This property holds the name of the current state of the item.
3853 If the item is in its default state — that is, no explicit state has been
3854 set — then this property holds an empty string. Likewise, you can return
3855 an item to its default state by setting this property to an empty string.
3857 \sa {Qt Quick States}
3860 \property QQuickItem::state
3862 This property holds the name of the current state of the item.
3864 If the item is in its default state — that is, no explicit state has been
3865 set — then this property holds an empty string. Likewise, you can return
3866 an item to its default state by setting this property to an empty string.
3868 \sa {Qt Quick States}
3870 QString QQuickItem::state() const
3872 Q_D(const QQuickItem);
3876 void QQuickItem::setState(const QString &state)
3883 \qmlproperty list<Transform> QtQuick2::Item::transform
3884 This property holds the list of transformations to apply.
3886 For more information see \l Transform.
3889 \property QQuickItem::transform
3895 QQmlListProperty<QQuickTransform> QQuickItem::transform()
3897 return QQmlListProperty<QQuickTransform>(this, 0, QQuickItemPrivate::transform_append,
3898 QQuickItemPrivate::transform_count,
3899 QQuickItemPrivate::transform_at,
3900 QQuickItemPrivate::transform_clear);
3905 Derived classes should call the base class method before adding their own action to
3906 perform at classBegin.
3908 void QQuickItem::classBegin()
3911 d->componentComplete = false;
3913 d->_stateGroup->classBegin();
3915 d->_anchors->classBegin();
3916 if (d->extra.isAllocated() && d->extra->layer)
3917 d->extra->layer->classBegin();
3922 Derived classes should call the base class method before adding their own actions to
3923 perform at componentComplete.
3925 void QQuickItem::componentComplete()
3928 d->componentComplete = true;
3930 d->_stateGroup->componentComplete();
3932 d->_anchors->componentComplete();
3933 QQuickAnchorsPrivate::get(d->_anchors)->updateOnComplete();
3936 if (d->extra.isAllocated() && d->extra->layer)
3937 d->extra->layer->componentComplete();
3939 if (d->extra.isAllocated() && d->extra->keyHandler)
3940 d->extra->keyHandler->componentComplete();
3942 if (d->extra.isAllocated() && d->extra->contents)
3943 d->extra->contents->complete();
3945 if (d->window && d->dirtyAttributes) {
3946 d->addToDirtyList();
3947 QQuickWindowPrivate::get(d->window)->dirtyItem(this);
3951 QQuickStateGroup *QQuickItemPrivate::_states()
3955 _stateGroup = new QQuickStateGroup;
3956 if (!componentComplete)
3957 _stateGroup->classBegin();
3958 qmlobject_connect(_stateGroup, QQuickStateGroup, SIGNAL(stateChanged(QString)),
3959 q, QQuickItem, SIGNAL(stateChanged(QString)))
3965 QPointF QQuickItemPrivate::computeTransformOrigin() const
3969 case QQuickItem::TopLeft:
3970 return QPointF(0, 0);
3971 case QQuickItem::Top:
3972 return QPointF(width / 2., 0);
3973 case QQuickItem::TopRight:
3974 return QPointF(width, 0);
3975 case QQuickItem::Left:
3976 return QPointF(0, height / 2.);
3977 case QQuickItem::Center:
3978 return QPointF(width / 2., height / 2.);
3979 case QQuickItem::Right:
3980 return QPointF(width, height / 2.);
3981 case QQuickItem::BottomLeft:
3982 return QPointF(0, height);
3983 case QQuickItem::Bottom:
3984 return QPointF(width / 2., height);
3985 case QQuickItem::BottomRight:
3986 return QPointF(width, height);
3990 void QQuickItemPrivate::transformChanged()
3992 if (extra.isAllocated() && extra->layer)
3993 extra->layer->updateMatrix();
3996 void QQuickItemPrivate::deliverKeyEvent(QKeyEvent *e)
4000 Q_ASSERT(e->isAccepted());
4001 if (extra.isAllocated() && extra->keyHandler) {
4002 if (e->type() == QEvent::KeyPress)
4003 extra->keyHandler->keyPressed(e, false);
4005 extra->keyHandler->keyReleased(e, false);
4007 if (e->isAccepted())
4013 if (e->type() == QEvent::KeyPress)
4014 q->keyPressEvent(e);
4016 q->keyReleaseEvent(e);
4018 if (e->isAccepted())
4021 if (extra.isAllocated() && extra->keyHandler) {
4024 if (e->type() == QEvent::KeyPress)
4025 extra->keyHandler->keyPressed(e, true);
4027 extra->keyHandler->keyReleased(e, true);
4031 void QQuickItemPrivate::deliverInputMethodEvent(QInputMethodEvent *e)
4035 Q_ASSERT(e->isAccepted());
4036 if (extra.isAllocated() && extra->keyHandler) {
4037 extra->keyHandler->inputMethodEvent(e, false);
4039 if (e->isAccepted())
4045 q->inputMethodEvent(e);
4047 if (e->isAccepted())
4050 if (extra.isAllocated() && extra->keyHandler) {
4053 extra->keyHandler->inputMethodEvent(e, true);
4057 void QQuickItemPrivate::deliverFocusEvent(QFocusEvent *e)
4061 if (e->type() == QEvent::FocusIn) {
4064 q->focusOutEvent(e);
4068 void QQuickItemPrivate::deliverMouseEvent(QMouseEvent *e)
4072 Q_ASSERT(e->isAccepted());
4074 switch (e->type()) {
4076 Q_ASSERT(!"Unknown event type");
4077 case QEvent::MouseMove:
4078 q->mouseMoveEvent(e);
4080 case QEvent::MouseButtonPress:
4081 q->mousePressEvent(e);
4083 case QEvent::MouseButtonRelease:
4084 q->mouseReleaseEvent(e);
4086 case QEvent::MouseButtonDblClick:
4087 q->mouseDoubleClickEvent(e);
4092 void QQuickItemPrivate::deliverWheelEvent(QWheelEvent *e)
4098 void QQuickItemPrivate::deliverTouchEvent(QTouchEvent *e)
4104 void QQuickItemPrivate::deliverHoverEvent(QHoverEvent *e)
4107 switch (e->type()) {
4109 Q_ASSERT(!"Unknown event type");
4110 case QEvent::HoverEnter:
4111 q->hoverEnterEvent(e);
4113 case QEvent::HoverLeave:
4114 q->hoverLeaveEvent(e);
4116 case QEvent::HoverMove:
4117 q->hoverMoveEvent(e);
4122 #ifndef QT_NO_DRAGANDDROP
4123 void QQuickItemPrivate::deliverDragEvent(QEvent *e)
4126 switch (e->type()) {
4128 Q_ASSERT(!"Unknown event type");
4129 case QEvent::DragEnter:
4130 q->dragEnterEvent(static_cast<QDragEnterEvent *>(e));
4132 case QEvent::DragLeave:
4133 q->dragLeaveEvent(static_cast<QDragLeaveEvent *>(e));
4135 case QEvent::DragMove:
4136 q->dragMoveEvent(static_cast<QDragMoveEvent *>(e));
4139 q->dropEvent(static_cast<QDropEvent *>(e));
4143 #endif // QT_NO_DRAGANDDROP
4148 void QQuickItem::itemChange(ItemChange change, const ItemChangeData &value)
4155 Notify input method on updated query values if needed. \a queries indicates
4156 the changed attributes.
4158 void QQuickItem::updateInputMethod(Qt::InputMethodQueries queries)
4160 if (hasActiveFocus())
4161 qApp->inputMethod()->update(queries);
4165 // XXX todo - do we want/need this anymore?
4166 QRectF QQuickItem::boundingRect() const
4168 Q_D(const QQuickItem);
4169 return QRectF(0, 0, d->width, d->height);
4173 QRectF QQuickItem::clipRect() const
4175 Q_D(const QQuickItem);
4176 return QRectF(0, 0, d->width, d->height);
4180 \qmlproperty enumeration QtQuick2::Item::transformOrigin
4181 This property holds the origin point around which scale and rotation transform.
4183 Nine transform origins are available, as shown in the image below.
4184 The default transform origin is \c Item.Center.
4186 \image declarative-transformorigin.png
4188 This example rotates an image around its bottom-right corner.
4191 source: "myimage.png"
4192 transformOrigin: Item.BottomRight
4197 To set an arbitrary transform origin point use the \l Scale or \l Rotation
4198 transform types with \l transform.
4201 \property QQuickItem::transformOrigin
4202 This property holds the origin point around which scale and rotation transform.
4204 Nine transform origins are available, as shown in the image below.
4205 The default transform origin is \c Item.Center.
4207 \image declarative-transformorigin.png
4209 QQuickItem::TransformOrigin QQuickItem::transformOrigin() const
4211 Q_D(const QQuickItem);
4215 void QQuickItem::setTransformOrigin(TransformOrigin origin)
4218 if (origin == d->origin())
4221 d->extra.value().origin = origin;
4222 d->dirty(QQuickItemPrivate::TransformOrigin);
4224 emit transformOriginChanged(d->origin());
4228 \property QQuickItem::transformOriginPoint
4234 QPointF QQuickItem::transformOriginPoint() const
4236 Q_D(const QQuickItem);
4237 if (d->extra.isAllocated() && !d->extra->userTransformOriginPoint.isNull())
4238 return d->extra->userTransformOriginPoint;
4239 return d->computeTransformOrigin();
4245 void QQuickItem::setTransformOriginPoint(const QPointF &point)
4248 if (d->extra.value().userTransformOriginPoint == point)
4251 d->extra->userTransformOriginPoint = point;
4252 d->dirty(QQuickItemPrivate::TransformOrigin);
4256 \qmlproperty real QtQuick2::Item::z
4258 Sets the stacking order of sibling items. By default the stacking order is 0.
4260 Items with a higher stacking value are drawn on top of siblings with a
4261 lower stacking order. Items with the same stacking value are drawn
4262 bottom up in the order they appear. Items with a negative stacking
4263 value are drawn under their parent's content.
4265 The following example shows the various effects of stacking order.
4269 \li \image declarative-item_stacking1.png
4270 \li Same \c z - later children above earlier children:
4275 width: 100; height: 100
4279 x: 50; y: 50; width: 100; height: 100
4284 \li \image declarative-item_stacking2.png
4285 \li Higher \c z on top:
4291 width: 100; height: 100
4295 x: 50; y: 50; width: 100; height: 100
4300 \li \image declarative-item_stacking3.png
4301 \li Same \c z - children above parents:
4306 width: 100; height: 100
4309 x: 50; y: 50; width: 100; height: 100
4315 \li \image declarative-item_stacking4.png
4316 \li Lower \c z below:
4321 width: 100; height: 100
4325 x: 50; y: 50; width: 100; height: 100
4333 \property QQuickItem::z
4335 Sets the stacking order of sibling items. By default the stacking order is 0.
4337 Items with a higher stacking value are drawn on top of siblings with a
4338 lower stacking order. Items with the same stacking value are drawn
4339 bottom up in the order they appear. Items with a negative stacking
4340 value are drawn under their parent's content.
4342 The following example shows the various effects of stacking order.
4346 \li \image declarative-item_stacking1.png
4347 \li Same \c z - later children above earlier children:
4352 width: 100; height: 100
4356 x: 50; y: 50; width: 100; height: 100
4361 \li \image declarative-item_stacking2.png
4362 \li Higher \c z on top:
4368 width: 100; height: 100
4372 x: 50; y: 50; width: 100; height: 100
4377 \li \image declarative-item_stacking3.png
4378 \li Same \c z - children above parents:
4383 width: 100; height: 100
4386 x: 50; y: 50; width: 100; height: 100
4392 \li \image declarative-item_stacking4.png
4393 \li Lower \c z below:
4398 width: 100; height: 100
4402 x: 50; y: 50; width: 100; height: 100
4409 qreal QQuickItem::z() const
4411 Q_D(const QQuickItem);
4415 void QQuickItem::setZ(qreal v)
4421 d->extra.value().z = v;
4423 d->dirty(QQuickItemPrivate::ZValue);
4424 if (d->parentItem) {
4425 QQuickItemPrivate::get(d->parentItem)->dirty(QQuickItemPrivate::ChildrenStackingChanged);
4426 QQuickItemPrivate::get(d->parentItem)->markSortedChildrenDirty(this);
4431 if (d->extra.isAllocated() && d->extra->layer)
4432 d->extra->layer->updateZ();
4436 \qmlproperty real QtQuick2::Item::rotation
4437 This property holds the rotation of the item in degrees clockwise around
4438 its transformOrigin.
4440 The default value is 0 degrees (that is, no rotation).
4444 \li \image declarative-rotation.png
4449 width: 100; height: 100
4452 x: 25; y: 25; width: 50; height: 50
4459 \sa transform, Rotation
4462 \property QQuickItem::rotation
4463 This property holds the rotation of the item in degrees clockwise around
4464 its transformOrigin.
4466 The default value is 0 degrees (that is, no rotation).
4470 \li \image declarative-rotation.png
4475 width: 100; height: 100
4478 x: 25; y: 25; width: 50; height: 50
4485 \sa transform, Rotation
4487 qreal QQuickItem::rotation() const
4489 Q_D(const QQuickItem);
4490 return d->rotation();
4493 void QQuickItem::setRotation(qreal r)
4496 if (d->rotation() == r)
4499 d->extra.value().rotation = r;
4501 d->dirty(QQuickItemPrivate::BasicTransform);
4503 d->itemChange(ItemRotationHasChanged, r);
4505 emit rotationChanged();
4509 \qmlproperty real QtQuick2::Item::scale
4510 This property holds the scale factor for this item.
4512 A scale of less than 1.0 causes the item to be rendered at a smaller
4513 size, and a scale greater than 1.0 renders the item at a larger size.
4514 A negative scale causes the item to be mirrored when rendered.
4516 The default value is 1.0.
4518 Scaling is applied from the transformOrigin.
4522 \li \image declarative-scale.png
4529 width: 100; height: 100
4533 width: 25; height: 25
4538 x: 25; y: 25; width: 50; height: 50
4545 \sa transform, Scale
4548 \property QQuickItem::scale
4549 This property holds the scale factor for this item.
4551 A scale of less than 1.0 causes the item to be rendered at a smaller
4552 size, and a scale greater than 1.0 renders the item at a larger size.
4553 A negative scale causes the item to be mirrored when rendered.
4555 The default value is 1.0.
4557 Scaling is applied from the transformOrigin.
4561 \li \image declarative-scale.png
4568 width: 100; height: 100
4572 width: 25; height: 25
4577 x: 25; y: 25; width: 50; height: 50
4584 \sa transform, Scale
4586 qreal QQuickItem::scale() const
4588 Q_D(const QQuickItem);
4592 void QQuickItem::setScale(qreal s)
4595 if (d->scale() == s)
4598 d->extra.value().scale = s;
4600 d->dirty(QQuickItemPrivate::BasicTransform);
4602 emit scaleChanged();
4606 \qmlproperty real QtQuick2::Item::opacity
4608 This property holds the opacity of the item. Opacity is specified as a
4609 number between 0.0 (fully transparent) and 1.0 (fully opaque). The default
4612 When this property is set, the specified opacity is also applied
4613 individually to child items. This may have an unintended effect in some
4614 circumstances. For example in the second set of rectangles below, the red
4615 rectangle has specified an opacity of 0.5, which affects the opacity of
4616 its blue child rectangle even though the child has not specified an opacity.
4620 \li \image declarative-item_opacity1.png
4626 width: 100; height: 100
4629 x: 50; y: 50; width: 100; height: 100
4635 \li \image declarative-item_opacity2.png
4642 width: 100; height: 100
4645 x: 50; y: 50; width: 100; height: 100
4652 Changing an item's opacity does not affect whether the item receives user
4653 input events. (In contrast, setting \l visible property to \c false stops
4654 mouse events, and setting the \l enabled property to \c false stops mouse
4655 and keyboard events, and also removes active focus from the item.)
4660 \property QQuickItem::opacity
4662 This property holds the opacity of the item. Opacity is specified as a
4663 number between 0.0 (fully transparent) and 1.0 (fully opaque). The default
4666 When this property is set, the specified opacity is also applied
4667 individually to child items. This may have an unintended effect in some
4668 circumstances. For example in the second set of rectangles below, the red
4669 rectangle has specified an opacity of 0.5, which affects the opacity of
4670 its blue child rectangle even though the child has not specified an opacity.
4674 \li \image declarative-item_opacity1.png
4680 width: 100; height: 100
4683 x: 50; y: 50; width: 100; height: 100
4689 \li \image declarative-item_opacity2.png
4696 width: 100; height: 100
4699 x: 50; y: 50; width: 100; height: 100
4706 Changing an item's opacity does not affect whether the item receives user
4707 input events. (In contrast, setting \l visible property to \c false stops
4708 mouse events, and setting the \l enabled property to \c false stops mouse
4709 and keyboard events, and also removes active focus from the item.)
4713 qreal QQuickItem::opacity() const
4715 Q_D(const QQuickItem);
4716 return d->opacity();
4719 void QQuickItem::setOpacity(qreal o)
4722 if (d->opacity() == o)
4725 d->extra.value().opacity = o;
4727 d->dirty(QQuickItemPrivate::OpacityValue);
4729 d->itemChange(ItemOpacityHasChanged, o);
4731 emit opacityChanged();
4735 \qmlproperty bool QtQuick2::Item::visible
4737 This property holds whether the item is visible. By default this is true.
4739 Setting this property directly affects the \c visible value of child
4740 items. When set to \c false, the \c visible values of all child items also
4741 become \c false. When set to \c true, the \c visible values of child items
4742 are returned to \c true, unless they have explicitly been set to \c false.
4744 (Because of this flow-on behavior, using the \c visible property may not
4745 have the intended effect if a property binding should only respond to
4746 explicit property changes. In such cases it may be better to use the
4747 \l opacity property instead.)
4749 If this property is set to \c false, the item will no longer receive mouse
4750 events, but will continue to receive key events and will retain the keyboard
4751 \l focus if it has been set. (In contrast, setting the \l enabled property
4752 to \c false stops both mouse and keyboard events, and also removes focus
4755 \note This property's value is only affected by changes to this property or
4756 the parent's \c visible property. It does not change, for example, if this
4757 item moves off-screen, or if the \l opacity changes to 0.
4759 \sa opacity, enabled
4762 \property QQuickItem::visible
4764 This property holds whether the item is visible. By default this is true.
4766 Setting this property directly affects the \c visible value of child
4767 items. When set to \c false, the \c visible values of all child items also
4768 become \c false. When set to \c true, the \c visible values of child items
4769 are returned to \c true, unless they have explicitly been set to \c false.
4771 (Because of this flow-on behavior, using the \c visible property may not
4772 have the intended effect if a property binding should only respond to
4773 explicit property changes. In such cases it may be better to use the
4774 \l opacity property instead.)
4776 If this property is set to \c false, the item will no longer receive mouse
4777 events, but will continue to receive key events and will retain the keyboard
4778 \l focus if it has been set. (In contrast, setting the \l enabled property
4779 to \c false stops both mouse and keyboard events, and also removes focus
4782 \note This property's value is only affected by changes to this property or
4783 the parent's \c visible property. It does not change, for example, if this
4784 item moves off-screen, or if the \l opacity changes to 0.
4786 \sa opacity, enabled
4788 bool QQuickItem::isVisible() const
4790 Q_D(const QQuickItem);
4791 return d->effectiveVisible;
4794 void QQuickItem::setVisible(bool v)
4797 if (v == d->explicitVisible)
4800 d->explicitVisible = v;
4802 d->dirty(QQuickItemPrivate::Visible);
4804 const bool childVisibilityChanged = d->setEffectiveVisibleRecur(d->calcEffectiveVisible());
4805 if (childVisibilityChanged && d->parentItem)
4806 emit d->parentItem->visibleChildrenChanged(); // signal the parent, not this!
4810 \qmlproperty bool QtQuick2::Item::enabled
4812 This property holds whether the item receives mouse and keyboard events.
4813 By default this is true.
4815 Setting this property directly affects the \c enabled value of child
4816 items. When set to \c false, the \c enabled values of all child items also
4817 become \c false. When set to \c true, the \c enabled values of child items
4818 are returned to \c true, unless they have explicitly been set to \c false.
4820 Setting this property to \c false automatically causes \l activeFocus to be
4821 set to \c false, and this item will longer receive keyboard events.
4826 \property QQuickItem::enabled
4828 This property holds whether the item receives mouse and keyboard events.
4829 By default this is true.
4831 Setting this property directly affects the \c enabled value of child
4832 items. When set to \c false, the \c enabled values of all child items also
4833 become \c false. When set to \c true, the \c enabled values of child items
4834 are returned to \c true, unless they have explicitly been set to \c false.
4836 Setting this property to \c false automatically causes \l activeFocus to be
4837 set to \c false, and this item will longer receive keyboard events.
4841 bool QQuickItem::isEnabled() const
4843 Q_D(const QQuickItem);
4844 return d->effectiveEnable;
4847 void QQuickItem::setEnabled(bool e)
4850 if (e == d->explicitEnable)
4853 d->explicitEnable = e;
4855 QQuickItem *scope = parentItem();
4856 while (scope && !scope->isFocusScope())
4857 scope = scope->parentItem();
4859 d->setEffectiveEnableRecur(scope, d->calcEffectiveEnable());
4862 bool QQuickItemPrivate::calcEffectiveVisible() const
4864 // XXX todo - Should the effective visible of an element with no parent just be the current
4865 // effective visible? This would prevent pointless re-processing in the case of an element
4866 // moving to/from a no-parent situation, but it is different from what graphics view does.
4867 return explicitVisible && (!parentItem || QQuickItemPrivate::get(parentItem)->effectiveVisible);
4870 bool QQuickItemPrivate::setEffectiveVisibleRecur(bool newEffectiveVisible)
4874 if (newEffectiveVisible && !explicitVisible) {
4875 // This item locally overrides visibility
4876 return false; // effective visibility didn't change
4879 if (newEffectiveVisible == effectiveVisible) {
4880 // No change necessary
4881 return false; // effective visibility didn't change
4884 effectiveVisible = newEffectiveVisible;
4886 if (parentItem) QQuickItemPrivate::get(parentItem)->dirty(ChildrenStackingChanged);
4889 QQuickWindowPrivate *windowPriv = QQuickWindowPrivate::get(window);
4890 if (windowPriv->mouseGrabberItem == q)
4894 bool childVisibilityChanged = false;
4895 for (int ii = 0; ii < childItems.count(); ++ii)
4896 childVisibilityChanged |= QQuickItemPrivate::get(childItems.at(ii))->setEffectiveVisibleRecur(newEffectiveVisible);
4898 itemChange(QQuickItem::ItemVisibleHasChanged, effectiveVisible);
4899 #ifndef QT_NO_ACCESSIBILITY
4901 QAccessibleEvent ev(q, effectiveVisible ? QAccessible::ObjectShow : QAccessible::ObjectHide);
4902 QAccessible::updateAccessibility(&ev);
4905 emit q->visibleChanged();
4906 if (childVisibilityChanged)
4907 emit q->visibleChildrenChanged();
4909 return true; // effective visibility DID change
4912 bool QQuickItemPrivate::calcEffectiveEnable() const
4914 // XXX todo - Should the effective enable of an element with no parent just be the current
4915 // effective enable? This would prevent pointless re-processing in the case of an element
4916 // moving to/from a no-parent situation, but it is different from what graphics view does.
4917 return explicitEnable && (!parentItem || QQuickItemPrivate::get(parentItem)->effectiveEnable);
4920 void QQuickItemPrivate::setEffectiveEnableRecur(QQuickItem *scope, bool newEffectiveEnable)
4924 if (newEffectiveEnable && !explicitEnable) {
4925 // This item locally overrides enable
4929 if (newEffectiveEnable == effectiveEnable) {
4930 // No change necessary
4934 effectiveEnable = newEffectiveEnable;
4937 QQuickWindowPrivate *windowPriv = QQuickWindowPrivate::get(window);
4938 if (windowPriv->mouseGrabberItem == q)
4940 if (scope && !effectiveEnable && activeFocus) {
4941 windowPriv->clearFocusInScope(
4942 scope, q, QQuickWindowPrivate::DontChangeFocusProperty | QQuickWindowPrivate::DontChangeSubFocusItem);
4946 for (int ii = 0; ii < childItems.count(); ++ii) {
4947 QQuickItemPrivate::get(childItems.at(ii))->setEffectiveEnableRecur(
4948 (flags & QQuickItem::ItemIsFocusScope) && scope ? q : scope, newEffectiveEnable);
4951 if (window && scope && effectiveEnable && focus) {
4952 QQuickWindowPrivate::get(window)->setFocusInScope(
4953 scope, q, QQuickWindowPrivate::DontChangeFocusProperty | QQuickWindowPrivate::DontChangeSubFocusItem);
4956 emit q->enabledChanged();
4959 QString QQuickItemPrivate::dirtyToString() const
4961 #define DIRTY_TO_STRING(value) if (dirtyAttributes & value) { \
4962 if (!rv.isEmpty()) \
4963 rv.append(QLatin1String("|")); \
4964 rv.append(QLatin1String(#value)); \
4967 // QString rv = QLatin1String("0x") + QString::number(dirtyAttributes, 16);
4970 DIRTY_TO_STRING(TransformOrigin);
4971 DIRTY_TO_STRING(Transform);
4972 DIRTY_TO_STRING(BasicTransform);
4973 DIRTY_TO_STRING(Position);
4974 DIRTY_TO_STRING(Size);
4975 DIRTY_TO_STRING(ZValue);
4976 DIRTY_TO_STRING(Content);
4977 DIRTY_TO_STRING(Smooth);
4978 DIRTY_TO_STRING(OpacityValue);
4979 DIRTY_TO_STRING(ChildrenChanged);
4980 DIRTY_TO_STRING(ChildrenStackingChanged);
4981 DIRTY_TO_STRING(ParentChanged);
4982 DIRTY_TO_STRING(Clip);
4983 DIRTY_TO_STRING(Window);
4984 DIRTY_TO_STRING(EffectReference);
4985 DIRTY_TO_STRING(Visible);
4986 DIRTY_TO_STRING(HideReference);
4987 DIRTY_TO_STRING(Antialiasing);
4992 void QQuickItemPrivate::dirty(DirtyType type)
4995 if (type & (TransformOrigin | Transform | BasicTransform | Position | Size))
4998 if (!(dirtyAttributes & type) || (window && !prevDirtyItem)) {
4999 dirtyAttributes |= type;
5000 if (window && componentComplete) {
5002 QQuickWindowPrivate::get(window)->dirtyItem(q);
5007 void QQuickItemPrivate::addToDirtyList()
5012 if (!prevDirtyItem) {
5013 Q_ASSERT(!nextDirtyItem);
5015 QQuickWindowPrivate *p = QQuickWindowPrivate::get(window);
5016 nextDirtyItem = p->dirtyItemList;
5017 if (nextDirtyItem) QQuickItemPrivate::get(nextDirtyItem)->prevDirtyItem = &nextDirtyItem;
5018 prevDirtyItem = &p->dirtyItemList;
5019 p->dirtyItemList = q;
5022 Q_ASSERT(prevDirtyItem);
5025 void QQuickItemPrivate::removeFromDirtyList()
5027 if (prevDirtyItem) {
5028 if (nextDirtyItem) QQuickItemPrivate::get(nextDirtyItem)->prevDirtyItem = prevDirtyItem;
5029 *prevDirtyItem = nextDirtyItem;
5033 Q_ASSERT(!prevDirtyItem);
5034 Q_ASSERT(!nextDirtyItem);
5037 void QQuickItemPrivate::refFromEffectItem(bool hide)
5039 ++extra.value().effectRefCount;
5040 if (1 == extra->effectRefCount) {
5041 dirty(EffectReference);
5042 if (parentItem) QQuickItemPrivate::get(parentItem)->dirty(ChildrenStackingChanged);
5045 if (++extra->hideRefCount == 1)
5046 dirty(HideReference);
5050 void QQuickItemPrivate::derefFromEffectItem(bool unhide)
5052 Q_ASSERT(extra->effectRefCount);
5053 --extra->effectRefCount;
5054 if (0 == extra->effectRefCount) {
5055 dirty(EffectReference);
5056 if (parentItem) QQuickItemPrivate::get(parentItem)->dirty(ChildrenStackingChanged);
5059 if (--extra->hideRefCount == 0)
5060 dirty(HideReference);
5064 void QQuickItemPrivate::setCulled(bool cull)
5070 if ((cull && ++extra.value().hideRefCount == 1) || (!cull && --extra.value().hideRefCount == 0))
5071 dirty(HideReference);
5074 void QQuickItemPrivate::itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &data)
5078 case QQuickItem::ItemChildAddedChange:
5079 q->itemChange(change, data);
5080 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5081 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5082 if (change.types & QQuickItemPrivate::Children) {
5083 change.listener->itemChildAdded(q, data.item);
5087 case QQuickItem::ItemChildRemovedChange:
5088 q->itemChange(change, data);
5089 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5090 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5091 if (change.types & QQuickItemPrivate::Children) {
5092 change.listener->itemChildRemoved(q, data.item);
5096 case QQuickItem::ItemSceneChange:
5097 q->itemChange(change, data);
5099 case QQuickItem::ItemVisibleHasChanged:
5100 q->itemChange(change, data);
5101 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5102 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5103 if (change.types & QQuickItemPrivate::Visibility) {
5104 change.listener->itemVisibilityChanged(q);
5108 case QQuickItem::ItemParentHasChanged:
5109 q->itemChange(change, data);
5110 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5111 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5112 if (change.types & QQuickItemPrivate::Parent) {
5113 change.listener->itemParentChanged(q, data.item);
5117 case QQuickItem::ItemOpacityHasChanged:
5118 q->itemChange(change, data);
5119 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5120 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5121 if (change.types & QQuickItemPrivate::Opacity) {
5122 change.listener->itemOpacityChanged(q);
5126 case QQuickItem::ItemActiveFocusHasChanged:
5127 q->itemChange(change, data);
5129 case QQuickItem::ItemRotationHasChanged:
5130 q->itemChange(change, data);
5131 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5132 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5133 if (change.types & QQuickItemPrivate::Rotation) {
5134 change.listener->itemRotationChanged(q);
5142 \qmlproperty bool QtQuick2::Item::smooth
5144 Primarily used in image based items to decide if the item should use smooth
5145 sampling or not. Smooth sampling is performed using linear interpolation, while
5146 non-smooth is performed using nearest neighbor.
5148 In Qt Quick 2.0, this property has minimal impact on performance.
5153 \property QQuickItem::smooth
5154 \brief Specifies whether the item is smoothed or not
5156 Primarily used in image based items to decide if the item should use smooth
5157 sampling or not. Smooth sampling is performed using linear interpolation, while
5158 non-smooth is performed using nearest neighbor.
5160 In Qt Quick 2.0, this property has minimal impact on performance.
5164 bool QQuickItem::smooth() const
5166 Q_D(const QQuickItem);
5169 void QQuickItem::setSmooth(bool smooth)
5172 if (d->smooth == smooth)
5176 d->dirty(QQuickItemPrivate::Smooth);
5178 emit smoothChanged(smooth);
5182 \qmlproperty bool QtQuick2::Item::antialiasing
5184 Primarily used in Rectangle and image based elements to decide if the item should
5185 use antialiasing or not. Items with antialiasing enabled require more memory and
5186 are potentially slower to render.
5188 The default is false.
5191 \property QQuickItem::antialiasing
5192 \brief Specifies whether the item is antialiased or not
5194 Primarily used in Rectangle and image based elements to decide if the item should
5195 use antialiasing or not. Items with antialiasing enabled require more memory and
5196 are potentially slower to render.
5198 The default is false.
5200 bool QQuickItem::antialiasing() const
5202 Q_D(const QQuickItem);
5203 return d->antialiasing;
5205 void QQuickItem::setAntialiasing(bool antialiasing)
5208 if (d->antialiasing == antialiasing)
5211 d->antialiasing = antialiasing;
5212 d->dirty(QQuickItemPrivate::Antialiasing);
5214 emit antialiasingChanged(antialiasing);
5218 Returns the item flags for this item.
5222 QQuickItem::Flags QQuickItem::flags() const
5224 Q_D(const QQuickItem);
5225 return (QQuickItem::Flags)d->flags;
5229 Enables the specified \a flag for this item if \a enabled is true;
5230 if \a enabled is false, the flag is disabled.
5232 These provide various hints for the item; for example, the
5233 ItemClipsChildrenToShape flag indicates that all children of this
5234 item should be clipped to fit within the item area.
5236 void QQuickItem::setFlag(Flag flag, bool enabled)
5240 setFlags((Flags)(d->flags | (quint32)flag));
5242 setFlags((Flags)(d->flags & ~(quint32)flag));
5246 Enables the specified \a flags for this item.
5250 void QQuickItem::setFlags(Flags flags)
5254 if ((flags & ItemIsFocusScope) != (d->flags & ItemIsFocusScope)) {
5255 if (flags & ItemIsFocusScope && !d->childItems.isEmpty() && d->window) {
5256 qWarning("QQuickItem: Cannot set FocusScope once item has children and is in a window.");
5257 flags &= ~ItemIsFocusScope;
5258 } else if (d->flags & ItemIsFocusScope) {
5259 qWarning("QQuickItem: Cannot unset FocusScope flag.");
5260 flags |= ItemIsFocusScope;
5264 if ((flags & ItemClipsChildrenToShape ) != (d->flags & ItemClipsChildrenToShape))
5265 d->dirty(QQuickItemPrivate::Clip);
5271 \qmlproperty real QtQuick2::Item::x
5272 \qmlproperty real QtQuick2::Item::y
5273 \qmlproperty real QtQuick2::Item::width
5274 \qmlproperty real QtQuick2::Item::height
5276 Defines the item's position and size.
5278 The (x,y) position is relative to the \l parent.
5281 Item { x: 100; y: 100; width: 100; height: 100 }
5285 \property QQuickItem::x
5287 Defines the item's x position relative to its parent.
5290 \property QQuickItem::y
5292 Defines the item's y position relative to its parent.
5294 qreal QQuickItem::x() const
5296 Q_D(const QQuickItem);
5300 qreal QQuickItem::y() const
5302 Q_D(const QQuickItem);
5307 \property QQuickItem::pos
5313 QPointF QQuickItem::pos() const
5315 Q_D(const QQuickItem);
5316 return QPointF(d->x, d->y);
5319 void QQuickItem::setX(qreal v)
5328 d->dirty(QQuickItemPrivate::Position);
5330 geometryChanged(QRectF(x(), y(), width(), height()),
5331 QRectF(oldx, y(), width(), height()));
5334 void QQuickItem::setY(qreal v)
5343 d->dirty(QQuickItemPrivate::Position);
5345 geometryChanged(QRectF(x(), y(), width(), height()),
5346 QRectF(x(), oldy, width(), height()));
5352 void QQuickItem::setPos(const QPointF &pos)
5355 if (QPointF(d->x, d->y) == pos)
5364 d->dirty(QQuickItemPrivate::Position);
5366 geometryChanged(QRectF(x(), y(), width(), height()),
5367 QRectF(oldx, oldy, width(), height()));
5371 \property QQuickItem::width
5373 This property holds the width of this item.
5375 qreal QQuickItem::width() const
5377 Q_D(const QQuickItem);
5381 void QQuickItem::setWidth(qreal w)
5387 d->widthValid = true;
5391 qreal oldWidth = d->width;
5394 d->dirty(QQuickItemPrivate::Size);
5396 geometryChanged(QRectF(x(), y(), width(), height()),
5397 QRectF(x(), y(), oldWidth, height()));
5400 void QQuickItem::resetWidth()
5403 d->widthValid = false;
5404 setImplicitWidth(implicitWidth());
5407 void QQuickItemPrivate::implicitWidthChanged()
5410 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5411 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5412 if (change.types & QQuickItemPrivate::ImplicitWidth) {
5413 change.listener->itemImplicitWidthChanged(q);
5416 emit q->implicitWidthChanged();
5419 qreal QQuickItemPrivate::getImplicitWidth() const
5421 return implicitWidth;
5424 Returns the width of the item that is implied by other properties that determine the content.
5426 qreal QQuickItem::implicitWidth() const
5428 Q_D(const QQuickItem);
5429 return d->getImplicitWidth();
5433 \qmlproperty real QtQuick2::Item::implicitWidth
5434 \qmlproperty real QtQuick2::Item::implicitHeight
5436 Defines the natural width or height of the Item if no \l width or \l height is specified.
5438 The default implicit size for most items is 0x0, however some items have an inherent
5439 implicit size which cannot be overridden, e.g. Image, Text.
5441 Setting the implicit size is useful for defining components that have a preferred size
5442 based on their content, for example:
5449 property alias icon: image.source
5450 property alias label: text.text
5451 implicitWidth: text.implicitWidth + image.implicitWidth
5452 implicitHeight: Math.max(text.implicitHeight, image.implicitHeight)
5457 anchors.left: image.right; anchors.right: parent.right
5458 anchors.verticalCenter: parent.verticalCenter
5463 \b Note: using implicitWidth of Text or TextEdit and setting the width explicitly
5464 incurs a performance penalty as the text must be laid out twice.
5467 \property QQuickItem::implicitWidth
5468 \property QQuickItem::implicitHeight
5470 Defines the natural width or height of the Item if no \l width or \l height is specified.
5472 The default implicit size for most items is 0x0, however some items have an inherent
5473 implicit size which cannot be overridden, e.g. Image, Text.
5475 Setting the implicit size is useful for defining components that have a preferred size
5476 based on their content, for example:
5483 property alias icon: image.source
5484 property alias label: text.text
5485 implicitWidth: text.implicitWidth + image.implicitWidth
5486 implicitHeight: Math.max(text.implicitHeight, image.implicitHeight)
5491 anchors.left: image.right; anchors.right: parent.right
5492 anchors.verticalCenter: parent.verticalCenter
5497 \b Note: using implicitWidth of Text or TextEdit and setting the width explicitly
5498 incurs a performance penalty as the text must be laid out twice.
5500 void QQuickItem::setImplicitWidth(qreal w)
5503 bool changed = w != d->implicitWidth;
5504 d->implicitWidth = w;
5505 if (d->width == w || widthValid()) {
5507 d->implicitWidthChanged();
5508 if (d->width == w || widthValid())
5513 qreal oldWidth = d->width;
5516 d->dirty(QQuickItemPrivate::Size);
5518 geometryChanged(QRectF(x(), y(), width(), height()),
5519 QRectF(x(), y(), oldWidth, height()));
5522 d->implicitWidthChanged();
5526 Returns whether the width property has been set explicitly.
5528 bool QQuickItem::widthValid() const
5530 Q_D(const QQuickItem);
5531 return d->widthValid;
5535 \property QQuickItem::height
5537 This property holds the height of this item.
5539 qreal QQuickItem::height() const
5541 Q_D(const QQuickItem);
5545 void QQuickItem::setHeight(qreal h)
5551 d->heightValid = true;
5555 qreal oldHeight = d->height;
5558 d->dirty(QQuickItemPrivate::Size);
5560 geometryChanged(QRectF(x(), y(), width(), height()),
5561 QRectF(x(), y(), width(), oldHeight));
5564 void QQuickItem::resetHeight()
5567 d->heightValid = false;
5568 setImplicitHeight(implicitHeight());
5571 void QQuickItemPrivate::implicitHeightChanged()
5574 for (int ii = 0; ii < changeListeners.count(); ++ii) {
5575 const QQuickItemPrivate::ChangeListener &change = changeListeners.at(ii);
5576 if (change.types & QQuickItemPrivate::ImplicitHeight) {
5577 change.listener->itemImplicitHeightChanged(q);
5580 emit q->implicitHeightChanged();
5583 qreal QQuickItemPrivate::getImplicitHeight() const
5585 return implicitHeight;
5588 qreal QQuickItem::implicitHeight() const
5590 Q_D(const QQuickItem);
5591 return d->getImplicitHeight();
5594 void QQuickItem::setImplicitHeight(qreal h)
5597 bool changed = h != d->implicitHeight;
5598 d->implicitHeight = h;
5599 if (d->height == h || heightValid()) {
5601 d->implicitHeightChanged();
5602 if (d->height == h || heightValid())
5607 qreal oldHeight = d->height;
5610 d->dirty(QQuickItemPrivate::Size);
5612 geometryChanged(QRectF(x(), y(), width(), height()),
5613 QRectF(x(), y(), width(), oldHeight));
5616 d->implicitHeightChanged();
5622 void QQuickItem::setImplicitSize(qreal w, qreal h)
5625 bool wChanged = w != d->implicitWidth;
5626 bool hChanged = h != d->implicitHeight;
5628 d->implicitWidth = w;
5629 d->implicitHeight = h;
5633 if (d->width == w || widthValid()) {
5635 d->implicitWidthChanged();
5636 wDone = d->width == w || widthValid();
5639 if (d->height == h || heightValid()) {
5641 d->implicitHeightChanged();
5642 hDone = d->height == h || heightValid();
5648 qreal oldWidth = d->width;
5649 qreal oldHeight = d->height;
5655 d->dirty(QQuickItemPrivate::Size);
5657 geometryChanged(QRectF(x(), y(), width(), height()),
5658 QRectF(x(), y(), oldWidth, oldHeight));
5660 if (!wDone && wChanged)
5661 d->implicitWidthChanged();
5662 if (!hDone && hChanged)
5663 d->implicitHeightChanged();
5667 Returns whether the height property has been set explicitly.
5669 bool QQuickItem::heightValid() const
5671 Q_D(const QQuickItem);
5672 return d->heightValid;
5678 void QQuickItem::setSize(const QSizeF &size)
5681 d->heightValid = true;
5682 d->widthValid = true;
5684 if (QSizeF(d->width, d->height) == size)
5687 qreal oldHeight = d->height;
5688 qreal oldWidth = d->width;
5689 d->height = size.height();
5690 d->width = size.width();
5692 d->dirty(QQuickItemPrivate::Size);
5694 geometryChanged(QRectF(x(), y(), width(), height()),
5695 QRectF(x(), y(), oldWidth, oldHeight));
5699 \qmlproperty bool QtQuick2::Item::activeFocus
5701 This read-only property indicates whether the item has active focus.
5703 If activeFocus is true, either this item is the one that currently
5704 receives keyboard input, or it is a FocusScope ancestor of the item
5705 that currently receives keyboard input.
5707 Usually, activeFocus is gained by setting \l focus on an item and its
5708 enclosing FocusScope objects. In the following example, the \c input
5709 and \c focusScope objects will have active focus, while the root
5710 rectangle object will not.
5716 width: 100; height: 100
5730 \sa focus, {Keyboard Focus in Qt Quick}
5733 \property QQuickItem::activeFocus
5735 This read-only property indicates whether the item has active focus.
5737 If activeFocus is true, either this item is the one that currently
5738 receives keyboard input, or it is a FocusScope ancestor of the item
5739 that currently receives keyboard input.
5741 Usually, activeFocus is gained by setting \l focus on an item and its
5742 enclosing FocusScope objects. In the following example, the \c input
5743 and \c focusScope objects will have active focus, while the root
5744 rectangle object will not.
5750 width: 100; height: 100
5763 \sa focus, {Keyboard Focus in Qt Quick}
5765 bool QQuickItem::hasActiveFocus() const
5767 Q_D(const QQuickItem);
5768 return d->activeFocus;
5772 \qmlproperty bool QtQuick2::Item::focus
5774 This property holds whether the item has focus within the enclosing
5775 FocusScope. If true, this item will gain active focus when the
5776 enclosing FocusScope gains active focus.
5778 In the following example, \c input will be given active focus when
5779 \c scope gains active focus:
5785 width: 100; height: 100
5798 For the purposes of this property, the scene as a whole is assumed
5799 to act like a focus scope. On a practical level, that means the
5800 following QML will give active focus to \c input on startup.
5804 width: 100; height: 100
5813 \sa activeFocus, {Keyboard Focus in Qt Quick}
5816 \property QQuickItem::focus
5818 This property holds whether the item has focus within the enclosing
5819 FocusScope. If true, this item will gain active focus when the
5820 enclosing FocusScope gains active focus.
5822 In the following example, \c input will be given active focus when
5823 \c scope gains active focus:
5829 width: 100; height: 100
5842 For the purposes of this property, the scene as a whole is assumed
5843 to act like a focus scope. On a practical level, that means the
5844 following QML will give active focus to \c input on startup.
5848 width: 100; height: 100
5857 \sa activeFocus, {Keyboard Focus in Qt Quick}
5859 bool QQuickItem::hasFocus() const
5861 Q_D(const QQuickItem);
5865 void QQuickItem::setFocus(bool focus)
5868 if (d->focus == focus)
5871 if (d->window || d->parentItem) {
5872 // Need to find our nearest focus scope
5873 QQuickItem *scope = parentItem();
5874 while (scope && !scope->isFocusScope() && scope->parentItem())
5875 scope = scope->parentItem();
5878 QQuickWindowPrivate::get(d->window)->setFocusInScope(scope, this);
5880 QQuickWindowPrivate::get(d->window)->clearFocusInScope(scope, this);
5882 // do the focus changes from setFocusInScope/clearFocusInScope that are
5883 // unrelated to a window
5884 QVarLengthArray<QQuickItem *, 20> changed;
5885 QQuickItem *oldSubFocusItem = QQuickItemPrivate::get(scope)->subFocusItem;
5886 if (oldSubFocusItem) {
5887 QQuickItemPrivate::get(oldSubFocusItem)->updateSubFocusItem(scope, false);
5888 QQuickItemPrivate::get(oldSubFocusItem)->focus = false;
5889 changed << oldSubFocusItem;
5890 } else if (!scope->isFocusScope() && scope->hasFocus()) {
5891 QQuickItemPrivate::get(scope)->focus = false;
5894 d->updateSubFocusItem(scope, focus);
5898 emit focusChanged(focus);
5900 QQuickWindowPrivate::notifyFocusChangesRecur(changed.data(), changed.count() - 1);
5903 QVarLengthArray<QQuickItem *, 20> changed;
5904 QQuickItem *oldSubFocusItem = d->subFocusItem;
5905 if (!isFocusScope() && oldSubFocusItem) {
5906 QQuickItemPrivate::get(oldSubFocusItem)->updateSubFocusItem(this, false);
5907 QQuickItemPrivate::get(oldSubFocusItem)->focus = false;
5908 changed << oldSubFocusItem;
5913 emit focusChanged(focus);
5915 QQuickWindowPrivate::notifyFocusChangesRecur(changed.data(), changed.count() - 1);
5920 Returns true if this item is a focus scope, and false otherwise.
5922 bool QQuickItem::isFocusScope() const
5924 return flags() & ItemIsFocusScope;
5928 If this item is a focus scope, this returns the item in its focus chain
5929 that currently has focus.
5931 Returns 0 if this item is not a focus scope.
5933 QQuickItem *QQuickItem::scopedFocusItem() const
5935 Q_D(const QQuickItem);
5936 if (!isFocusScope())
5939 return d->subFocusItem;
5943 Returns the mouse buttons accepted by this item.
5945 The default value is Qt::NoButton; that is, no mouse buttons are accepted.
5947 If an item does not accept the mouse button for a particular mouse event,
5948 the mouse event will not be delivered to the item and will be delivered
5949 to the next item in the item hierarchy instead.
5951 Qt::MouseButtons QQuickItem::acceptedMouseButtons() const
5953 Q_D(const QQuickItem);
5954 return d->acceptedMouseButtons();
5958 Sets the mouse buttons accepted by this item to \a buttons.
5960 void QQuickItem::setAcceptedMouseButtons(Qt::MouseButtons buttons)
5963 if (buttons & Qt::LeftButton)
5966 d->extra.clearFlag();
5968 buttons &= ~Qt::LeftButton;
5969 if (buttons || d->extra.isAllocated())
5970 d->extra.value().acceptedMouseButtons = buttons;
5974 Returns whether mouse events of this item's children should be filtered
5977 \sa setFiltersChildMouseEvents(), childMouseEventFilter()
5979 bool QQuickItem::filtersChildMouseEvents() const
5981 Q_D(const QQuickItem);
5982 return d->filtersChildMouseEvents;
5986 Sets whether mouse events of this item's children should be filtered
5989 If \a filter is true, childMouseEventFilter() will be called when
5990 a mouse event is triggered for a child item.
5992 \sa filtersChildMouseEvents()
5994 void QQuickItem::setFiltersChildMouseEvents(bool filter)
5997 d->filtersChildMouseEvents = filter;
6003 bool QQuickItem::isUnderMouse() const
6005 Q_D(const QQuickItem);
6009 QPointF cursorPos = QGuiApplicationPrivate::lastCursorPosition;
6010 return contains(mapFromScene(d->window->mapFromGlobal(cursorPos.toPoint())));
6014 Returns whether hover events are accepted by this item.
6016 The default value is false.
6018 If this is false, then the item will not receive any hover events through
6019 the hoverEnterEvent(), hoverMoveEvent() and hoverLeaveEvent() functions.
6021 bool QQuickItem::acceptHoverEvents() const
6023 Q_D(const QQuickItem);
6024 return d->hoverEnabled;
6028 If \a enabled is true, this sets the item to accept hover events;
6029 otherwise, hover events are not accepted by this item.
6031 \sa acceptHoverEvents()
6033 void QQuickItem::setAcceptHoverEvents(bool enabled)
6036 d->hoverEnabled = enabled;
6039 void QQuickItemPrivate::incrementCursorCount(int delta)
6041 #ifndef QT_NO_CURSOR
6043 extra.value().numItemsWithCursor += delta;
6044 QQuickItem *parent = q->parentItem();
6046 QQuickItemPrivate *parentPrivate = QQuickItemPrivate::get(parent);
6047 parentPrivate->incrementCursorCount(delta);
6052 #ifndef QT_NO_CURSOR
6055 Returns the cursor shape for this item.
6057 The mouse cursor will assume this shape when it is over this
6058 item, unless an override cursor is set.
6059 See the \l{Qt::CursorShape}{list of predefined cursor objects} for a
6060 range of useful shapes.
6062 If no cursor shape has been set this returns a cursor with the Qt::ArrowCursor shape, however
6063 another cursor shape may be displayed if an overlapping item has a valid cursor.
6065 \sa setCursor(), unsetCursor()
6068 QCursor QQuickItem::cursor() const
6070 Q_D(const QQuickItem);
6071 return d->extra.isAllocated()
6077 Sets the \a cursor shape for this item.
6079 \sa cursor(), unsetCursor()
6082 void QQuickItem::setCursor(const QCursor &cursor)
6086 Qt::CursorShape oldShape = d->extra.isAllocated() ? d->extra->cursor.shape() : Qt::ArrowCursor;
6088 if (oldShape != cursor.shape() || oldShape >= Qt::LastCursor || cursor.shape() >= Qt::LastCursor) {
6089 d->extra.value().cursor = cursor;
6091 QQuickWindowPrivate *windowPrivate = QQuickWindowPrivate::get(d->window);
6092 if (windowPrivate->cursorItem == this)
6093 d->window->setCursor(cursor);
6097 if (!d->hasCursor) {
6098 d->incrementCursorCount(+1);
6099 d->hasCursor = true;
6101 QPointF pos = d->window->mapFromGlobal(QGuiApplicationPrivate::lastCursorPosition.toPoint());
6102 if (contains(mapFromScene(pos)))
6103 QQuickWindowPrivate::get(d->window)->updateCursor(pos);
6109 Clears the cursor shape for this item.
6111 \sa cursor(), setCursor()
6114 void QQuickItem::unsetCursor()
6119 d->incrementCursorCount(-1);
6120 d->hasCursor = false;
6121 if (d->extra.isAllocated())
6122 d->extra->cursor = QCursor();
6125 QQuickWindowPrivate *windowPrivate = QQuickWindowPrivate::get(d->window);
6126 if (windowPrivate->cursorItem == this) {
6127 QPointF pos = d->window->mapFromGlobal(QGuiApplicationPrivate::lastCursorPosition.toPoint());
6128 windowPrivate->updateCursor(pos);
6136 Grabs the mouse input.
6138 This item will receive all mouse events until ungrabMouse() is called.
6140 \warning This function should be used with caution.
6142 void QQuickItem::grabMouse()
6147 QQuickWindowPrivate *windowPriv = QQuickWindowPrivate::get(d->window);
6148 if (windowPriv->mouseGrabberItem == this)
6151 QQuickItem *oldGrabber = windowPriv->mouseGrabberItem;
6152 windowPriv->mouseGrabberItem = this;
6154 QEvent ev(QEvent::UngrabMouse);
6155 d->window->sendEvent(oldGrabber, &ev);
6160 Releases the mouse grab following a call to grabMouse().
6162 void QQuickItem::ungrabMouse()
6167 QQuickWindowPrivate *windowPriv = QQuickWindowPrivate::get(d->window);
6168 if (windowPriv->mouseGrabberItem != this) {
6169 qWarning("QQuickItem::ungrabMouse(): Item is not the mouse grabber.");
6173 windowPriv->mouseGrabberItem = 0;
6175 QEvent ev(QEvent::UngrabMouse);
6176 d->window->sendEvent(this, &ev);
6181 Returns whether mouse input should exclusively remain with this item.
6183 \sa setKeepMouseGrab()
6185 bool QQuickItem::keepMouseGrab() const
6187 Q_D(const QQuickItem);
6188 return d->keepMouse;
6192 Sets whether the mouse input should remain exclusively with this item.
6194 This is useful for items that wish to grab and keep mouse
6195 interaction following a predefined gesture. For example,
6196 an item that is interested in horizontal mouse movement
6197 may set keepMouseGrab to true once a threshold has been
6198 exceeded. Once keepMouseGrab has been set to true, filtering
6199 items will not react to mouse events.
6201 If \a keep is false, a filtering item may steal the grab. For example,
6202 \l Flickable may attempt to steal a mouse grab if it detects that the
6203 user has begun to move the viewport.
6207 void QQuickItem::setKeepMouseGrab(bool keep)
6210 d->keepMouse = keep;
6214 Grabs the touch points specified by \a ids.
6216 These touch points will be owned by the item until
6217 they are released. Alternatively, the grab can be stolen
6218 by a filtering item like Flickable. Use setKeepTouchGrab()
6219 to prevent the grab from being stolen.
6221 \sa ungrabTouchPoints(), setKeepTouchGrab()
6223 void QQuickItem::grabTouchPoints(const QVector<int> &ids)
6228 QQuickWindowPrivate *windowPriv = QQuickWindowPrivate::get(d->window);
6230 QSet<QQuickItem*> ungrab;
6231 for (int i = 0; i < ids.count(); ++i) {
6232 QQuickItem *oldGrabber = windowPriv->itemForTouchPointId.value(ids.at(i));
6233 if (oldGrabber == this)
6236 windowPriv->itemForTouchPointId[ids.at(i)] = this;
6238 ungrab.insert(oldGrabber);
6240 foreach (QQuickItem *oldGrabber, ungrab)
6241 oldGrabber->touchUngrabEvent();
6245 Ungrabs the touch points owned by this item.
6247 \sa grabTouchPoints()
6249 void QQuickItem::ungrabTouchPoints()
6254 QQuickWindowPrivate *windowPriv = QQuickWindowPrivate::get(d->window);
6256 QMutableHashIterator<int, QQuickItem*> i(windowPriv->itemForTouchPointId);
6257 while (i.hasNext()) {
6259 if (i.value() == this)
6266 Returns whether the touch points grabbed by this item should exclusively
6267 remain with this item.
6269 \sa setKeepTouchGrab(), keepMouseGrab()
6271 bool QQuickItem::keepTouchGrab() const
6273 Q_D(const QQuickItem);
6274 return d->keepTouch;
6278 Sets whether the touch points grabbed by this item should remain
6279 exclusively with this item.
6281 This is useful for items that wish to grab and keep specific touch
6282 points following a predefined gesture. For example,
6283 an item that is interested in horizontal touch point movement
6284 may set setKeepTouchGrab to true once a threshold has been
6285 exceeded. Once setKeepTouchGrab has been set to true, filtering
6286 items will not react to the relevant touch points.
6288 If \a keep is false, a filtering item may steal the grab. For example,
6289 \l Flickable may attempt to steal a touch point grab if it detects that the
6290 user has begun to move the viewport.
6292 \sa keepTouchGrab(), setKeepMouseGrab()
6294 void QQuickItem::setKeepTouchGrab(bool keep)
6297 d->keepTouch = keep;
6301 \qmlmethod object QtQuick2::Item::contains(point point)
6303 Returns true if this item contains \a point, which is in local coordinates;
6304 returns false otherwise.
6307 Returns true if this item contains \a point, which is in local coordinates;
6308 returns false otherwise.
6310 This function can be overwritten in order to handle point collisions in items
6311 with custom shapes. The default implementation checks if the point is inside
6312 the item's bounding rect.
6314 Note that this method is generally used to check whether the item is under the mouse cursor,
6315 and for that reason, the implementation of this function should be as light-weight
6318 bool QQuickItem::contains(const QPointF &point) const
6320 Q_D(const QQuickItem);
6321 return QRectF(0, 0, d->width, d->height).contains(point);
6325 Maps the given \a point in this item's coordinate system to the equivalent
6326 point within \a item's coordinate system, and returns the mapped
6329 If \a item is 0, this maps \a point to the coordinate system of the
6332 \sa {Concepts - Visual Coordinates in Qt Quick}
6334 QPointF QQuickItem::mapToItem(const QQuickItem *item, const QPointF &point) const
6336 QPointF p = mapToScene(point);
6338 p = item->mapFromScene(p);
6343 Maps the given \a point in this item's coordinate system to the equivalent
6344 point within the scene's coordinate system, and returns the mapped
6347 \sa {Concepts - Visual Coordinates in Qt Quick}
6349 QPointF QQuickItem::mapToScene(const QPointF &point) const
6351 Q_D(const QQuickItem);
6352 return d->itemToWindowTransform().map(point);
6356 Maps the given \a rect in this item's coordinate system to the equivalent
6357 rectangular area within \a item's coordinate system, and returns the mapped
6360 If \a item is 0, this maps \a rect to the coordinate system of the
6363 \sa {Concepts - Visual Coordinates in Qt Quick}
6365 QRectF QQuickItem::mapRectToItem(const QQuickItem *item, const QRectF &rect) const
6367 Q_D(const QQuickItem);
6368 QTransform t = d->itemToWindowTransform();
6370 t *= QQuickItemPrivate::get(item)->windowToItemTransform();
6371 return t.mapRect(rect);
6375 Maps the given \a rect in this item's coordinate system to the equivalent
6376 rectangular area within the scene's coordinate system, and returns the mapped
6379 \sa {Concepts - Visual Coordinates in Qt Quick}
6381 QRectF QQuickItem::mapRectToScene(const QRectF &rect) const
6383 Q_D(const QQuickItem);
6384 return d->itemToWindowTransform().mapRect(rect);
6388 Maps the given \a point in \a item's coordinate system to the equivalent
6389 point within this item's coordinate system, and returns the mapped
6392 If \a item is 0, this maps \a point from the coordinate system of the
6395 \sa {Concepts - Visual Coordinates in Qt Quick}
6397 QPointF QQuickItem::mapFromItem(const QQuickItem *item, const QPointF &point) const
6399 QPointF p = item?item->mapToScene(point):point;
6400 return mapFromScene(p);
6404 Maps the given \a point in the scene's coordinate system to the equivalent
6405 point within this item's coordinate system, and returns the mapped
6408 \sa {Concepts - Visual Coordinates in Qt Quick}
6410 QPointF QQuickItem::mapFromScene(const QPointF &point) const
6412 Q_D(const QQuickItem);
6413 return d->windowToItemTransform().map(point);
6417 Maps the given \a rect in \a item's coordinate system to the equivalent
6418 rectangular area within this item's coordinate system, and returns the mapped
6421 If \a item is 0, this maps \a rect from the coordinate system of the
6424 \sa {Concepts - Visual Coordinates in Qt Quick}
6426 QRectF QQuickItem::mapRectFromItem(const QQuickItem *item, const QRectF &rect) const
6428 Q_D(const QQuickItem);
6429 QTransform t = item?QQuickItemPrivate::get(item)->itemToWindowTransform():QTransform();
6430 t *= d->windowToItemTransform();
6431 return t.mapRect(rect);
6435 Maps the given \a rect in the scene's coordinate system to the equivalent
6436 rectangular area within this item's coordinate system, and returns the mapped
6439 \sa {Concepts - Visual Coordinates in Qt Quick}
6441 QRectF QQuickItem::mapRectFromScene(const QRectF &rect) const
6443 Q_D(const QQuickItem);
6444 return d->windowToItemTransform().mapRect(rect);
6448 \property QQuickItem::anchors
6453 \property QQuickItem::left
6458 \property QQuickItem::right
6463 \property QQuickItem::horizontalCenter
6468 \property QQuickItem::top
6473 \property QQuickItem::bottom
6478 \property QQuickItem::verticalCenter
6483 \property QQuickItem::baseline
6488 \property QQuickItem::data
6493 \property QQuickItem::resources
6500 bool QQuickItem::event(QEvent *ev)
6503 if (ev->type() == QEvent::PolishRequest) {
6505 d->polishScheduled = false;
6509 return QObject::event(ev);
6512 if (ev->type() == QEvent::InputMethodQuery) {
6513 QInputMethodQueryEvent *query = static_cast<QInputMethodQueryEvent *>(ev);
6514 Qt::InputMethodQueries queries = query->queries();
6515 for (uint i = 0; i < 32; ++i) {
6516 Qt::InputMethodQuery q = (Qt::InputMethodQuery)(int)(queries & (1<<i));
6518 QVariant v = inputMethodQuery(q);
6519 query->setValue(q, v);
6524 } else if (ev->type() == QEvent::InputMethod) {
6525 inputMethodEvent(static_cast<QInputMethodEvent *>(ev));
6527 } else if (ev->type() == QEvent::StyleAnimationUpdate) {
6531 return QObject::event(ev);
6534 #ifndef QT_NO_DEBUG_STREAM
6535 QDebug operator<<(QDebug debug, QQuickItem *item)
6538 debug << "QQuickItem(0)";
6542 debug << item->metaObject()->className() << "(this =" << ((void*)item)
6543 << ", name=" << item->objectName()
6544 << ", parent =" << ((void*)item->parentItem())
6545 << ", geometry =" << QRectF(item->pos(), QSizeF(item->width(), item->height()))
6546 << ", z =" << item->z() << ')';
6551 qint64 QQuickItemPrivate::consistentTime = -1;
6552 void QQuickItemPrivate::setConsistentTime(qint64 t)
6557 class QElapsedTimerConsistentTimeHack
6561 t1 = QQuickItemPrivate::consistentTime;
6565 return QQuickItemPrivate::consistentTime - t1;
6568 qint64 val = QQuickItemPrivate::consistentTime - t1;
6569 t1 = QQuickItemPrivate::consistentTime;
6579 void QQuickItemPrivate::start(QElapsedTimer &t)
6581 if (QQuickItemPrivate::consistentTime == -1)
6584 ((QElapsedTimerConsistentTimeHack*)&t)->start();
6587 qint64 QQuickItemPrivate::elapsed(QElapsedTimer &t)
6589 if (QQuickItemPrivate::consistentTime == -1)
6592 return ((QElapsedTimerConsistentTimeHack*)&t)->elapsed();
6595 qint64 QQuickItemPrivate::restart(QElapsedTimer &t)
6597 if (QQuickItemPrivate::consistentTime == -1)
6600 return ((QElapsedTimerConsistentTimeHack*)&t)->restart();
6604 \fn bool QQuickItem::isTextureProvider() const
6606 Returns true if this item is a texture provider. The default
6607 implementation returns false.
6609 This function can be called from any thread.
6612 bool QQuickItem::isTextureProvider() const
6614 Q_D(const QQuickItem);
6615 return d->extra.isAllocated() && d->extra->layer && d->extra->layer->effectSource() ?
6616 d->extra->layer->effectSource()->isTextureProvider() : false;
6620 \fn QSGTextureProvider *QQuickItem::textureProvider() const
6622 Returns the texture provider for an item. The default implementation
6625 This function may only be called on the rendering thread.
6628 QSGTextureProvider *QQuickItem::textureProvider() const
6630 Q_D(const QQuickItem);
6631 return d->extra.isAllocated() && d->extra->layer && d->extra->layer->effectSource() ?
6632 d->extra->layer->effectSource()->textureProvider() : 0;
6636 \property QQuickItem::layer
6639 QQuickItemLayer *QQuickItemPrivate::layer() const
6641 if (!extra.isAllocated() || !extra->layer) {
6642 extra.value().layer = new QQuickItemLayer(const_cast<QQuickItem *>(q_func()));
6643 if (!componentComplete)
6644 extra->layer->classBegin();
6646 return extra->layer;
6649 QQuickItemLayer::QQuickItemLayer(QQuickItem *item)
6654 , m_componentComplete(true)
6655 , m_wrapMode(QQuickShaderEffectSource::ClampToEdge)
6656 , m_format(QQuickShaderEffectSource::RGBA)
6658 , m_effectComponent(0)
6664 QQuickItemLayer::~QQuickItemLayer()
6666 delete m_effectSource;
6671 \qmlproperty bool QtQuick2::Item::layer.enabled
6673 Holds whether the item is layered or not. Layering is disabled by default.
6675 A layered item is rendered into an offscreen surface and cached until
6676 it is changed. Enabling layering for complex QML item hierarchies can
6677 sometimes be an optimization.
6679 None of the other layer properties have any effect when the layer
6682 void QQuickItemLayer::setEnabled(bool e)
6687 if (m_componentComplete) {
6694 emit enabledChanged(e);
6697 void QQuickItemLayer::classBegin()
6699 Q_ASSERT(!m_effectSource);
6700 Q_ASSERT(!m_effect);
6701 m_componentComplete = false;
6704 void QQuickItemLayer::componentComplete()
6706 Q_ASSERT(!m_componentComplete);
6707 m_componentComplete = true;
6712 void QQuickItemLayer::activate()
6714 Q_ASSERT(!m_effectSource);
6715 m_effectSource = new QQuickShaderEffectSource();
6717 QQuickItem *parentItem = m_item->parentItem();
6719 m_effectSource->setParentItem(parentItem);
6720 m_effectSource->stackAfter(m_item);
6723 m_effectSource->setSourceItem(m_item);
6724 m_effectSource->setHideSource(true);
6725 m_effectSource->setSmooth(m_smooth);
6726 m_effectSource->setTextureSize(m_size);
6727 m_effectSource->setSourceRect(m_sourceRect);
6728 m_effectSource->setMipmap(m_mipmap);
6729 m_effectSource->setWrapMode(m_wrapMode);
6730 m_effectSource->setFormat(m_format);
6732 if (m_effectComponent)
6735 m_effectSource->setVisible(m_item->isVisible() && !m_effect);
6742 QQuickItemPrivate *id = QQuickItemPrivate::get(m_item);
6743 id->addItemChangeListener(this, QQuickItemPrivate::Geometry | QQuickItemPrivate::Opacity | QQuickItemPrivate::Parent | QQuickItemPrivate::Visibility | QQuickItemPrivate::SiblingOrder);
6746 void QQuickItemLayer::deactivate()
6748 Q_ASSERT(m_effectSource);
6750 if (m_effectComponent)
6753 delete m_effectSource;
6756 QQuickItemPrivate *id = QQuickItemPrivate::get(m_item);
6757 id->removeItemChangeListener(this, QQuickItemPrivate::Geometry | QQuickItemPrivate::Opacity | QQuickItemPrivate::Parent | QQuickItemPrivate::Visibility | QQuickItemPrivate::SiblingOrder);
6760 void QQuickItemLayer::activateEffect()
6762 Q_ASSERT(m_effectSource);
6763 Q_ASSERT(m_effectComponent);
6764 Q_ASSERT(!m_effect);
6766 QObject *created = m_effectComponent->beginCreate(m_effectComponent->creationContext());
6767 m_effect = qobject_cast<QQuickItem *>(created);
6769 qWarning("Item: layer.effect is not a QML Item.");
6770 m_effectComponent->completeCreate();
6774 QQuickItem *parentItem = m_item->parentItem();
6776 m_effect->setParentItem(parentItem);
6777 m_effect->stackAfter(m_effectSource);
6779 m_effect->setVisible(m_item->isVisible());
6780 m_effect->setProperty(m_name, qVariantFromValue<QObject *>(m_effectSource));
6781 m_effectComponent->completeCreate();
6784 void QQuickItemLayer::deactivateEffect()
6786 Q_ASSERT(m_effectSource);
6787 Q_ASSERT(m_effectComponent);
6795 \qmlproperty Component QtQuick2::Item::layer.effect
6797 Holds the effect that is applied to this layer.
6799 The effect is typically a \l ShaderEffect component, although any \l Item component can be
6800 assigned. The effect should have a source texture property with a name matching \l layer.samplerName.
6802 \sa layer.samplerName
6805 void QQuickItemLayer::setEffect(QQmlComponent *component)
6807 if (component == m_effectComponent)
6810 bool updateNeeded = false;
6811 if (m_effectSource && m_effectComponent) {
6813 updateNeeded = true;
6816 m_effectComponent = component;
6818 if (m_effectSource && m_effectComponent) {
6820 updateNeeded = true;
6828 m_effectSource->setVisible(m_item->isVisible() && !m_effect);
6831 emit effectChanged(component);
6836 \qmlproperty bool QtQuick2::Item::layer.mipmap
6838 If this property is true, mipmaps are generated for the texture.
6840 \note Some OpenGL ES 2 implementations do not support mipmapping of
6841 non-power-of-two textures.
6844 void QQuickItemLayer::setMipmap(bool mipmap)
6846 if (mipmap == m_mipmap)
6851 m_effectSource->setMipmap(m_mipmap);
6853 emit mipmapChanged(mipmap);
6858 \qmlproperty enumeration QtQuick2::Item::layer.format
6860 This property defines the internal OpenGL format of the texture.
6861 Modifying this property makes most sense when the \a layer.effect is also
6862 specified. Depending on the OpenGL implementation, this property might
6863 allow you to save some texture memory.
6866 \li ShaderEffectSource.Alpha - GL_ALPHA
6867 \li ShaderEffectSource.RGB - GL_RGB
6868 \li ShaderEffectSource.RGBA - GL_RGBA
6871 \note Some OpenGL implementations do not support the GL_ALPHA format.
6874 void QQuickItemLayer::setFormat(QQuickShaderEffectSource::Format f)
6881 m_effectSource->setFormat(m_format);
6883 emit formatChanged(m_format);
6888 \qmlproperty enumeration QtQuick2::Item::layer.sourceRect
6890 This property defines the rectangular area of the item that should be
6891 rendered into the texture. The source rectangle can be larger than
6892 the item itself. If the rectangle is null, which is the default,
6893 then the whole item is rendered to the texture.
6896 void QQuickItemLayer::setSourceRect(const QRectF &sourceRect)
6898 if (sourceRect == m_sourceRect)
6900 m_sourceRect = sourceRect;
6903 m_effectSource->setSourceRect(m_sourceRect);
6905 emit sourceRectChanged(sourceRect);
6909 \qmlproperty bool QtQuick2::Item::layer.smooth
6911 Holds whether the layer is smoothly transformed.
6914 void QQuickItemLayer::setSmooth(bool s)
6921 m_effectSource->setSmooth(m_smooth);
6923 emit smoothChanged(s);
6927 \qmlproperty size QtQuick2::Item::layer.textureSize
6929 This property holds the requested pixel size of the layers texture. If it is empty,
6930 which is the default, the size of the item is used.
6932 \note Some platforms have a limit on how small framebuffer objects can be,
6933 which means the actual texture size might be larger than the requested
6937 void QQuickItemLayer::setSize(const QSize &size)
6944 m_effectSource->setTextureSize(size);
6946 emit sizeChanged(size);
6950 \qmlproperty enumeration QtQuick2::Item::layer.wrapMode
6952 This property defines the OpenGL wrap modes associated with the texture.
6953 Modifying this property makes most sense when the \a layer.effect is
6957 \li ShaderEffectSource.ClampToEdge - GL_CLAMP_TO_EDGE both horizontally and vertically
6958 \li ShaderEffectSource.RepeatHorizontally - GL_REPEAT horizontally, GL_CLAMP_TO_EDGE vertically
6959 \li ShaderEffectSource.RepeatVertically - GL_CLAMP_TO_EDGE horizontally, GL_REPEAT vertically
6960 \li ShaderEffectSource.Repeat - GL_REPEAT both horizontally and vertically
6963 \note Some OpenGL ES 2 implementations do not support the GL_REPEAT
6964 wrap mode with non-power-of-two textures.
6967 void QQuickItemLayer::setWrapMode(QQuickShaderEffectSource::WrapMode mode)
6969 if (mode == m_wrapMode)
6974 m_effectSource->setWrapMode(m_wrapMode);
6976 emit wrapModeChanged(mode);
6980 \qmlproperty string QtQuick2::Item::layer.samplerName
6982 Holds the name of the effect's source texture property.
6984 This value must match the name of the effect's source texture property
6985 so that the Item can pass the layer's offscreen surface to the effect correctly.
6987 \sa layer.effect, ShaderEffect
6990 void QQuickItemLayer::setName(const QByteArray &name) {
6994 m_effect->setProperty(m_name, QVariant());
6995 m_effect->setProperty(name, qVariantFromValue<QObject *>(m_effectSource));
6998 emit nameChanged(name);
7001 void QQuickItemLayer::itemOpacityChanged(QQuickItem *item)
7007 void QQuickItemLayer::itemGeometryChanged(QQuickItem *, const QRectF &, const QRectF &)
7012 void QQuickItemLayer::itemParentChanged(QQuickItem *item, QQuickItem *parent)
7015 Q_ASSERT(item == m_item);
7016 Q_ASSERT(parent != m_effectSource);
7017 Q_ASSERT(parent == 0 || parent != m_effect);
7019 m_effectSource->setParentItem(parent);
7021 m_effectSource->stackAfter(m_item);
7024 m_effect->setParentItem(parent);
7026 m_effect->stackAfter(m_effectSource);
7030 void QQuickItemLayer::itemSiblingOrderChanged(QQuickItem *)
7032 m_effectSource->stackAfter(m_item);
7034 m_effect->stackAfter(m_effectSource);
7037 void QQuickItemLayer::itemVisibilityChanged(QQuickItem *)
7039 QQuickItem *l = m_effect ? (QQuickItem *) m_effect : (QQuickItem *) m_effectSource;
7041 l->setVisible(m_item->isVisible());
7044 void QQuickItemLayer::updateZ()
7046 if (!m_componentComplete || !m_enabled)
7048 QQuickItem *l = m_effect ? (QQuickItem *) m_effect : (QQuickItem *) m_effectSource;
7050 l->setZ(m_item->z());
7053 void QQuickItemLayer::updateOpacity()
7055 QQuickItem *l = m_effect ? (QQuickItem *) m_effect : (QQuickItem *) m_effectSource;
7057 l->setOpacity(m_item->opacity());
7060 void QQuickItemLayer::updateGeometry()
7062 QQuickItem *l = m_effect ? (QQuickItem *) m_effect : (QQuickItem *) m_effectSource;
7064 QRectF bounds = m_item->clipRect();
7065 l->setWidth(bounds.width());
7066 l->setHeight(bounds.height());
7067 l->setX(bounds.x() + m_item->x());
7068 l->setY(bounds.y() + m_item->y());
7071 void QQuickItemLayer::updateMatrix()
7073 // Called directly from transformChanged(), so needs some extra
7075 if (!m_componentComplete || !m_enabled)
7077 QQuickItem *l = m_effect ? (QQuickItem *) m_effect : (QQuickItem *) m_effectSource;
7079 QQuickItemPrivate *ld = QQuickItemPrivate::get(l);
7080 l->setScale(m_item->scale());
7081 l->setRotation(m_item->rotation());
7082 ld->transforms = QQuickItemPrivate::get(m_item)->transforms;
7083 if (ld->origin() != QQuickItemPrivate::get(m_item)->origin())
7084 ld->extra.value().origin = QQuickItemPrivate::get(m_item)->origin();
7085 ld->dirty(QQuickItemPrivate::Transform);
7088 QQuickItemPrivate::ExtraData::ExtraData()
7089 : z(0), scale(1), rotation(0), opacity(1),
7090 contents(0), screenAttached(0), layoutDirectionAttached(0),
7091 keyHandler(0), layer(0),
7092 #ifndef QT_NO_CURSOR
7093 numItemsWithCursor(0),
7095 effectRefCount(0), hideRefCount(0),
7096 opacityNode(0), clipNode(0), rootNode(0), beforePaintNode(0),
7097 acceptedMouseButtons(0), origin(QQuickItem::Center)
7103 #include <moc_qquickitem.cpp>