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

Public Types | Public Member Functions | Protected Types | Protected Member Functions | Protected Attributes | Friends | Related Functions

QGraphicsItem Class Reference

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

Inheritance diagram for QGraphicsItem:
Inheritance graph
Collaboration diagram for QGraphicsItem:
Collaboration graph

List of all members.

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,
  ItemZValueHasChanged, ItemOpacityChange, ItemOpacityHasChanged
enum  GraphicsItemFlag {
  ItemIsMovable = 0x1, ItemIsSelectable = 0x2, ItemIsFocusable = 0x4, ItemClipsToShape = 0x8,
  ItemClipsChildrenToShape = 0x10, ItemIgnoresTransformations = 0x20, ItemIgnoresParentOpacity = 0x40, ItemDoesntPropagateOpacityToChildren = 0x80,
  ItemStacksBehindParent = 0x100

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 ()
QPainterPath clipPath () const
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
qreal effectiveOpacity () 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 ()
void installSceneEventFilter (QGraphicsItem *filterItem)
bool isAncestorOf (const QGraphicsItem *child) const
bool isClipped () const
bool isEnabled () const
bool isObscured () const
bool isObscured (const QRectF &rect) const
bool isObscured (qreal x, qreal y, qreal w, qreal h) const
virtual bool isObscuredBy (const QGraphicsItem *item) const
bool isSelected () const
bool isUnderMouse () const
bool isVisible () const
bool isVisibleTo (const QGraphicsItem *parent) const
bool isWidget () const
bool isWindow () const
QTransform itemTransform (const QGraphicsItem *other, bool *ok=0) const
QPolygonF mapFromItem (const QGraphicsItem *item, const QPolygonF &polygon) const
QPainterPath mapFromItem (const QGraphicsItem *item, const QPainterPath &path) const
QPointF mapFromItem (const QGraphicsItem *item, qreal x, qreal y) const
QPolygonF mapFromItem (const QGraphicsItem *item, qreal x, qreal y, qreal w, qreal h) const
QPointF mapFromItem (const QGraphicsItem *item, const QPointF &point) const
QPolygonF mapFromItem (const QGraphicsItem *item, const QRectF &rect) const
QPolygonF mapFromParent (const QPolygonF &polygon) const
QPainterPath mapFromParent (const QPainterPath &path) const
QPointF mapFromParent (qreal x, qreal y) const
QPolygonF mapFromParent (qreal x, qreal y, qreal w, qreal h) const
QPointF mapFromParent (const QPointF &point) const
QPolygonF mapFromParent (const QRectF &rect) const
QPolygonF mapFromScene (const QPolygonF &polygon) const
QPainterPath mapFromScene (const QPainterPath &path) const
QPolygonF mapFromScene (qreal x, qreal y, qreal w, qreal h) const
QPointF mapFromScene (qreal x, qreal y) const
QPointF mapFromScene (const QPointF &point) const
QPolygonF mapFromScene (const QRectF &rect) const
QRectF mapRectFromItem (const QGraphicsItem *item, qreal x, qreal y, qreal w, qreal h) const
QRectF mapRectFromItem (const QGraphicsItem *item, const QRectF &rect) const
QRectF mapRectFromParent (qreal x, qreal y, qreal w, qreal h) const
QRectF mapRectFromParent (const QRectF &rect) const
QRectF mapRectFromScene (const QRectF &rect) const
QRectF mapRectFromScene (qreal x, qreal y, qreal w, qreal h) const
QRectF mapRectToItem (const QGraphicsItem *item, qreal x, qreal y, qreal w, qreal h) const
QRectF mapRectToItem (const QGraphicsItem *item, const QRectF &rect) const
QRectF mapRectToParent (qreal x, qreal y, qreal w, qreal h) const
QRectF mapRectToParent (const QRectF &rect) const
QRectF mapRectToScene (qreal x, qreal y, qreal w, qreal h) const
QRectF mapRectToScene (const QRectF &rect) const
QPointF mapToItem (const QGraphicsItem *item, qreal x, qreal y) const
QPolygonF mapToItem (const QGraphicsItem *item, qreal x, qreal y, qreal w, qreal h) const
QPointF mapToItem (const QGraphicsItem *item, const QPointF &point) const
QPolygonF mapToItem (const QGraphicsItem *item, const QRectF &rect) const
QPolygonF mapToItem (const QGraphicsItem *item, const QPolygonF &polygon) const
QPainterPath mapToItem (const QGraphicsItem *item, const QPainterPath &path) const
QPolygonF mapToParent (qreal x, qreal y, qreal w, qreal h) const
QPointF mapToParent (qreal x, qreal y) const
QPointF mapToParent (const QPointF &point) const
QPolygonF mapToParent (const QRectF &rect) const
QPolygonF mapToParent (const QPolygonF &polygon) const
QPainterPath mapToParent (const QPainterPath &path) const
QPolygonF mapToScene (const QRectF &rect) const
QPointF mapToScene (qreal x, qreal y) const
QPainterPath mapToScene (const QPainterPath &path) const
QPolygonF mapToScene (qreal x, qreal y, qreal w, qreal h) const
QPolygonF mapToScene (const QPolygonF &polygon) const
QPointF mapToScene (const QPointF &point) const
QMatrix matrix () const
void moveBy (qreal dx, qreal dy)
qreal opacity () const
virtual QPainterPath opaqueArea () const
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 removeSceneEventFilter (QGraphicsItem *filterItem)
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 setOpacity (qreal opacity)
void setParentItem (QGraphicsItem *parent)
void setPos (const QPointF &pos)
void setPos (qreal x, qreal y)
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 (const QRectF &rect=QRectF())
void update (qreal x, qreal y, qreal width, qreal height)
QGraphicsWidgetwindow () const
qreal x () const
qreal y () const
qreal zValue () const
virtual ~QGraphicsItem ()

Protected Types

enum  Extension { UserExtension = 0x80000000 }

Protected Member Functions

void addToIndex ()
virtual void contextMenuEvent (QGraphicsSceneContextMenuEvent *event)
virtual void dragEnterEvent (QGraphicsSceneDragDropEvent *event)
virtual void dragLeaveEvent (QGraphicsSceneDragDropEvent *event)
virtual void dragMoveEvent (QGraphicsSceneDragDropEvent *event)
virtual void dropEvent (QGraphicsSceneDragDropEvent *event)
virtual QVariant extension (const QVariant &variant) const
virtual void focusInEvent (QFocusEvent *event)
virtual void focusOutEvent (QFocusEvent *event)
virtual void hoverEnterEvent (QGraphicsSceneHoverEvent *event)
virtual void hoverLeaveEvent (QGraphicsSceneHoverEvent *event)
virtual void hoverMoveEvent (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)
void prepareGeometryChange ()
 QGraphicsItem (QGraphicsItemPrivate &dd, QGraphicsItem *parent, QGraphicsScene *scene)
void removeFromIndex ()
virtual bool sceneEvent (QEvent *event)
virtual bool sceneEventFilter (QGraphicsItem *watched, QEvent *event)
virtual void setExtension (Extension extension, const QVariant &variant)
virtual bool supportsExtension (Extension extension) const
virtual void wheelEvent (QGraphicsSceneWheelEvent *event)

Protected Attributes



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

Related Functions

(Note that these are not member functions.)

qgraphicsitem_cast (QGraphicsItem *item)

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:

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 85 of file qgraphicsitem.h.

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

Generated by  Doxygen 1.6.0   Back to index