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

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