Logo Search packages:      
Sourcecode: qt4-x11 version File versions

QGraphicsItem Class Reference

Inheritance diagram for QGraphicsItem:

CustomItem CustomItem Mouse Node QAbstractGraphicsShapeItem QGraphicsItemGroup QGraphicsLineItem QGraphicsPixmapItem QGraphicsSvgItem QGraphicsTextItem QGraphicsWidget SimpleItem

List of all members.

Detailed Description

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



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:

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:


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.

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, {The Graphics View Framework}

Definition at line 87 of file qgraphicsitem.h.

void installSceneEventFilter (QGraphicsItem *filterItem)
virtual bool isObscuredBy (const QGraphicsItem *item) const
virtual QPainterPath opaqueArea () const
void removeSceneEventFilter (QGraphicsItem *filterItem)
void addToIndex ()
virtual void dragMoveEvent (QGraphicsSceneDragDropEvent *event)
virtual QVariant extension (const QVariant &variant) const
virtual void hoverMoveEvent (QGraphicsSceneHoverEvent *event)
void prepareGeometryChange ()
void removeFromIndex ()
virtual bool sceneEvent (QEvent *event)
virtual void setExtension (Extension extension, const QVariant &variant)
virtual bool supportsExtension (Extension extension) const
bool _qt_movableAncestorIsSelected (const QGraphicsItem *item)
QDebug operator<< (QDebug debug, QGraphicsItem::GraphicsItemChange change)
QDebug operator<< (QDebug debug, QGraphicsItem *item)
 QGraphicsEllipseItem (qreal x, qreal y, qreal width, qreal height, QGraphicsItem *parent)
qgraphicsitem_cast (QGraphicsItem *item)
 QGraphicsRectItem (qreal x, qreal y, qreal width, qreal height, QGraphicsItem *parent)
static void qt_graphicsItem_highlightSelected (QGraphicsItem *item, QPainter *painter, const QStyleOptionGraphicsItem *option)
void setShapeMode (ShapeMode mode)
static QRectF setupTextLayout (QTextLayout *layout)

Public Types

