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

**

** Copyright (C) 2010 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$

**

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

/*!

    \class QGraphicsItem

    \brief The QGraphicsItem class is the base class for all graphical

    items in a QGraphicsScene.

    \since 4.2

    \ingroup graphicsview-api

    It provides a light-weight foundation for writing your own custom items.

    This includes defining the item's geometry, collision detection, its

    painting implementation and item interaction through its event handlers.

    \image graphicsview-items.png

    For convenience, Qt provides a set of standard graphics items for the most

    common shapes. These are:

    \list

    \o QGraphicsEllipseItem provides an ellipse item

    \o QGraphicsLineItem provides a line item

    \o QGraphicsPathItem provides an arbitrary path item

    \o QGraphicsPixmapItem provides a pixmap item

    \o QGraphicsPolygonItem provides a polygon item

    \o QGraphicsRectItem provides a rectangular item

    \o QGraphicsSimpleTextItem provides a simple text label item

    \o QGraphicsTextItem provides an advanced text browser item

    \endlist

    All of an item's geometric information is based on its local coordinate

    system. The item's position, pos(), is the only function that does not

    operate in local coordinates, as it returns a position in parent

    coordinates. \l {The Graphics View Coordinate System} describes the coordinate

    system in detail.

    You can set whether an item should be visible (i.e., drawn, and accepting

    events), by calling setVisible(). Hiding an item will also hide its

    children. Similarly, you can enable or disable an item by calling

    setEnabled(). If you disable an item, all its children will also be

    disabled. By default, items are both visible and enabled. To toggle

    whether an item is selected or not, first enable selection by setting

    the ItemIsSelectable flag, and then call setSelected(). Normally,

    selection is toggled by the scene, as a result of user interaction.

    To write your own graphics item, you first create a subclass of

    QGraphicsItem, and then start by implementing its two pure virtual public

    functions: boundingRect(), which returns an estimate of the area painted

    by the item, and paint(), which implements the actual painting. For

    example:

    \snippet doc/src/snippets/code/src_gui_graphicsview_qgraphicsitem.cpp 0

    The boundingRect() function has many different purposes.

    QGraphicsScene bases its item index on boundingRect(), and

    QGraphicsView uses it both for culling invisible items, and for

    determining the area that needs to be recomposed when drawing

    overlapping items. In addition, QGraphicsItem's collision

    detection mechanisms use boundingRect() to provide an efficient

    cut-off. The fine grained collision algorithm in

    collidesWithItem() is based on calling shape(), which returns an

    accurate outline of the item's shape as a QPainterPath.

    QGraphicsScene expects all items boundingRect() and shape() to

    remain unchanged unless it is notified. If you want to change an

    item's geometry in any way, you must first call

    prepareGeometryChange() to allow QGraphicsScene to update its

    bookkeeping.

    Collision detection can be done in two ways:

    \list 1

    \o Reimplement shape() to return an accurate shape for your item,

    and rely on the default implementation of collidesWithItem() to do

    shape-shape intersection. This can be rather expensive if the

    shapes are complex.

    \o Reimplement collidesWithItem() to provide your own custom item

    and shape collision algorithm.

    \endlist

    The contains() function can be called to determine whether the item \e

    contains a point or not. This function can also be reimplemented by the

    item. The default behavior of contains() is based on calling shape().

    Items can contain other items, and also be contained by other items. All

    items can have a parent item and a list of children. Unless the item has

    no parent, its position is in \e parent coordinates (i.e., the parent's

    local coordinates). Parent items propagate both their position and their

    transformation to all children.

    \img graphicsview-parentchild.png

    \section1 Transformation

    QGraphicsItem supports projective transformations in addition to its base

    position, pos(). There are several ways to change an item's transformation.

    For simple transformations, you can call either of the convenience

    functions setRotation() or setScale(), or you can pass any transformation

    matrix to setTransform(). For advanced transformation control you also have

    the option of setting several combined transformations by calling

    setTransformations().

    Item transformations accumulate from parent to child, so if both a parent

    and child item are rotated 90 degrees, the child's total transformation

    will be 180 degrees. Similarly, if the item's parent is scaled to 2x its

    original size, its children will also be twice as large. An item's

    transformation does not affect its own local geometry; all geometry

    functions (e.g., contains(), update(), and all the mapping functions) still

    operate in local coordinates. For convenience, QGraphicsItem provides the

    functions sceneTransform(), which returns the item's total transformation

    matrix (including its position and all parents' positions and

    transformations), and scenePos(), which returns its position in scene

    coordinates. To reset an item's matrix, call resetTransform().

    Certain transformation operations produce a different outcome depending on

    the order in which they are applied. For example, if you scale an

    transform, and then rotate it, you may get a different result than if the

    transform was rotated first. However, the order you set the transformation

    properties on QGraphicsItem does not affect the resulting transformation;

    QGraphicsItem always applies the properties in a fixed, defined order:

    \list

    \o The item's base transform is applied (transform())

    \o The item's transformations list is applied in order (transformations())

    \o The item is rotated relative to its transform origin point (rotation(), transformOriginPoint())

    \o The item is scaled relative to its transform origin point (scale(), transformOriginPoint())

    \endlist

    \section1 Painting

    The paint() function is called by QGraphicsView to paint the item's

    contents. The item has no background or default fill of its own; whatever

    is behind the item will shine through all areas that are not explicitly

    painted in this function.  You can call update() to schedule a repaint,

    optionally passing the rectangle that needs a repaint. Depending on

    whether or not the item is visible in a view, the item may or may not be

    repainted; there is no equivalent to QWidget::repaint() in QGraphicsItem.

    Items are painted by the view, starting with the parent items and then

    drawing children, in ascending stacking order. You can set an item's

    stacking order by calling setZValue(), and test it by calling

    zValue(), where items with low z-values are painted before items with

    high z-values. Stacking order applies to sibling items; parents are always

    drawn before their children.

    \section1 Sorting

    All items are drawn in a defined, stable order, and this same order decides

    which items will receive mouse input first when you click on the scene.

    Normally you don't have to worry about sorting, as the items follow a

    "natural order", following the logical structure of the scene.

    An item's children are stacked on top of the parent, and sibling items are

    stacked by insertion order (i.e., in the same order that they were either

    added to the scene, or added to the same parent). If you add item A, and

    then B, then B will be on top of A. If you then add C, the items' stacking

    order will be A, then B, then C.

    \image graphicsview-zorder.png

    This example shows the stacking order of all limbs of the robot from the

    \l{graphicsview/dragdroprobot}{Drag and Drop Robot} example. The torso is

    the root item (all other items are children or descendants of the torso),

    so it is drawn first. Next, the head is drawn, as it is the first item in

    the torso's list of children. Then the upper left arm is drawn. As the

    lower arm is a child of the upper arm, the lower arm is then drawn,

    followed by the upper arm's next sibling, which is the upper right arm, and

    so on.

    For advanced users, there are ways to alter how your items are sorted:

    \list

    \o You can call setZValue() on an item to explicitly stack it on top of, or

    under, other sibling items. The default Z value for an item is 0. Items

    with the same Z value are stacked by insertion order.

    \o You can call stackBefore() to reorder the list of children. This will

    directly modify the insertion order.

    \o You can set the ItemStacksBehindParent flag to stack a child item behind

    its parent.

    \endlist

    The stacking order of two sibling items also counts for each item's

    children and descendant items. So if one item is on top of another, then

    all its children will also be on top of all the other item's children as

    well.

    \section1 Events

    QGraphicsItem receives events from QGraphicsScene through the virtual

    function sceneEvent(). This function distributes the most common events

    to a set of convenience event handlers:

    \list

    \o contextMenuEvent() handles context menu events

    \o focusInEvent() and focusOutEvent() handle focus in and out events

    \o hoverEnterEvent(), hoverMoveEvent(), and hoverLeaveEvent() handles

    hover enter, move and leave events

    \o inputMethodEvent() handles input events, for accessibility support

    \o keyPressEvent() and keyReleaseEvent() handle key press and release events

    \o mousePressEvent(), mouseMoveEvent(), mouseReleaseEvent(), and

    mouseDoubleClickEvent() handles mouse press, move, release, click and

    doubleclick events

    \endlist

    You can filter events for any other item by installing event filters. This

    functionality is separate from Qt's regular event filters (see

    QObject::installEventFilter()), which only work on subclasses of QObject. After

    installing your item as an event filter for another item by calling

    installSceneEventFilter(), the filtered events will be received by the virtual

    function sceneEventFilter(). You can remove item event filters by calling

    removeSceneEventFilter().

    \section1 Custom Data

    Sometimes it's useful to register custom data with an item, be it a custom

    item, or a standard item. You can call setData() on any item to store data

    in it using a key-value pair (the key being an integer, and the value is a

    QVariant). To get custom data from an item, call data(). This

    functionality is completely untouched by Qt itself; it is provided for the

    user's convenience.

*/

