/****************************************************************************

**

** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the QtGui module of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

#ifndef QGRAPHICSITEM_H

#define QGRAPHICSITEM_H

#include <QtCore/qglobal.h>

#include <QtCore/qobject.h>

#include <QtCore/qvariant.h>

#include <QtCore/qrect.h>

#include <QtCore/qscopedpointer.h>

#include <QtGui/qpainterpath.h>

#include <QtGui/qpixmap.h>

class tst_QGraphicsItem;

QT_BEGIN_HEADER

QT_BEGIN_NAMESPACE

QT_MODULE(Gui)

#if !defined(QT_NO_GRAPHICSVIEW) || (QT_EDITION & QT_MODULE_GRAPHICSVIEW) != QT_MODULE_GRAPHICSVIEW

class QBrush;

class QCursor;

class QFocusEvent;

class QGraphicsEffect;

class QGraphicsItemGroup;

class QGraphicsObject;

class QGraphicsSceneContextMenuEvent;

class QGraphicsSceneDragDropEvent;

class QGraphicsSceneEvent;

class QGraphicsSceneHoverEvent;

class QGraphicsSceneMouseEvent;

class QGraphicsSceneWheelEvent;

class QGraphicsScene;

class QGraphicsTransform;

class QGraphicsWidget;

class QInputMethodEvent;

class QKeyEvent;

class QMatrix;

class QMenu;

class QPainter;

class QPen;

class QPointF;

class QRectF;

class QStyleOptionGraphicsItem;

class QGraphicsItemPrivate;

class Q_GUI_EXPORT QGraphicsItem

{

public:

    enum GraphicsItemFlag {

        ItemIsMovable = 0x1,

        ItemIsSelectable = 0x2,

        ItemIsFocusable = 0x4,

        ItemClipsToShape = 0x8,

        ItemClipsChildrenToShape = 0x10,

        ItemIgnoresTransformations = 0x20,

        ItemIgnoresParentOpacity = 0x40,

        ItemDoesntPropagateOpacityToChildren = 0x80,

        ItemStacksBehindParent = 0x100,

        ItemUsesExtendedStyleOption = 0x200,

        ItemHasNoContents = 0x400,

        ItemSendsGeometryChanges = 0x800,

        ItemAcceptsInputMethod = 0x1000,

        ItemNegativeZStacksBehindParent = 0x2000,

        ItemIsPanel = 0x4000,

        ItemIsFocusScope = 0x8000 // internal

        // NB! Don't forget to increase the d_ptr->flags bit field by 1 when adding a new flag.

    };

    Q_DECLARE_FLAGS(GraphicsItemFlags, GraphicsItemFlag)

    enum GraphicsItemChange {

        ItemPositionChange,

        ItemMatrixChange,

        ItemVisibleChange,

        ItemEnabledChange,

        ItemSelectedChange,

        ItemParentChange,

        ItemChildAddedChange,

        ItemChildRemovedChange,

        ItemTransformChange,

        ItemPositionHasChanged,

        ItemTransformHasChanged,

        ItemSceneChange,

        ItemVisibleHasChanged,

        ItemEnabledHasChanged,

        ItemSelectedHasChanged,

        ItemParentHasChanged,

        ItemSceneHasChanged,

        ItemCursorChange,

        ItemCursorHasChanged,

        ItemToolTipChange,

        ItemToolTipHasChanged,

        ItemFlagsChange,

        ItemFlagsHaveChanged,

        ItemZValueChange,

        ItemZValueHasChanged,

        ItemOpacityChange,

        ItemOpacityHasChanged

    };

    enum CacheMode {

        NoCache,

        ItemCoordinateCache,

        DeviceCoordinateCache

    };

    enum PanelModality

    {

        NonModal,

        PanelModal,

        SceneModal

    };

    QGraphicsItem(QGraphicsItem *parent = 0

#ifndef Q_QDOC

                  // ### obsolete argument

                  , QGraphicsScene *scene = 0

#endif

        );

    virtual ~QGraphicsItem();

    QGraphicsScene *scene() const;

    QGraphicsItem *parentItem() const;

    QGraphicsItem *topLevelItem() const;

    QGraphicsObject *parentObject() const;

    QGraphicsWidget *parentWidget() const;

    QGraphicsWidget *topLevelWidget() const;

    QGraphicsWidget *window() const;

    QGraphicsItem *panel() const;

    void setParentItem(QGraphicsItem *parent);

    QList<QGraphicsItem *> children() const; // ### obsolete

    QList<QGraphicsItem *> childItems() const;

    bool isWidget() const;

    bool isWindow() const;

    bool isPanel() const;

    QGraphicsObject *toGraphicsObject();

    const QGraphicsObject *toGraphicsObject() const;

    QGraphicsItemGroup *group() const;

    void setGroup(QGraphicsItemGroup *group);

    GraphicsItemFlags flags() const;

    void setFlag(GraphicsItemFlag flag, bool enabled = true);

    void setFlags(GraphicsItemFlags flags);

    CacheMode cacheMode() const;

    void setCacheMode(CacheMode mode, const QSize &cacheSize = QSize());

    PanelModality panelModality() const;

    void setPanelModality(PanelModality panelModality);

    bool isBlockedByModalPanel(QGraphicsItem **blockingPanel = 0) const;

#ifndef QT_NO_TOOLTIP

    QString toolTip() const;

    void setToolTip(const QString &toolTip);

#endif

#ifndef QT_NO_CURSOR

    QCursor cursor() const;

    void setCursor(const QCursor &cursor);

    bool hasCursor() const;

    void unsetCursor();

#endif

    bool isVisible() const;

    bool isVisibleTo(const QGraphicsItem *parent) const;

    void setVisible(bool visible);

    inline void hide() { setVisible(false); }

    inline void show() { setVisible(true); }

    bool isEnabled() const;

    void setEnabled(bool enabled);

    bool isSelected() const;

    void setSelected(bool selected);

    bool acceptDrops() const;

    void setAcceptDrops(bool on);

    qreal opacity() const;

    qreal effectiveOpacity() const;

    void setOpacity(qreal opacity);

    // Effect

    QGraphicsEffect *graphicsEffect() const;

    void setGraphicsEffect(QGraphicsEffect *effect);

    Qt::MouseButtons acceptedMouseButtons() const;

    void setAcceptedMouseButtons(Qt::MouseButtons buttons);

    bool acceptsHoverEvents() const; // ### obsolete

    void setAcceptsHoverEvents(bool enabled); // ### obsolete

    bool acceptHoverEvents() const;

    void setAcceptHoverEvents(bool enabled);

    bool acceptTouchEvents() const;

    void setAcceptTouchEvents(bool enabled);

    bool filtersChildEvents() const;

    void setFiltersChildEvents(bool enabled);

    bool handlesChildEvents() const;

    void setHandlesChildEvents(bool enabled);

    bool isActive() const;

    void setActive(bool active);

    bool hasFocus() const;

    void setFocus(Qt::FocusReason focusReason = Qt::OtherFocusReason);

    void clearFocus();

    QGraphicsItem *focusProxy() const;

    void setFocusProxy(QGraphicsItem *item);

    QGraphicsItem *focusItem() const;

    QGraphicsItem *focusScopeItem() const;

    void grabMouse();

    void ungrabMouse();

    void grabKeyboard();

    void ungrabKeyboard();

    // Positioning in scene coordinates

    QPointF pos() const;

    inline qreal x() const { return pos().x(); }

    void setX(qreal x);

    inline qreal y() const { return pos().y(); }

    void setY(qreal y);

    QPointF scenePos() const;

    void setPos(const QPointF &pos);

    inline void setPos(qreal x, qreal y);

    inline void moveBy(qreal dx, qreal dy) { setPos(pos().x() + dx, pos().y() + dy); }

    void ensureVisible(const QRectF &rect = QRectF(), int xmargin = 50, int ymargin = 50);

    inline void ensureVisible(qreal x, qreal y, qreal w, qreal h, int xmargin = 50, int ymargin = 50);

    // Local transformation

    QMatrix matrix() const;

    QMatrix sceneMatrix() const;

    void setMatrix(const QMatrix &matrix, bool combine = false);

    void resetMatrix();

    QTransform transform() const;

    QTransform sceneTransform() const;

    QTransform deviceTransform(const QTransform &viewportTransform) const;

    QTransform itemTransform(const QGraphicsItem *other, bool *ok = 0) const;

    void setTransform(const QTransform &matrix, bool combine = false);

    void resetTransform();

    void rotate(qreal angle);           // ### obsolete

    void scale(qreal sx, qreal sy);     // ### obsolete

    void shear(qreal sh, qreal sv);     // ### obsolete

    void translate(qreal dx, qreal dy); // ### obsolete

    void setRotation(qreal angle);

    qreal rotation() const;

    void setScale(qreal scale);

    qreal scale() const;

    QList<QGraphicsTransform *> transformations() const;

    void setTransformations(const QList<QGraphicsTransform *> &transformations);

    QPointF transformOriginPoint() const;

    void setTransformOriginPoint(const QPointF &origin);

    inline void setTransformOriginPoint(qreal ax, qreal ay)

    { setTransformOriginPoint(QPointF(ax,ay)); }

    virtual void advance(int phase);

    // Stacking order

    qreal zValue() const;

    void setZValue(qreal z);

    void stackBefore(const QGraphicsItem *sibling);

    // Hit test

    virtual QRectF boundingRect() const = 0;

    QRectF childrenBoundingRect() const;

    QRectF sceneBoundingRect() const;

    virtual QPainterPath shape() const;

    bool isClipped() const;

    QPainterPath clipPath() const;

    virtual bool contains(const QPointF &point) const;

    virtual bool collidesWithItem(const QGraphicsItem *other, Qt::ItemSelectionMode mode = Qt::IntersectsItemShape) const;

    virtual bool collidesWithPath(const QPainterPath &path, Qt::ItemSelectionMode mode = Qt::IntersectsItemShape) const;

    QList<QGraphicsItem *> collidingItems(Qt::ItemSelectionMode mode = Qt::IntersectsItemShape) const;

    bool isObscured() const;

    bool isObscured(const QRectF &rect) const; // ### Qt 5: merge with isObscured(), add QRectF arg to isObscuredBy()

    inline bool isObscured(qreal x, qreal y, qreal w, qreal h) const;

    virtual bool isObscuredBy(const QGraphicsItem *item) const;

    virtual QPainterPath opaqueArea() const;

    QRegion boundingRegion(const QTransform &itemToDeviceTransform) const;

    qreal boundingRegionGranularity() const;

    void setBoundingRegionGranularity(qreal granularity);

    // Drawing

    virtual void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = 0) = 0;

    void update(const QRectF &rect = QRectF());

    inline void update(qreal x, qreal y, qreal width, qreal height);

    void scroll(qreal dx, qreal dy, const QRectF &rect = QRectF());

    // Coordinate mapping

    QPointF mapToItem(const QGraphicsItem *item, const QPointF &point) const;

    QPointF mapToParent(const QPointF &point) const;

    QPointF mapToScene(const QPointF &point) const;

    QPolygonF mapToItem(const QGraphicsItem *item, const QRectF &rect) const;

    QPolygonF mapToParent(const QRectF &rect) const;

    QPolygonF mapToScene(const QRectF &rect) const;

    QRectF mapRectToItem(const QGraphicsItem *item, const QRectF &rect) const;

    QRectF mapRectToParent(const QRectF &rect) const;

    QRectF mapRectToScene(const QRectF &rect) const;

    QPolygonF mapToItem(const QGraphicsItem *item, const QPolygonF &polygon) const;

    QPolygonF mapToParent(const QPolygonF &polygon) const;

    QPolygonF mapToScene(const QPolygonF &polygon) const;

    QPainterPath mapToItem(const QGraphicsItem *item, const QPainterPath &path) const;

    QPainterPath mapToParent(const QPainterPath &path) const;

    QPainterPath mapToScene(const QPainterPath &path) const;

    QPointF mapFromItem(const QGraphicsItem *item, const QPointF &point) const;

    QPointF mapFromParent(const QPointF &point) const;

    QPointF mapFromScene(const QPointF &point) const;

    QPolygonF mapFromItem(const QGraphicsItem *item, const QRectF &rect) const;

    QPolygonF mapFromParent(const QRectF &rect) const;

    QPolygonF mapFromScene(const QRectF &rect) const;

    QRectF mapRectFromItem(const QGraphicsItem *item, const QRectF &rect) const;

    QRectF mapRectFromParent(const QRectF &rect) const;

    QRectF mapRectFromScene(const QRectF &rect) const;

    QPolygonF mapFromItem(const QGraphicsItem *item, const QPolygonF &polygon) const;

    QPolygonF mapFromParent(const QPolygonF &polygon) const;

    QPolygonF mapFromScene(const QPolygonF &polygon) const;

    QPainterPath mapFromItem(const QGraphicsItem *item, const QPainterPath &path) const;

    QPainterPath mapFromParent(const QPainterPath &path) const;

    QPainterPath mapFromScene(const QPainterPath &path) const;

    inline QPointF mapToItem(const QGraphicsItem *item, qreal x, qreal y) const;

    inline QPointF mapToParent(qreal x, qreal y) const;

    inline QPointF mapToScene(qreal x, qreal y) const;

    inline QPolygonF mapToItem(const QGraphicsItem *item, qreal x, qreal y, qreal w, qreal h) const;

    inline QPolygonF mapToParent(qreal x, qreal y, qreal w, qreal h) const;

    inline QPolygonF mapToScene(qreal x, qreal y, qreal w, qreal h) const;

    inline QRectF mapRectToItem(const QGraphicsItem *item, qreal x, qreal y, qreal w, qreal h) const;

    inline QRectF mapRectToParent(qreal x, qreal y, qreal w, qreal h) const;

    inline QRectF mapRectToScene(qreal x, qreal y, qreal w, qreal h) const;

    inline QPointF mapFromItem(const QGraphicsItem *item, qreal x, qreal y) const;

    inline QPointF mapFromParent(qreal x, qreal y) const;

    inline QPointF mapFromScene(qreal x, qreal y) const;

    inline QPolygonF mapFromItem(const QGraphicsItem *item, qreal x, qreal y, qreal w, qreal h) const;

    inline QPolygonF mapFromParent(qreal x, qreal y, qreal w, qreal h) const;

    inline QPolygonF mapFromScene(qreal x, qreal y, qreal w, qreal h) const;

    inline QRectF mapRectFromItem(const QGraphicsItem *item, qreal x, qreal y, qreal w, qreal h) const;

    inline QRectF mapRectFromParent(qreal x, qreal y, qreal w, qreal h) const;

    inline QRectF mapRectFromScene(qreal x, qreal y, qreal w, qreal h) const;

    bool isAncestorOf(const QGraphicsItem *child) const;

    QGraphicsItem *commonAncestorItem(const QGraphicsItem *other) const;

    bool isUnderMouse() const;

    // Custom data

    QVariant data(int key) const;

    void setData(int key, const QVariant &value);

    Qt::InputMethodHints inputMethodHints() const;

    void setInputMethodHints(Qt::InputMethodHints hints);

    enum {

        Type = 1,

        UserType = 65536

    };

    virtual int type() const;

    void installSceneEventFilter(QGraphicsItem *filterItem);

    void removeSceneEventFilter(QGraphicsItem *filterItem);

protected:

    virtual bool sceneEventFilter(QGraphicsItem *watched, QEvent *event);

    virtual bool sceneEvent(QEvent *event);

    virtual void contextMenuEvent(QGraphicsSceneContextMenuEvent *event);

    virtual void dragEnterEvent(QGraphicsSceneDragDropEvent *event);

    virtual void dragLeaveEvent(QGraphicsSceneDragDropEvent *event);

    virtual void dragMoveEvent(QGraphicsSceneDragDropEvent *event);

    virtual void dropEvent(QGraphicsSceneDragDropEvent *event);

    virtual void focusInEvent(QFocusEvent *event);

    virtual void focusOutEvent(QFocusEvent *event);

    virtual void hoverEnterEvent(QGraphicsSceneHoverEvent *event);

    virtual void hoverMoveEvent(QGraphicsSceneHoverEvent *event);

    virtual void hoverLeaveEvent(QGraphicsSceneHoverEvent *event);

    virtual void keyPressEvent(QKeyEvent *event);

    virtual void keyReleaseEvent(QKeyEvent *event);

    virtual void mousePressEvent(QGraphicsSceneMouseEvent *event);

    virtual void mouseMoveEvent(QGraphicsSceneMouseEvent *event);

    virtual void mouseReleaseEvent(QGraphicsSceneMouseEvent *event);

    virtual void mouseDoubleClickEvent(QGraphicsSceneMouseEvent *event);

    virtual void wheelEvent(QGraphicsSceneWheelEvent *event);

    virtual void inputMethodEvent(QInputMethodEvent *event);

    virtual QVariant inputMethodQuery(Qt::InputMethodQuery query) const;

    virtual QVariant itemChange(GraphicsItemChange change, const QVariant &value);

    enum Extension {

        UserExtension = 0x80000000

    };

    virtual bool supportsExtension(Extension extension) const;

    virtual void setExtension(Extension extension, const QVariant &variant);

    virtual QVariant extension(const QVariant &variant) const;

protected:

    QGraphicsItem(QGraphicsItemPrivate &dd,

                  QGraphicsItem *parent, QGraphicsScene *scene);

    QScopedPointer<QGraphicsItemPrivate> d_ptr;

    void addToIndex();

    void removeFromIndex();

    void prepareGeometryChange();

private:

    Q_DISABLE_COPY(QGraphicsItem)

    Q_DECLARE_PRIVATE(QGraphicsItem)

    friend class QGraphicsItemGroup;

    friend class QGraphicsScene;

    friend class QGraphicsScenePrivate;

    friend class QGraphicsSceneFindItemBspTreeVisitor;

    friend class QGraphicsSceneBspTree;

    friend class QGraphicsView;

    friend class QGraphicsViewPrivate;

    friend class QGraphicsObject;

    friend class QGraphicsWidget;

    friend class QGraphicsWidgetPrivate;

    friend class QGraphicsProxyWidgetPrivate;

    friend class QGraphicsSceneIndex;

    friend class QGraphicsSceneIndexPrivate;

    friend class QGraphicsSceneBspTreeIndex;

    friend class QGraphicsSceneBspTreeIndexPrivate;

    friend class QGraphicsItemEffectSourcePrivate;

    friend class QGraphicsTransformPrivate;

    friend class QGestureManager;

    friend class ::tst_QGraphicsItem;

    friend bool qt_closestLeaf(const QGraphicsItem *, const QGraphicsItem *);

    friend bool qt_closestItemFirst(const QGraphicsItem *, const QGraphicsItem *);

};

Q_DECLARE_OPERATORS_FOR_FLAGS(QGraphicsItem::GraphicsItemFlags)

Q_DECLARE_INTERFACE(QGraphicsItem, "com.trolltech.Qt.QGraphicsItem")

inline void QGraphicsItem::setPos(qreal ax, qreal ay)

{ setPos(QPointF(ax, ay)); }

inline void QGraphicsItem::ensureVisible(qreal ax, qreal ay, qreal w, qreal h, int xmargin, int ymargin)

{ ensureVisible(QRectF(ax, ay, w, h), xmargin, ymargin); }

inline void QGraphicsItem::update(qreal ax, qreal ay, qreal width, qreal height)

{ update(QRectF(ax, ay, width, height)); }

inline bool QGraphicsItem::isObscured(qreal ax, qreal ay, qreal w, qreal h) const

{ return isObscured(QRectF(ax, ay, w, h)); }

inline QPointF QGraphicsItem::mapToItem(const QGraphicsItem *item, qreal ax, qreal ay) const

{ return mapToItem(item, QPointF(ax, ay)); }

inline QPointF QGraphicsItem::mapToParent(qreal ax, qreal ay) const

{ return mapToParent(QPointF(ax, ay)); }

inline QPointF QGraphicsItem::mapToScene(qreal ax, qreal ay) const

{ return mapToScene(QPointF(ax, ay));  }

inline QPointF QGraphicsItem::mapFromItem(const QGraphicsItem *item, qreal ax, qreal ay) const

{ return mapFromItem(item, QPointF(ax, ay)); }

inline QPointF QGraphicsItem::mapFromParent(qreal ax, qreal ay) const

{ return mapFromParent(QPointF(ax, ay));  }

inline QPointF QGraphicsItem::mapFromScene(qreal ax, qreal ay) const

{ return mapFromScene(QPointF(ax, ay));  }

inline QPolygonF QGraphicsItem::mapToItem(const QGraphicsItem *item, qreal ax, qreal ay, qreal w, qreal h) const

{ return mapToItem(item, QRectF(ax, ay, w, h)); }

inline QPolygonF QGraphicsItem::mapToParent(qreal ax, qreal ay, qreal w, qreal h) const

{ return mapToParent(QRectF(ax, ay, w, h)); }

inline QPolygonF QGraphicsItem::mapToScene(qreal ax, qreal ay, qreal w, qreal h) const

{ return mapToScene(QRectF(ax, ay, w, h)); }

inline QRectF QGraphicsItem::mapRectToItem(const QGraphicsItem *item, qreal ax, qreal ay, qreal w, qreal h) const

{ return mapRectToItem(item, QRectF(ax, ay, w, h)); }

inline QRectF QGraphicsItem::mapRectToParent(qreal ax, qreal ay, qreal w, qreal h) const

{ return mapRectToParent(QRectF(ax, ay, w, h)); }

inline QRectF QGraphicsItem::mapRectToScene(qreal ax, qreal ay, qreal w, qreal h) const

{ return mapRectToScene(QRectF(ax, ay, w, h)); }

inline QPolygonF QGraphicsItem::mapFromItem(const QGraphicsItem *item, qreal ax, qreal ay, qreal w, qreal h) const

{ return mapFromItem(item, QRectF(ax, ay, w, h)); }

inline QPolygonF QGraphicsItem::mapFromParent(qreal ax, qreal ay, qreal w, qreal h) const

{ return mapFromParent(QRectF(ax, ay, w, h)); }

inline QPolygonF QGraphicsItem::mapFromScene(qreal ax, qreal ay, qreal w, qreal h) const

{ return mapFromScene(QRectF(ax, ay, w, h)); }

inline QRectF QGraphicsItem::mapRectFromItem(const QGraphicsItem *item, qreal ax, qreal ay, qreal w, qreal h) const

{ return mapRectFromItem(item, QRectF(ax, ay, w, h)); }

inline QRectF QGraphicsItem::mapRectFromParent(qreal ax, qreal ay, qreal w, qreal h) const

{ return mapRectFromParent(QRectF(ax, ay, w, h)); }

inline QRectF QGraphicsItem::mapRectFromScene(qreal ax, qreal ay, qreal w, qreal h) const