QGraphicsItem Class

Detailed Description

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 override
     {
         qreal penWidth = 1;
         return QRectF(-10 - penWidth / 2, -10 - penWidth / 2,
                       20 + penWidth, 20 + penWidth);
     }

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

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.

Transformations

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:

• The item's base transform is applied (transform())
• The item's transformations list is applied in order (transformations())
• The item is rotated relative to its transform origin point (rotation(), transformOriginPoint())
• The item is scaled relative to its transform origin point (scale(), transformOriginPoint())

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.

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.

This example shows the stacking order of all limbs of the robot from the 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:

• 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.
• You can call stackBefore() to reorder the list of children. This will directly modify the insertion order.
• You can set the ItemStacksBehindParent flag to stack a child item behind its parent.

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.

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:

• 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 double-click events

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().

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.

 class QGraphicsPathItem : public QAbstractGraphicsShapeItem
 {
  public:
   enum { Type = 2 };
     int type() const override { return Type; }
   ...
 };

 class CustomItem : public QGraphicsItem
 {
 public:
    enum { Type = UserType + 1 };

    int type() const override
    {
        // Enable the use of qgraphicsitem_cast with this item.
        return Type;
    }
    ...
 };