1// Copyright (C) 2020 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#ifndef QQUICKITEM_H
5#define QQUICKITEM_H
6
7#include <QtQuick/qtquickglobal.h>
8#include <QtQml/qqml.h>
9#include <QtQml/qqmlcomponent.h>
10
11#include <QtCore/QObject>
12#include <QtCore/QList>
13#include <QtCore/qproperty.h>
14#include <QtGui/qevent.h>
15#include <QtGui/qfont.h>
16#include <QtGui/qaccessible.h>
17
18QT_BEGIN_NAMESPACE
19
20class QQuickItem;
21class QQuickTransformPrivate;
22class Q_QUICK_EXPORT QQuickTransform : public QObject
23{
24 Q_OBJECT
25 QML_ANONYMOUS
26 QML_ADDED_IN_VERSION(2, 0)
27public:
28 explicit QQuickTransform(QObject *parent = nullptr);
29 ~QQuickTransform() override;
30
31 void appendToItem(QQuickItem *);
32 void prependToItem(QQuickItem *);
33
34 virtual void applyTo(QMatrix4x4 *matrix) const = 0;
35
36protected Q_SLOTS:
37 void update();
38
39protected:
40 QQuickTransform(QQuickTransformPrivate &dd, QObject *parent);
41
42private:
43 Q_DECLARE_PRIVATE(QQuickTransform)
44};
45
46class QCursor;
47class QQuickItemLayer;
48class QQmlV4Function;
49class QQuickState;
50class QQuickAnchorLine;
51class QQuickTransition;
52class QQuickKeyEvent;
53class QQuickAnchors;
54class QQuickItemPrivate;
55class QQuickWindow;
56class QTouchEvent;
57class QSGNode;
58class QSGTransformNode;
59class QSGTextureProvider;
60class QQuickItemGrabResult;
61class QQuickPalette;
62
63class Q_QUICK_EXPORT QQuickItem : public QObject, public QQmlParserStatus
64{
65 Q_OBJECT
66 Q_INTERFACES(QQmlParserStatus)
67
68 Q_PROPERTY(QQuickItem *parent READ parentItem WRITE setParentItem NOTIFY parentChanged DESIGNABLE false FINAL)
69 Q_PRIVATE_PROPERTY(QQuickItem::d_func(), QQmlListProperty<QObject> data READ data DESIGNABLE false)
70 Q_PRIVATE_PROPERTY(QQuickItem::d_func(), QQmlListProperty<QObject> resources READ resources DESIGNABLE false)
71 Q_PRIVATE_PROPERTY(QQuickItem::d_func(), QQmlListProperty<QQuickItem> children READ children NOTIFY childrenChanged DESIGNABLE false)
72
73 Q_PROPERTY(qreal x READ x WRITE setX NOTIFY xChanged BINDABLE bindableX FINAL)
74 Q_PROPERTY(qreal y READ y WRITE setY NOTIFY yChanged BINDABLE bindableY FINAL)
75 Q_PROPERTY(qreal z READ z WRITE setZ NOTIFY zChanged FINAL)
76 Q_PROPERTY(qreal width READ width WRITE setWidth NOTIFY widthChanged RESET resetWidth BINDABLE bindableWidth FINAL)
77 Q_PROPERTY(qreal height READ height WRITE setHeight NOTIFY heightChanged RESET resetHeight BINDABLE bindableHeight FINAL)
78
79 Q_PROPERTY(qreal opacity READ opacity WRITE setOpacity NOTIFY opacityChanged FINAL)
80 Q_PROPERTY(bool enabled READ isEnabled WRITE setEnabled NOTIFY enabledChanged)
81 Q_PROPERTY(bool visible READ isVisible WRITE setVisible NOTIFY visibleChanged FINAL)
82 Q_PRIVATE_PROPERTY(QQuickItem::d_func(), QQuickPalette *palette READ palette WRITE setPalette RESET resetPalette NOTIFY paletteChanged REVISION(6, 0))
83 Q_PRIVATE_PROPERTY(QQuickItem::d_func(), QQmlListProperty<QQuickItem> visibleChildren READ visibleChildren NOTIFY visibleChildrenChanged DESIGNABLE false)
84
85 Q_PRIVATE_PROPERTY(QQuickItem::d_func(), QQmlListProperty<QQuickState> states READ states DESIGNABLE false)
86 Q_PRIVATE_PROPERTY(QQuickItem::d_func(), QQmlListProperty<QQuickTransition> transitions READ transitions DESIGNABLE false)
87 Q_PROPERTY(QString state READ state WRITE setState NOTIFY stateChanged)
88 Q_PROPERTY(QRectF childrenRect READ childrenRect NOTIFY childrenRectChanged DESIGNABLE false FINAL)
89 Q_PRIVATE_PROPERTY(QQuickItem::d_func(), QQuickAnchors * anchors READ anchors DESIGNABLE false CONSTANT FINAL)
90 Q_PRIVATE_PROPERTY(QQuickItem::d_func(), QQuickAnchorLine left READ left CONSTANT FINAL)
91 Q_PRIVATE_PROPERTY(QQuickItem::d_func(), QQuickAnchorLine right READ right CONSTANT FINAL)
92 Q_PRIVATE_PROPERTY(QQuickItem::d_func(), QQuickAnchorLine horizontalCenter READ horizontalCenter CONSTANT FINAL)
93 Q_PRIVATE_PROPERTY(QQuickItem::d_func(), QQuickAnchorLine top READ top CONSTANT FINAL)
94 Q_PRIVATE_PROPERTY(QQuickItem::d_func(), QQuickAnchorLine bottom READ bottom CONSTANT FINAL)
95 Q_PRIVATE_PROPERTY(QQuickItem::d_func(), QQuickAnchorLine verticalCenter READ verticalCenter CONSTANT FINAL)
96 Q_PRIVATE_PROPERTY(QQuickItem::d_func(), QQuickAnchorLine baseline READ baseline CONSTANT FINAL)
97 Q_PROPERTY(qreal baselineOffset READ baselineOffset WRITE setBaselineOffset NOTIFY baselineOffsetChanged)
98
99 Q_PROPERTY(bool clip READ clip WRITE setClip NOTIFY clipChanged FINAL)
100
101 Q_PROPERTY(bool focus READ hasFocus WRITE setFocus NOTIFY focusChanged FINAL)
102 Q_PROPERTY(bool activeFocus READ hasActiveFocus NOTIFY activeFocusChanged FINAL)
103 Q_PROPERTY(bool activeFocusOnTab READ activeFocusOnTab WRITE setActiveFocusOnTab NOTIFY activeFocusOnTabChanged FINAL REVISION(2, 1))
104
105 Q_PROPERTY(qreal rotation READ rotation WRITE setRotation NOTIFY rotationChanged)
106 Q_PROPERTY(qreal scale READ scale WRITE setScale NOTIFY scaleChanged)
107 Q_PROPERTY(TransformOrigin transformOrigin READ transformOrigin WRITE setTransformOrigin NOTIFY transformOriginChanged FINAL)
108 Q_PROPERTY(QPointF transformOriginPoint READ transformOriginPoint FINAL) // deprecated - see QTBUG-26423
109 Q_PROPERTY(QQmlListProperty<QQuickTransform> transform READ transform DESIGNABLE false FINAL)
110
111 Q_PROPERTY(bool smooth READ smooth WRITE setSmooth NOTIFY smoothChanged FINAL)
112 Q_PROPERTY(bool antialiasing READ antialiasing WRITE setAntialiasing NOTIFY antialiasingChanged RESET resetAntialiasing FINAL)
113 Q_PROPERTY(qreal implicitWidth READ implicitWidth WRITE setImplicitWidth NOTIFY implicitWidthChanged)
114 Q_PROPERTY(qreal implicitHeight READ implicitHeight WRITE setImplicitHeight NOTIFY implicitHeightChanged)
115 Q_PROPERTY(QObject *containmentMask READ containmentMask WRITE setContainmentMask NOTIFY containmentMaskChanged REVISION(2, 11) FINAL)
116
117#if QT_CONFIG(quick_shadereffect)
118 Q_PRIVATE_PROPERTY(QQuickItem::d_func(), QQuickItemLayer *layer READ layer DESIGNABLE false CONSTANT FINAL)
119#endif
120
121 Q_CLASSINFO("DefaultProperty", "data")
122 Q_CLASSINFO("ParentProperty", "parent")
123 Q_CLASSINFO("qt_QmlJSWrapperFactoryMethod", "_q_createJSWrapper(QV4::ExecutionEngine*)")
124 QML_NAMED_ELEMENT(Item)
125 QML_ADDED_IN_VERSION(2, 0)
126
127public:
128 enum Flag {
129 ItemClipsChildrenToShape = 0x01,
130#if QT_CONFIG(im)
131 ItemAcceptsInputMethod = 0x02,
132#endif
133 ItemIsFocusScope = 0x04,
134 ItemHasContents = 0x08,
135 ItemAcceptsDrops = 0x10,
136 ItemIsViewport = 0x20,
137 ItemObservesViewport = 0x40,
138 // Remember to increment the size of QQuickItemPrivate::flags
139 };
140 Q_DECLARE_FLAGS(Flags, Flag)
141 Q_FLAG(Flags)
142
143 enum ItemChange {
144 ItemChildAddedChange, // value.item
145 ItemChildRemovedChange, // value.item
146 ItemSceneChange, // value.window
147 ItemVisibleHasChanged, // value.boolValue
148 ItemParentHasChanged, // value.item
149 ItemOpacityHasChanged, // value.realValue
150 ItemActiveFocusHasChanged, // value.boolValue
151 ItemRotationHasChanged, // value.realValue
152 ItemAntialiasingHasChanged, // value.boolValue
153 ItemDevicePixelRatioHasChanged, // value.realValue
154 ItemEnabledHasChanged // value.boolValue
155 };
156 Q_ENUM(ItemChange)
157
158 union ItemChangeData {
159 ItemChangeData(QQuickItem *v) : item(v) {}
160 ItemChangeData(QQuickWindow *v) : window(v) {}
161 ItemChangeData(qreal v) : realValue(v) {}
162 ItemChangeData(bool v) : boolValue(v) {}
163
164 QQuickItem *item;
165 QQuickWindow *window;
166 qreal realValue;
167 bool boolValue;
168 };
169
170 enum TransformOrigin {
171 TopLeft, Top, TopRight,
172 Left, Center, Right,
173 BottomLeft, Bottom, BottomRight
174 };
175 Q_ENUM(TransformOrigin)
176
177 explicit QQuickItem(QQuickItem *parent = nullptr);
178 ~QQuickItem() override;
179
180 QQuickWindow *window() const;
181 QQuickItem *parentItem() const;
182 void setParentItem(QQuickItem *parent);
183 void stackBefore(const QQuickItem *);
184 void stackAfter(const QQuickItem *);
185
186 QRectF childrenRect();
187 QList<QQuickItem *> childItems() const;
188
189 bool clip() const;
190 void setClip(bool);
191
192 QString state() const;
193 void setState(const QString &);
194
195 qreal baselineOffset() const;
196 void setBaselineOffset(qreal);
197
198 QQmlListProperty<QQuickTransform> transform();
199
200 qreal x() const;
201 qreal y() const;
202 QPointF position() const;
203 void setX(qreal);
204 void setY(qreal);
205 void setPosition(const QPointF &);
206 QBindable<qreal> bindableX();
207 QBindable<qreal> bindableY();
208
209 qreal width() const;
210 void setWidth(qreal);
211 void resetWidth();
212 void setImplicitWidth(qreal);
213 qreal implicitWidth() const;
214 QBindable<qreal> bindableWidth();
215
216 qreal height() const;
217 void setHeight(qreal);
218 void resetHeight();
219 void setImplicitHeight(qreal);
220 qreal implicitHeight() const;
221 QBindable<qreal> bindableHeight();
222
223 QSizeF size() const;
224 void setSize(const QSizeF &size);
225
226 TransformOrigin transformOrigin() const;
227 void setTransformOrigin(TransformOrigin);
228 QPointF transformOriginPoint() const;
229 void setTransformOriginPoint(const QPointF &);
230
231 qreal z() const;
232 void setZ(qreal);
233
234 qreal rotation() const;
235 void setRotation(qreal);
236 qreal scale() const;
237 void setScale(qreal);
238
239 qreal opacity() const;
240 void setOpacity(qreal);
241
242 bool isVisible() const;
243 void setVisible(bool);
244
245 bool isEnabled() const;
246 void setEnabled(bool);
247
248 bool smooth() const;
249 void setSmooth(bool);
250
251 bool activeFocusOnTab() const;
252 void setActiveFocusOnTab(bool);
253
254 bool antialiasing() const;
255 void setAntialiasing(bool);
256 void resetAntialiasing();
257
258 Flags flags() const;
259 void setFlag(Flag flag, bool enabled = true);
260 void setFlags(Flags flags);
261
262 virtual QRectF boundingRect() const;
263 virtual QRectF clipRect() const;
264 QQuickItem *viewportItem() const;
265
266 bool hasActiveFocus() const;
267 bool hasFocus() const;
268 void setFocus(bool);
269 void setFocus(bool focus, Qt::FocusReason reason);
270 bool isFocusScope() const;
271 QQuickItem *scopedFocusItem() const;
272
273 bool isAncestorOf(const QQuickItem *child) const;
274
275 Qt::MouseButtons acceptedMouseButtons() const;
276 void setAcceptedMouseButtons(Qt::MouseButtons buttons);
277 bool acceptHoverEvents() const;
278 void setAcceptHoverEvents(bool enabled);
279 bool acceptTouchEvents() const;
280 void setAcceptTouchEvents(bool accept);
281
282#if QT_CONFIG(cursor)
283 QCursor cursor() const;
284 void setCursor(const QCursor &cursor);
285 void unsetCursor();
286#endif
287
288 bool isUnderMouse() const;
289 void grabMouse();
290 void ungrabMouse();
291 bool keepMouseGrab() const;
292 void setKeepMouseGrab(bool);
293 bool filtersChildMouseEvents() const;
294 void setFiltersChildMouseEvents(bool filter);
295
296 void grabTouchPoints(const QList<int> &ids);
297 void ungrabTouchPoints();
298 bool keepTouchGrab() const;
299 void setKeepTouchGrab(bool);
300
301 // implemented in qquickitemgrabresult.cpp
302 Q_REVISION(2, 4) Q_INVOKABLE bool grabToImage(const QJSValue &callback, const QSize &targetSize = QSize());
303 QSharedPointer<QQuickItemGrabResult> grabToImage(const QSize &targetSize = QSize());
304
305 Q_INVOKABLE virtual bool contains(const QPointF &point) const;
306 QObject *containmentMask() const;
307 void setContainmentMask(QObject *mask);
308
309 QTransform itemTransform(QQuickItem *, bool *) const;
310 QPointF mapToScene(const QPointF &point) const;
311 QRectF mapRectToItem(const QQuickItem *item, const QRectF &rect) const;
312 QRectF mapRectToScene(const QRectF &rect) const;
313 QPointF mapFromScene(const QPointF &point) const;
314 QRectF mapRectFromItem(const QQuickItem *item, const QRectF &rect) const;
315 QRectF mapRectFromScene(const QRectF &rect) const;
316
317 void polish();
318
319#if QT_DEPRECATED_SINCE(6, 5)
320 QT_DEPRECATED_VERSION_X_6_5("Use typed overload or mapRectFromItem")
321 void mapFromItem(QQmlV4Function*) const;
322#endif
323 Q_INVOKABLE QPointF mapFromItem(const QQuickItem *item, const QPointF &point) const;
324 // overloads mainly exist for QML
325 Q_INVOKABLE QPointF mapFromItem(const QQuickItem *item, qreal x, qreal y);
326 Q_INVOKABLE QRectF mapFromItem(const QQuickItem *item, const QRectF &rect) const;
327 Q_INVOKABLE QRectF mapFromItem(const QQuickItem *item, qreal x, qreal y, qreal width, qreal height) const;
328
329#if QT_DEPRECATED_SINCE(6, 5)
330 QT_DEPRECATED_VERSION_X_6_5("Use typed overload or mapRectToItem")
331 void mapToItem(QQmlV4Function*) const;
332#endif
333 Q_INVOKABLE QPointF mapToItem(const QQuickItem *item, const QPointF &point) const;
334 // overloads mainly exist for QML
335 Q_INVOKABLE QPointF mapToItem(const QQuickItem *item, qreal x, qreal y);
336 Q_INVOKABLE QRectF mapToItem(const QQuickItem *item, const QRectF &rect) const;
337 Q_INVOKABLE QRectF mapToItem(const QQuickItem *item, qreal x, qreal y, qreal width, qreal height) const;
338
339#if QT_DEPRECATED_SINCE(6, 5)
340 QT_DEPRECATED_VERSION_X_6_5("Use the typed overload")
341 Q_REVISION(2, 7) void mapFromGlobal(QQmlV4Function*) const;
342#endif
343 Q_REVISION(2, 7) Q_INVOKABLE QPointF mapFromGlobal(qreal x, qreal y) const;
344 // overload mainly exists for QML
345 Q_REVISION(2, 7) Q_INVOKABLE QPointF mapFromGlobal(const QPointF &point) const;
346
347#if QT_DEPRECATED_SINCE(6, 5)
348 QT_DEPRECATED_VERSION_X_6_5("Use the typed overload")
349 Q_REVISION(2, 7) void mapToGlobal(QQmlV4Function*) const;
350#endif
351 Q_REVISION(2, 7) Q_INVOKABLE QPointF mapToGlobal(qreal x, qreal y) const;
352 // overload only exist for QML
353 Q_REVISION(2, 7) Q_INVOKABLE QPointF mapToGlobal(const QPointF &point) const;
354
355 Q_INVOKABLE void forceActiveFocus();
356 Q_INVOKABLE void forceActiveFocus(Qt::FocusReason reason);
357 Q_REVISION(2, 1) Q_INVOKABLE QQuickItem *nextItemInFocusChain(bool forward = true);
358 Q_INVOKABLE QQuickItem *childAt(qreal x, qreal y) const;
359 Q_REVISION(6, 3) Q_INVOKABLE void ensurePolished();
360
361 Q_REVISION(6, 3) Q_INVOKABLE void dumpItemTree() const;
362
363#if QT_CONFIG(im)
364 virtual QVariant inputMethodQuery(Qt::InputMethodQuery query) const;
365#endif
366
367 struct UpdatePaintNodeData {
368 QSGTransformNode *transformNode;
369 private:
370 friend class QQuickWindowPrivate;
371 UpdatePaintNodeData();
372 };
373
374 virtual bool isTextureProvider() const;
375 virtual QSGTextureProvider *textureProvider() const;
376
377public Q_SLOTS:
378 void update();
379
380Q_SIGNALS:
381 void childrenRectChanged(const QRectF &);
382 void baselineOffsetChanged(qreal);
383 void stateChanged(const QString &);
384 void focusChanged(bool);
385 void activeFocusChanged(bool);
386 Q_REVISION(2, 1) void activeFocusOnTabChanged(bool);
387 void parentChanged(QQuickItem *);
388 void transformOriginChanged(TransformOrigin);
389 void smoothChanged(bool);
390 void antialiasingChanged(bool);
391 void clipChanged(bool);
392 Q_REVISION(2, 1) void windowChanged(QQuickWindow* window);
393
394 void childrenChanged();
395 void opacityChanged();
396 void enabledChanged();
397 void visibleChanged();
398 void visibleChildrenChanged();
399 void rotationChanged();
400 void scaleChanged();
401
402 void xChanged();
403 void yChanged();
404 void widthChanged();
405 void heightChanged();
406 void zChanged();
407 void implicitWidthChanged();
408 void implicitHeightChanged();
409 Q_REVISION(2, 11) void containmentMaskChanged();
410
411 Q_REVISION(6, 0) void paletteChanged();
412 Q_REVISION(6, 0) void paletteCreated();
413
414protected:
415 bool event(QEvent *) override;
416
417 bool isComponentComplete() const;
418 virtual void itemChange(ItemChange, const ItemChangeData &);
419 virtual void geometryChange(const QRectF &newGeometry, const QRectF &oldGeometry);
420
421#if QT_CONFIG(im)
422 void updateInputMethod(Qt::InputMethodQueries queries = Qt::ImQueryInput);
423#endif
424
425 bool widthValid() const; // ### better name?
426 bool heightValid() const; // ### better name?
427 void setImplicitSize(qreal, qreal);
428
429 void classBegin() override;
430 void componentComplete() override;
431
432 virtual void keyPressEvent(QKeyEvent *event);
433 virtual void keyReleaseEvent(QKeyEvent *event);
434#if QT_CONFIG(im)
435 virtual void inputMethodEvent(QInputMethodEvent *);
436#endif
437 virtual void focusInEvent(QFocusEvent *);
438 virtual void focusOutEvent(QFocusEvent *);
439 virtual void mousePressEvent(QMouseEvent *event);
440 virtual void mouseMoveEvent(QMouseEvent *event);
441 virtual void mouseReleaseEvent(QMouseEvent *event);
442 virtual void mouseDoubleClickEvent(QMouseEvent *event);
443 virtual void mouseUngrabEvent(); // XXX todo - params?
444 virtual void touchUngrabEvent();
445#if QT_CONFIG(wheelevent)
446 virtual void wheelEvent(QWheelEvent *event);
447#endif
448 virtual void touchEvent(QTouchEvent *event);
449 virtual void hoverEnterEvent(QHoverEvent *event);
450 virtual void hoverMoveEvent(QHoverEvent *event);
451 virtual void hoverLeaveEvent(QHoverEvent *event);
452#if QT_CONFIG(quick_draganddrop)
453 virtual void dragEnterEvent(QDragEnterEvent *);
454 virtual void dragMoveEvent(QDragMoveEvent *);
455 virtual void dragLeaveEvent(QDragLeaveEvent *);
456 virtual void dropEvent(QDropEvent *);
457#endif
458 virtual bool childMouseEventFilter(QQuickItem *, QEvent *);
459
460 virtual QSGNode *updatePaintNode(QSGNode *, UpdatePaintNodeData *);
461 virtual void releaseResources();
462 virtual void updatePolish();
463
464 QQuickItem(QQuickItemPrivate &dd, QQuickItem *parent = nullptr);
465
466private:
467 Q_PRIVATE_SLOT(d_func(), void _q_resourceObjectDeleted(QObject *))
468 Q_PRIVATE_SLOT(d_func(), quint64 _q_createJSWrapper(QV4::ExecutionEngine *))
469
470 friend class QQuickWindowPrivate;
471 friend class QQuickDeliveryAgentPrivate;
472 friend class QSGRenderer;
473 friend class QAccessibleQuickItem;
474 friend class QQuickAccessibleAttached;
475 friend class QQuickAnchorChanges;
476 Q_DISABLE_COPY(QQuickItem)
477 Q_DECLARE_PRIVATE(QQuickItem)
478};
479
480Q_DECLARE_OPERATORS_FOR_FLAGS(QQuickItem::Flags)
481
482#ifndef Q_QDOC
483template <> inline QQuickItem *qobject_cast<QQuickItem *>(QObject *o)
484{
485 if (!o || !o->isQuickItemType())
486 return nullptr;
487 return static_cast<QQuickItem *>(o);
488}
489template <> inline const QQuickItem *qobject_cast<const QQuickItem *>(const QObject *o)
490{
491 if (!o || !o->isQuickItemType())
492 return nullptr;
493 return static_cast<const QQuickItem *>(o);
494}
495#endif // !Q_QDOC
496
497#ifndef QT_NO_DEBUG_STREAM
498QDebug Q_QUICK_EXPORT operator<<(QDebug debug,
499#if QT_VERSION >= QT_VERSION_CHECK(7, 0, 0)
500 const
501#endif
502 QQuickItem *item);
503#endif // QT_NO_DEBUG_STREAM
504
505QT_END_NAMESPACE
506
507QML_DECLARE_TYPE(QQuickItem)
508QML_DECLARE_TYPE(QQuickTransform)
509
510#endif // QQUICKITEM_H
511

source code of qtdeclarative/src/quick/items/qquickitem.h