/*!

    \variable QGraphicsItem::Type

    The type value returned by the virtual type() function in standard

    graphics item classes in Qt. All such standard graphics item

    classes in Qt are associated with a unique value for Type,

    e.g. the value returned by QGraphicsPathItem::type() is 2.

    \snippet doc/src/snippets/code/src_gui_graphicsview_qgraphicsitem.cpp 18

*/

/*!

    \variable QGraphicsItem::UserType

    The lowest permitted type value for custom items (subclasses

    of QGraphicsItem or any of the standard items). This value is

    used in conjunction with a reimplementation of QGraphicsItem::type()

    and declaring a Type enum value. Example:

    \snippet doc/src/snippets/code/src_gui_graphicsview_qgraphicsitem.cpp 1

    \note UserType = 65536

*/

/*!

    \enum QGraphicsItem::GraphicsItemFlag

    This enum describes different flags that you can set on an item to

    toggle different features in the item's behavior.

    All flags are disabled by default.

    \value ItemIsMovable The item supports interactive movement using

    the mouse. By clicking on the item and then dragging, the item

    will move together with the mouse cursor. If the item has

    children, all children are also moved. If the item is part of a

    selection, all selected items are also moved. This feature is

    provided as a convenience through the base implementation of

    QGraphicsItem's mouse event handlers.

    \value ItemIsSelectable The item supports selection. Enabling this

    feature will enable setSelected() to toggle selection for the

    item. It will also let the item be selected automatically as a

    result of calling QGraphicsScene::setSelectionArea(), by clicking

    on an item, or by using rubber band selection in QGraphicsView.

    \value ItemIsFocusable The item supports keyboard input focus (i.e., it is

    an input item). Enabling this flag will allow the item to accept focus,

    which again allows the delivery of key events to

    QGraphicsItem::keyPressEvent() and QGraphicsItem::keyReleaseEvent().

    \value ItemClipsToShape The item clips to its own shape. The item cannot

    draw or receive mouse, tablet, drag and drop or hover events outside its

    shape. It is disabled by default. This behavior is enforced by

    QGraphicsView::drawItems() or QGraphicsScene::drawItems(). This flag was

    introduced in Qt 4.3.

    \value ItemClipsChildrenToShape The item clips the painting of all its

    descendants to its own shape. Items that are either direct or indirect

    children of this item cannot draw outside this item's shape. By default,

    this flag is disabled; children can draw anywhere. This behavior is

    enforced by QGraphicsView::drawItems() or

    QGraphicsScene::drawItems(). This flag was introduced in Qt 4.3.

    \value ItemIgnoresTransformations The item ignores inherited

    transformations (i.e., its position is still anchored to its parent, but

    the parent or view rotation, zoom or shear transformations are ignored).

    This flag is useful for keeping text label items horizontal and unscaled,

    so they will still be readable if the view is transformed.  When set, the

    item's view geometry and scene geometry will be maintained separately. You

    must call deviceTransform() to map coordinates and detect collisions in

    the view. By default, this flag is disabled. This flag was introduced in

    Qt 4.3. \note With this flag set you can still scale the item itself, and

    that scale transformation will influence the item's children.

    \value ItemIgnoresParentOpacity The item ignores its parent's opacity. The

    item's effective opacity is the same as its own; it does not combine with

    the parent's opacity. This flags allows your item to keep its absolute

    opacity even if the parent is semitransparent. This flag was introduced in

    Qt 4.5.

    \value ItemDoesntPropagateOpacityToChildren The item doesn't propagate its

    opacity to its children. This flag allows you to create a semitransparent

    item that does not affect the opacity of its children. This flag was

    introduced in Qt 4.5.

    \value ItemStacksBehindParent The item is stacked behind its parent. By

    default, child items are stacked on top of the parent item. But setting

    this flag, the child will be stacked behind it. This flag is useful for

    drop shadow effects and for decoration objects that follow the parent

    item's geometry without drawing on top of it. This flag was introduced

    in Qt 4.5.

    \value ItemUsesExtendedStyleOption The item makes use of either

    \l{QStyleOptionGraphicsItem::} {exposedRect} or

    \l{QStyleOptionGraphicsItem::} {matrix} in

    QStyleOptionGraphicsItem. By default, the

    \l{QStyleOptionGraphicsItem::} {exposedRect} is initialized to the

    item's boundingRect() and the

    \l{QStyleOptionGraphicsItem::}{matrix} is untransformed.  You can

    enable this flag for the style options to be set up with more

    fine-grained values.  Note that

    QStyleOptionGraphicsItem::levelOfDetail is unaffected by this flag

    and always initialized to 1. Use

    QStyleOptionGraphicsItem::levelOfDetailFromTransform() if you need

    a higher value. This flag was introduced in Qt 4.6.

    \value ItemHasNoContents The item does not paint anything (i.e., calling

    paint() on the item has no effect). You should set this flag on items that

    do not need to be painted to ensure that Graphics View avoids unnecessary

    painting preparations. This flag was introduced in Qt 4.6.

    \value ItemSendsGeometryChanges The item enables itemChange()

    notifications for ItemPositionChange, ItemPositionHasChanged,

    performance reasons, these notifications are disabled by default. You must

    enable this flag to receive notifications for position and transform

    changes. This flag was introduced in Qt 4.6.

    \value ItemAcceptsInputMethod The item supports input methods typically

    used for Asian languages.

    This flag was introduced in Qt 4.6.

    \value ItemNegativeZStacksBehindParent The item automatically

    stacks behind it's parent if it's z-value is negative. This flag

    enables setZValue() to toggle ItemStacksBehindParent. This flag

    was introduced in Qt 4.6.

    \value ItemIsPanel The item is a panel. A panel provides activation and

    contained focus handling. Only one panel can be active at a time (see

    QGraphicsItem::isActive()). When no panel is active, QGraphicsScene

    activates all non-panel items. Window items (i.e.,

    QGraphicsItem::isWindow() returns true) are panels. This flag was

    introduced in Qt 4.6.

    \omitvalue ItemIsFocusScope \omit Internal only (for now). \endomit

    \value ItemSendsScenePositionChanges The item enables itemChange()

    notifications for ItemScenePositionHasChanged. For performance reasons,

    these notifications are disabled by default. You must enable this flag

    to receive notifications for scene position changes. This flag was

    introduced in Qt 4.6.

*/

