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:

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:

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.


Copyright © 2008 Trolltech Trademarks
Qt Jambi 4.3.5_01