|  | Home · Overviews · Examples

# QGraphicsItemInterface Class Reference
[com.trolltech.qt.gui module]

The `QGraphicsItem` class is the base class for all graphical items in a `QGraphicsScene`. More...

Inherited by `QAbstractGraphicsShapeItem`, `QGraphicsItem`, `QGraphicsItemGroup`, `QGraphicsLineItem`, `QGraphicsPixmapItem`, `QGraphicsSvgItem`, and `QGraphicsTextItem`.

## Detailed Description

The `QGraphicsItem` class is the base class for all graphical items in a `QGraphicsScene`.

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. `QGraphicsItem` is part of The Graphics View Framework

For convenience, Qt provides a set of standard graphics items for the most common shapes. These are:

- `QGraphicsEllipseItem` provides an ellipse item
- `QGraphicsLineItem` provides a line item
- `QGraphicsPathItem` provides an arbitrary path item
- `QGraphicsPixmapItem` provides a pixmap item
- `QGraphicsPolygonItem` provides a polygon item
- `QGraphicsRectItem` provides a rectangular item
- `QGraphicsSimpleTextItem` provides a simple text label item
- `QGraphicsTextItem` provides an advanced text browser item

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. {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:

        class SimpleItem : public QGraphicsItem
        {
        public:
            QRectF boundingRect() const
            {
                qreal penWidth = 1;
                return QRectF(-10 - penWidth / 2, -10 - penWidth / 2,
                              20 + penWidth / 2, 20 + penWidth / 2);
            }

            void paint(QPainter *painter, const QStyleOptionGraphicsItem *option,
                       QWidget *widget)
            {
                painter->drawRoundRect(-10, -10, 20, 20);
            }
        };

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:

1. 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.
2. Reimplement `collidesWithItem` to provide your own custom item and shape collision algorithm.

The `contains` function can be called to determine whether the item 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 parent coordinates (i.e., the parent's local coordinates). Parent items propagate both their position and their transformation to all children.

`QGraphicsItem` supports affine transformations in addition to its base position, `pos`. To change the item's transformation, you can either pass a transformation matrix to `setTransform`, or call one of the convenience functions `rotate`, `scale`, `translate`, or `shear`. 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`.

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.

`QGraphicsItem` receives events from `QGraphicsScene` through the virtual function `sceneEvent`. This function distributes the most common events to a set of convenience event handlers:

- `contextMenuEvent` handles context menu events
- `focusInEvent` and `focusOutEvent` handle focus in and out events
- `hoverEnterEvent`, `hoverMoveEvent`, and `hoverLeaveEvent` handles hover enter, move and leave events
- `inputMethodEvent` handles input events, for accessibility support
- `keyPressEvent` and `keyReleaseEvent` handle key press and release events
- `mousePressEvent`, `mouseMoveEvent`, `mouseReleaseEvent`, and `mouseDoubleClickEvent` handles mouse press, move, release, click and doubleclick events

You can filter events for any other item by installing event filters. This functionaly is separate from 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`.

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.

See also `QGraphicsScene`, `QGraphicsView`, and The Graphics View Framework.