/*!

    \enum QGraphicsItem::GraphicsItemChange

    This enum describes the state changes that are notified by

    QGraphicsItem::itemChange(). The notifications are sent as the state

    changes, and in some cases, adjustments can be made (see the documentation

    for each change for details).

    Note: Be careful with calling functions on the QGraphicsItem itself inside

    itemChange(), as certain function calls can lead to unwanted

    recursion. For example, you cannot call setPos() in itemChange() on an

    ItemPositionChange notification, as the setPos() function will again call

    itemChange(ItemPositionChange). Instead, you can return the new, adjusted

    position from itemChange().

    \value ItemEnabledChange The item's enabled state changes. If the item is

    presently enabled, it will become disabled, and vice verca. The value

    argument is the new enabled state (i.e., true or false). Do not call

    setEnabled() in itemChange() as this notification is delivered. Instead,

    you can return the new state from itemChange().

    \value ItemEnabledHasChanged The item's enabled state has changed. The

    value argument is the new enabled state (i.e., true or false). Do not call

    setEnabled() in itemChange() as this notification is delivered. The return

    value is ignored.

    \value ItemMatrixChange The item's affine transformation matrix is

    changing. This value is obsolete; you can use ItemTransformChange instead.

    \value ItemPositionChange The item's position changes. This notification

    is sent if the ItemSendsGeometryChanges flag is enabled, and when the

    item's local position changes, relative to its parent (i.e., as a result

    of calling setPos() or moveBy()). The value argument is the new position

    (i.e., a QPointF).  You can call pos() to get the original position. Do

    not call setPos() or moveBy() in itemChange() as this notification is

    delivered; instead, you can return the new, adjusted position from

    itemChange(). After this notification, QGraphicsItem immediately sends the

    ItemPositionHasChanged notification if the position changed.

    \value ItemPositionHasChanged The item's position has changed. This

    notification is sent if the ItemSendsGeometryChanges flag is enabled, and

    after the item's local position, relative to its parent, has changed. The

    value argument is the new position (the same as pos()), and QGraphicsItem

    ignores the return value for this notification (i.e., a read-only

    notification).

    \value ItemTransformChange The item's transformation matrix changes. This

    notification is send if the ItemSendsGeometryChanges flag is enabled, and

    when the item's local transformation matrix changes (i.e., as a result of

    calling setTransform(). The value argument is the new matrix (i.e., a

    QTransform); to get the old matrix, call transform(). Do not call

    setTransform() or set any of the transformation properties in itemChange()

    as this notification is delivered; instead, you can return the new matrix

    from itemChange().  This notification is not sent if you change the

    transformation properties.

    \value ItemTransformHasChanged The item's transformation matrix has

    changed either because setTransform is called, or one of the

    transformation properties is changed. This notification is sent if the

    ItemSendsGeometryChanges flag is enabled, and after the item's local

    transformation matrix has changed. The value argument is the new matrix

    (same as transform()), and QGraphicsItem ignores the return value for this

    notification (i.e., a read-only notification).