enum  { Type = 1, UserType = 65536 }
enum  CacheMode { NoCache, ItemCoordinateCache, DeviceCoordinateCache }
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,
enum  GraphicsItemFlag {
  ItemIsMovable = 0x1, ItemIsSelectable = 0x2, ItemIsFocusable = 0x4, ItemClipsToShape = 0x8,
  ItemClipsChildrenToShape = 0x10, ItemIgnoresTransformations = 0x20

Public Member Functions

bool acceptDrops () const
Qt::MouseButtons acceptedMouseButtons () const
bool acceptHoverEvents () const
bool acceptsHoverEvents () const
virtual void advance (int phase)
virtual QRectF boundingRect () const =0
QRegion boundingRegion (const QTransform &itemToDeviceTransform) const
qreal boundingRegionGranularity () const
CacheMode cacheMode () const
QList< QGraphicsItem * > childItems () const
QList< QGraphicsItem * > children () const
QRectF childrenBoundingRect () const
void clearFocus ()
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
QGraphicsItemcommonAncestorItem (const QGraphicsItem *other) const
virtual bool contains (const QPointF &point) const
QCursor cursor () const
QVariant data (int key) const
QTransform deviceTransform (const QTransform &viewportTransform) const
void ensureVisible (qreal x, qreal y, qreal w, qreal h, int xmargin=50, int ymargin=50)
void ensureVisible (const QRectF &rect=QRectF(), int xmargin=50, int ymargin=50)
GraphicsItemFlags flags () const
void grabKeyboard ()
void grabMouse ()
QGraphicsItemGroupgroup () const
bool handlesChildEvents () const
bool hasCursor () const
bool hasFocus () const
void hide ()
bool isAncestorOf (const QGraphicsItem *child) const
bool isEnabled () const
bool isObscured (qreal x, qreal y, qreal w, qreal h) const
bool isObscured (const QRectF &rect) const
bool isObscured () const
bool isSelected () const
bool isUnderMouse () const
bool isVisible () const
bool isVisibleTo (const QGraphicsItem *parent) const
bool isWidget () const
bool isWindow () const
QPolygonF mapFromItem (const QGraphicsItem *item, qreal x, qreal y, qreal w, qreal h) const
QPointF mapFromItem (const QGraphicsItem *item, qreal x, qreal y) const
QPainterPath mapFromItem (const QGraphicsItem *item, const QPainterPath &path) const
QPolygonF mapFromItem (const QGraphicsItem *item, const QPolygonF &polygon) const
QPolygonF mapFromItem (const QGraphicsItem *item, const QRectF &rect) const
QPointF mapFromItem (const QGraphicsItem *item, const QPointF &point) const
QPolygonF mapFromParent (qreal x, qreal y, qreal w, qreal h) const
QPointF mapFromParent (qreal x, qreal y) const
QPainterPath mapFromParent (const QPainterPath &path) const
QPolygonF mapFromParent (const QPolygonF &polygon) const
QPolygonF mapFromParent (const QRectF &rect) const
QPointF mapFromParent (const QPointF &point) const
QPolygonF mapFromScene (qreal x, qreal y, qreal w, qreal h) const
QPointF mapFromScene (qreal x, qreal y) const
QPainterPath mapFromScene (const QPainterPath &path) const
QPolygonF mapFromScene (const QPolygonF &polygon) const
QPolygonF mapFromScene (const QRectF &rect) const
QPointF mapFromScene (const QPointF &point) const
QPolygonF mapToItem (const QGraphicsItem *item, qreal x, qreal y, qreal w, qreal h) const
QPointF mapToItem (const QGraphicsItem *item, qreal x, qreal y) const
QPainterPath mapToItem (const QGraphicsItem *item, const QPainterPath &path) const
QPolygonF mapToItem (const QGraphicsItem *item, const QPolygonF &polygon) const
QPolygonF mapToItem (const QGraphicsItem *item, const QRectF &rect) const
QPointF mapToItem (const QGraphicsItem *item, const QPointF &point) const
QPolygonF mapToParent (qreal x, qreal y, qreal w, qreal h) const
QPointF mapToParent (qreal x, qreal y) const
QPainterPath mapToParent (const QPainterPath &path) const
QPolygonF mapToParent (const QPolygonF &polygon) const
QPolygonF mapToParent (const QRectF &rect) const
QPointF mapToParent (const QPointF &point) const
QPolygonF mapToScene (qreal x, qreal y, qreal w, qreal h) const
QPointF mapToScene (qreal x, qreal y) const
QPainterPath mapToScene (const QPainterPath &path) const
QPolygonF mapToScene (const QPolygonF &polygon) const
QPolygonF mapToScene (const QRectF &rect) const
QPointF mapToScene (const QPointF &point) const
QMatrix matrix () const
void moveBy (qreal dx, qreal dy)
virtual void paint (QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget=0)=0
QGraphicsItemparentItem () const
QGraphicsWidgetparentWidget () const
QPointF pos () const
 QGraphicsItem (QGraphicsItem *parent=0, QGraphicsScene *scene=0)
void resetMatrix ()
void resetTransform ()
void rotate (qreal angle)
void scale (qreal sx, qreal sy)
QGraphicsScenescene () const
QRectF sceneBoundingRect () const
QMatrix sceneMatrix () const
QPointF scenePos () const
QTransform sceneTransform () const
void scroll (qreal dx, qreal dy, const QRectF &rect=QRectF())
void setAcceptDrops (bool on)
void setAcceptedMouseButtons (Qt::MouseButtons buttons)
void setAcceptHoverEvents (bool enabled)
void setAcceptsHoverEvents (bool enabled)
void setBoundingRegionGranularity (qreal granularity)
void setCacheMode (CacheMode mode, const QSize &cacheSize=QSize())
void setCursor (const QCursor &cursor)
void setData (int key, const QVariant &value)
void setEnabled (bool enabled)
void setFlag (GraphicsItemFlag flag, bool enabled=true)
void setFlags (GraphicsItemFlags flags)
void setFocus (Qt::FocusReason focusReason=Qt::OtherFocusReason)
void setGroup (QGraphicsItemGroup *group)
void setHandlesChildEvents (bool enabled)
void setMatrix (const QMatrix &matrix, bool combine=false)
void setParentItem (QGraphicsItem *parent)
void setPos (qreal x, qreal y)
void setPos (const QPointF &pos)
void setSelected (bool selected)
void setToolTip (const QString &toolTip)
void setTransform (const QTransform &matrix, bool combine=false)
void setVisible (bool visible)
void setZValue (qreal z)
virtual QPainterPath shape () const
void shear (qreal sh, qreal sv)
void show ()
QString toolTip () const
QGraphicsItemtopLevelItem () const
QGraphicsWidgettopLevelWidget () const
QTransform transform () const
void translate (qreal dx, qreal dy)
virtual int type () const
void ungrabKeyboard ()
void ungrabMouse ()
void unsetCursor ()
void update (qreal x, qreal y, qreal width, qreal height)
void update (const QRectF &rect=QRectF())
QGraphicsWidgetwindow () const
qreal x () const
qreal y () const
qreal zValue () const
virtual ~QGraphicsItem ()

Protected Types

enum  Extension { UserExtension = 0x80000000 }

Protected Member Functions

virtual void contextMenuEvent (QGraphicsSceneContextMenuEvent *event)
virtual void dragEnterEvent (QGraphicsSceneDragDropEvent *event)
virtual void dragLeaveEvent (QGraphicsSceneDragDropEvent *event)
virtual void dropEvent (QGraphicsSceneDragDropEvent *event)
virtual void focusInEvent (QFocusEvent *event)
virtual void focusOutEvent (QFocusEvent *event)
virtual void hoverEnterEvent (QGraphicsSceneHoverEvent *event)
virtual void hoverLeaveEvent (QGraphicsSceneHoverEvent *event)
virtual void inputMethodEvent (QInputMethodEvent *event)
virtual QVariant inputMethodQuery (Qt::InputMethodQuery query) const
virtual QVariant itemChange (GraphicsItemChange change, const QVariant &value)
virtual void keyPressEvent (QKeyEvent *event)
virtual void keyReleaseEvent (QKeyEvent *event)
virtual void mouseDoubleClickEvent (QGraphicsSceneMouseEvent *event)
virtual void mouseMoveEvent (QGraphicsSceneMouseEvent *event)
virtual void mousePressEvent (QGraphicsSceneMouseEvent *event)
virtual void mouseReleaseEvent (QGraphicsSceneMouseEvent *event)
 QGraphicsItem (QGraphicsItemPrivate &dd, QGraphicsItem *parent, QGraphicsScene *scene)
virtual bool sceneEventFilter (QGraphicsItem *watched, QEvent *event)
virtual void wheelEvent (QGraphicsSceneWheelEvent *event)

Protected Attributes

QGraphicsItemPrivate * d_ptr


class ::tst_QGraphicsItem
class QGraphicsItemGroup
class QGraphicsScene
class QGraphicsSceneFindItemBspTreeVisitor
class QGraphicsScenePrivate
class QGraphicsView
class QGraphicsViewPrivate
class QGraphicsWidget
bool qt_closestItemFirst (const QGraphicsItem *, const QGraphicsItem *)
bool qt_closestLeaf (const QGraphicsItem *, const QGraphicsItem *)

The documentation for this class was generated from the following files:

Generated by  Doxygen 1.6.0   Back to index