source: trunk/src/gui/graphicsview/qgraphicsitem.h@ 661

Last change on this file since 661 was 651, checked in by Dmitry A. Kuminov, 15 years ago

trunk: Merged in qt 4.6.2 sources.
File size: 39.5 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the QtGui module of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:LGPL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in
14** a written agreement between you and Nokia.
15**
16** GNU Lesser General Public License Usage
17** Alternatively, this file may be used under the terms of the GNU Lesser
18** General Public License version 2.1 as published by the Free Software
19** Foundation and appearing in the file LICENSE.LGPL included in the
20** packaging of this file. Please review the following information to
21** ensure the GNU Lesser General Public License version 2.1 requirements
22** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
23**
24** In addition, as a special exception, Nokia gives you certain additional
25** rights. These rights are described in the Nokia Qt LGPL Exception
26** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you have questions regarding the use of this file, please contact
37** Nokia at [email protected].
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42#ifndef QGRAPHICSITEM_H
43#define QGRAPHICSITEM_H
44
45#include <QtCore/qglobal.h>
46#include <QtCore/qobject.h>
47#include <QtCore/qvariant.h>
48#include <QtCore/qrect.h>
49#include <QtCore/qscopedpointer.h>
50#include <QtGui/qpainterpath.h>
51#include <QtGui/qpixmap.h>
52
53class tst_QGraphicsItem;
54
55QT_BEGIN_HEADER
56
57QT_BEGIN_NAMESPACE
58
59QT_MODULE(Gui)
60
61#if !defined(QT_NO_GRAPHICSVIEW) || (QT_EDITION & QT_MODULE_GRAPHICSVIEW) != QT_MODULE_GRAPHICSVIEW
62
63class QBrush;
64class QCursor;
65class QFocusEvent;
66class QGraphicsEffect;
67class QGraphicsItemGroup;
68class QGraphicsObject;
69class QGraphicsSceneContextMenuEvent;
70class QGraphicsSceneDragDropEvent;
71class QGraphicsSceneEvent;
72class QGraphicsSceneHoverEvent;
73class QGraphicsSceneMouseEvent;
74class QGraphicsSceneWheelEvent;
75class QGraphicsScene;
76class QGraphicsTransform;
77class QGraphicsWidget;
78class QInputMethodEvent;
79class QKeyEvent;
80class QMatrix;
81class QMenu;
82class QPainter;
83class QPen;
84class QPointF;
85class QRectF;
86class QStyleOptionGraphicsItem;
87
88class QGraphicsItemPrivate;
89class Q_GUI_EXPORT QGraphicsItem
90{
91public:
92 enum GraphicsItemFlag {
93 ItemIsMovable = 0x1,
94 ItemIsSelectable = 0x2,
95 ItemIsFocusable = 0x4,
96 ItemClipsToShape = 0x8,
97 ItemClipsChildrenToShape = 0x10,
98 ItemIgnoresTransformations = 0x20,
99 ItemIgnoresParentOpacity = 0x40,
100 ItemDoesntPropagateOpacityToChildren = 0x80,
101 ItemStacksBehindParent = 0x100,
102 ItemUsesExtendedStyleOption = 0x200,
103 ItemHasNoContents = 0x400,
104 ItemSendsGeometryChanges = 0x800,
105 ItemAcceptsInputMethod = 0x1000,
106 ItemNegativeZStacksBehindParent = 0x2000,
107 ItemIsPanel = 0x4000,
108 ItemIsFocusScope = 0x8000, // internal
109 ItemSendsScenePositionChanges = 0x10000
110 // NB! Don't forget to increase the d_ptr->flags bit field by 1 when adding a new flag.
111 };
112 Q_DECLARE_FLAGS(GraphicsItemFlags, GraphicsItemFlag)
113
114 enum GraphicsItemChange {
115 ItemPositionChange,
116 ItemMatrixChange,
117 ItemVisibleChange,
118 ItemEnabledChange,
119 ItemSelectedChange,
120 ItemParentChange,
121 ItemChildAddedChange,
122 ItemChildRemovedChange,
123 ItemTransformChange,
124 ItemPositionHasChanged,
125 ItemTransformHasChanged,
126 ItemSceneChange,
127 ItemVisibleHasChanged,
128 ItemEnabledHasChanged,
129 ItemSelectedHasChanged,
130 ItemParentHasChanged,
131 ItemSceneHasChanged,
132 ItemCursorChange,
133 ItemCursorHasChanged,
134 ItemToolTipChange,
135 ItemToolTipHasChanged,
136 ItemFlagsChange,
137 ItemFlagsHaveChanged,
138 ItemZValueChange,
139 ItemZValueHasChanged,
140 ItemOpacityChange,
141 ItemOpacityHasChanged,
142 ItemScenePositionHasChanged
143 };
144
145 enum CacheMode {
146 NoCache,
147 ItemCoordinateCache,
148 DeviceCoordinateCache
149 };
150
151 enum PanelModality
152 {
153 NonModal,
154 PanelModal,
155 SceneModal
156 };
157
158 QGraphicsItem(QGraphicsItem *parent = 0
159#ifndef Q_QDOC
160 // ### obsolete argument
161 , QGraphicsScene *scene = 0
162#endif
163 );
164 virtual ~QGraphicsItem();
165
166 QGraphicsScene *scene() const;
167
168 QGraphicsItem *parentItem() const;
169 QGraphicsItem *topLevelItem() const;
170 QGraphicsObject *parentObject() const;
171 QGraphicsWidget *parentWidget() const;
172 QGraphicsWidget *topLevelWidget() const;
173 QGraphicsWidget *window() const;
174 QGraphicsItem *panel() const;
175 void setParentItem(QGraphicsItem *parent);
176 QList<QGraphicsItem *> children() const; // ### obsolete
177 QList<QGraphicsItem *> childItems() const;
178 bool isWidget() const;
179 bool isWindow() const;
180 bool isPanel() const;
181
182 QGraphicsObject *toGraphicsObject();
183 const QGraphicsObject *toGraphicsObject() const;
184
185 QGraphicsItemGroup *group() const;
186 void setGroup(QGraphicsItemGroup *group);
187
188 GraphicsItemFlags flags() const;
189 void setFlag(GraphicsItemFlag flag, bool enabled = true);
190 void setFlags(GraphicsItemFlags flags);
191
192 CacheMode cacheMode() const;
193 void setCacheMode(CacheMode mode, const QSize &cacheSize = QSize());
194
195 PanelModality panelModality() const;
196 void setPanelModality(PanelModality panelModality);
197 bool isBlockedByModalPanel(QGraphicsItem **blockingPanel = 0) const;
198
199#ifndef QT_NO_TOOLTIP
200 QString toolTip() const;
201 void setToolTip(const QString &toolTip);
202#endif
203
204#ifndef QT_NO_CURSOR
205 QCursor cursor() const;
206 void setCursor(const QCursor &cursor);
207 bool hasCursor() const;
208 void unsetCursor();
209#endif
210
211 bool isVisible() const;
212 bool isVisibleTo(const QGraphicsItem *parent) const;
213 void setVisible(bool visible);
214 inline void hide() { setVisible(false); }
215 inline void show() { setVisible(true); }
216
217 bool isEnabled() const;
218 void setEnabled(bool enabled);
219
220 bool isSelected() const;
221 void setSelected(bool selected);
222
223 bool acceptDrops() const;
224 void setAcceptDrops(bool on);
225
226 qreal opacity() const;
227 qreal effectiveOpacity() const;
228 void setOpacity(qreal opacity);
229
230#ifndef QT_NO_GRAPHICSEFFECT
231 // Effect
232 QGraphicsEffect *graphicsEffect() const;
233 void setGraphicsEffect(QGraphicsEffect *effect);
234#endif //QT_NO_GRAPHICSEFFECT
235
236 Qt::MouseButtons acceptedMouseButtons() const;
237 void setAcceptedMouseButtons(Qt::MouseButtons buttons);
238
239 bool acceptsHoverEvents() const; // ### obsolete
240 void setAcceptsHoverEvents(bool enabled); // ### obsolete
241 bool acceptHoverEvents() const;
242 void setAcceptHoverEvents(bool enabled);
243 bool acceptTouchEvents() const;
244 void setAcceptTouchEvents(bool enabled);
245
246 bool filtersChildEvents() const;
247 void setFiltersChildEvents(bool enabled);
248
249 bool handlesChildEvents() const;
250 void setHandlesChildEvents(bool enabled);
251
252 bool isActive() const;
253 void setActive(bool active);
254
255 bool hasFocus() const;
256 void setFocus(Qt::FocusReason focusReason = Qt::OtherFocusReason);
257 void clearFocus();
258
259 QGraphicsItem *focusProxy() const;
260 void setFocusProxy(QGraphicsItem *item);
261
262 QGraphicsItem *focusItem() const;
263 QGraphicsItem *focusScopeItem() const;
264
265 void grabMouse();
266 void ungrabMouse();
267 void grabKeyboard();
268 void ungrabKeyboard();
269
270 // Positioning in scene coordinates
271 QPointF pos() const;
272 inline qreal x() const { return pos().x(); }
273 void setX(qreal x);
274 inline qreal y() const { return pos().y(); }
275 void setY(qreal y);
276 QPointF scenePos() const;
277 void setPos(const QPointF &pos);
278 inline void setPos(qreal x, qreal y);
279 inline void moveBy(qreal dx, qreal dy) { setPos(pos().x() + dx, pos().y() + dy); }
280
281 void ensureVisible(const QRectF &rect = QRectF(), int xmargin = 50, int ymargin = 50);
282 inline void ensureVisible(qreal x, qreal y, qreal w, qreal h, int xmargin = 50, int ymargin = 50);
283
284 // Local transformation
285 QMatrix matrix() const;
286 QMatrix sceneMatrix() const;
287 void setMatrix(const QMatrix &matrix, bool combine = false);
288 void resetMatrix();
289 QTransform transform() const;
290 QTransform sceneTransform() const;
291 QTransform deviceTransform(const QTransform &viewportTransform) const;
292 QTransform itemTransform(const QGraphicsItem *other, bool *ok = 0) const;
293 void setTransform(const QTransform &matrix, bool combine = false);
294 void resetTransform();
295
296 void rotate(qreal angle); // ### obsolete
297 void scale(qreal sx, qreal sy); // ### obsolete
298 void shear(qreal sh, qreal sv); // ### obsolete
299 void translate(qreal dx, qreal dy); // ### obsolete
300
301 void setRotation(qreal angle);
302 qreal rotation() const;
303
304 void setScale(qreal scale);
305 qreal scale() const;
306
307 QList<QGraphicsTransform *> transformations() const;
308 void setTransformations(const QList<QGraphicsTransform *> &transformations);
309
310 QPointF transformOriginPoint() const;
311 void setTransformOriginPoint(const QPointF &origin);
312 inline void setTransformOriginPoint(qreal ax, qreal ay)
313 { setTransformOriginPoint(QPointF(ax,ay)); }
314
315 virtual void advance(int phase);
316
317 // Stacking order
318 qreal zValue() const;
319 void setZValue(qreal z);
320 void stackBefore(const QGraphicsItem *sibling);
321
322 // Hit test
323 virtual QRectF boundingRect() const = 0;
324 QRectF childrenBoundingRect() const;
325 QRectF sceneBoundingRect() const;
326 virtual QPainterPath shape() const;
327 bool isClipped() const;
328 QPainterPath clipPath() const;
329 virtual bool contains(const QPointF &point) const;
330 virtual bool collidesWithItem(const QGraphicsItem *other, Qt::ItemSelectionMode mode = Qt::IntersectsItemShape) const;
331 virtual bool collidesWithPath(const QPainterPath &path, Qt::ItemSelectionMode mode = Qt::IntersectsItemShape) const;
332 QList<QGraphicsItem *> collidingItems(Qt::ItemSelectionMode mode = Qt::IntersectsItemShape) const;
333 bool isObscured() const;
334 bool isObscured(const QRectF &rect) const; // ### Qt 5: merge with isObscured(), add QRectF arg to isObscuredBy()
335 inline bool isObscured(qreal x, qreal y, qreal w, qreal h) const;
336 virtual bool isObscuredBy(const QGraphicsItem *item) const;
337 virtual QPainterPath opaqueArea() const;
338
339 QRegion boundingRegion(const QTransform &itemToDeviceTransform) const;
340 qreal boundingRegionGranularity() const;
341 void setBoundingRegionGranularity(qreal granularity);
342
343 // Drawing
344 virtual void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = 0) = 0;
345 void update(const QRectF &rect = QRectF());
346 inline void update(qreal x, qreal y, qreal width, qreal height);
347 void scroll(qreal dx, qreal dy, const QRectF &rect = QRectF());
348
349 // Coordinate mapping
350 QPointF mapToItem(const QGraphicsItem *item, const QPointF &point) const;
351 QPointF mapToParent(const QPointF &point) const;
352 QPointF mapToScene(const QPointF &point) const;
353 QPolygonF mapToItem(const QGraphicsItem *item, const QRectF &rect) const;
354 QPolygonF mapToParent(const QRectF &rect) const;
355 QPolygonF mapToScene(const QRectF &rect) const;
356 QRectF mapRectToItem(const QGraphicsItem *item, const QRectF &rect) const;
357 QRectF mapRectToParent(const QRectF &rect) const;
358 QRectF mapRectToScene(const QRectF &rect) const;
359 QPolygonF mapToItem(const QGraphicsItem *item, const QPolygonF &polygon) const;
360 QPolygonF mapToParent(const QPolygonF &polygon) const;
361 QPolygonF mapToScene(const QPolygonF &polygon) const;
362 QPainterPath mapToItem(const QGraphicsItem *item, const QPainterPath &path) const;
363 QPainterPath mapToParent(const QPainterPath &path) const;
364 QPainterPath mapToScene(const QPainterPath &path) const;
365 QPointF mapFromItem(const QGraphicsItem *item, const QPointF &point) const;
366 QPointF mapFromParent(const QPointF &point) const;
367 QPointF mapFromScene(const QPointF &point) const;
368 QPolygonF mapFromItem(const QGraphicsItem *item, const QRectF &rect) const;
369 QPolygonF mapFromParent(const QRectF &rect) const;
370 QPolygonF mapFromScene(const QRectF &rect) const;
371 QRectF mapRectFromItem(const QGraphicsItem *item, const QRectF &rect) const;
372 QRectF mapRectFromParent(const QRectF &rect) const;
373 QRectF mapRectFromScene(const QRectF &rect) const;
374 QPolygonF mapFromItem(const QGraphicsItem *item, const QPolygonF &polygon) const;
375 QPolygonF mapFromParent(const QPolygonF &polygon) const;
376 QPolygonF mapFromScene(const QPolygonF &polygon) const;
377 QPainterPath mapFromItem(const QGraphicsItem *item, const QPainterPath &path) const;
378 QPainterPath mapFromParent(const QPainterPath &path) const;
379 QPainterPath mapFromScene(const QPainterPath &path) const;
380
381 inline QPointF mapToItem(const QGraphicsItem *item, qreal x, qreal y) const;
382 inline QPointF mapToParent(qreal x, qreal y) const;
383 inline QPointF mapToScene(qreal x, qreal y) const;
384 inline QPolygonF mapToItem(const QGraphicsItem *item, qreal x, qreal y, qreal w, qreal h) const;
385 inline QPolygonF mapToParent(qreal x, qreal y, qreal w, qreal h) const;
386 inline QPolygonF mapToScene(qreal x, qreal y, qreal w, qreal h) const;
387 inline QRectF mapRectToItem(const QGraphicsItem *item, qreal x, qreal y, qreal w, qreal h) const;
388 inline QRectF mapRectToParent(qreal x, qreal y, qreal w, qreal h) const;
389 inline QRectF mapRectToScene(qreal x, qreal y, qreal w, qreal h) const;
390 inline QPointF mapFromItem(const QGraphicsItem *item, qreal x, qreal y) const;
391 inline QPointF mapFromParent(qreal x, qreal y) const;
392 inline QPointF mapFromScene(qreal x, qreal y) const;
393 inline QPolygonF mapFromItem(const QGraphicsItem *item, qreal x, qreal y, qreal w, qreal h) const;
394 inline QPolygonF mapFromParent(qreal x, qreal y, qreal w, qreal h) const;
395 inline QPolygonF mapFromScene(qreal x, qreal y, qreal w, qreal h) const;
396 inline QRectF mapRectFromItem(const QGraphicsItem *item, qreal x, qreal y, qreal w, qreal h) const;
397 inline QRectF mapRectFromParent(qreal x, qreal y, qreal w, qreal h) const;
398 inline QRectF mapRectFromScene(qreal x, qreal y, qreal w, qreal h) const;
399
400 bool isAncestorOf(const QGraphicsItem *child) const;
401 QGraphicsItem *commonAncestorItem(const QGraphicsItem *other) const;
402 bool isUnderMouse() const;
403
404 // Custom data
405 QVariant data(int key) const;
406 void setData(int key, const QVariant &value);
407
408 Qt::InputMethodHints inputMethodHints() const;
409 void setInputMethodHints(Qt::InputMethodHints hints);
410
411 enum {
412 Type = 1,
413 UserType = 65536
414 };
415 virtual int type() const;
416