CopperSpice API  1.9.1
QGraphicsScene Class Reference

Provides a surface for managing a large number of 2D graphical items. More...

Inheritance diagram for QGraphicsScene:
QObject

Public Typedefs

using SceneLayers = QFlags< SceneLayer >
 

Public Types

enum  ItemIndexMethod
 
enum  SceneLayer
 

Public Signals

void changed (const QList< QRectF > &region)
 
void focusItemChanged (QGraphicsItem *newFocus, QGraphicsItem *oldFocus, Qt::FocusReason reason)
 
void sceneRectChanged (const QRectF &rect)
 
void selectionChanged ()
 
- Public Signals inherited from QObject
void destroyed (QObject *obj=nullptr)
 
void objectNameChanged (const QString &objectName)
 

Public Slots

void advance ()
 
void clear ()
 
void clearSelection ()
 
void invalidate (const QRectF &rect=QRectF (), SceneLayers layers=AllLayers)
 
void update (const QRectF &rect=QRectF ())
 
- Public Slots inherited from QObject
void deleteLater ()
 

Public Methods

 QGraphicsScene (const QRectF &sceneRect, QObject *parent=nullptr)
 
 QGraphicsScene (QObject *parent=nullptr)
 
 QGraphicsScene (qreal x, qreal y, qreal width, qreal height, QObject *parent=nullptr)
 
virtual ~QGraphicsScene ()
 
QGraphicsItemactivePanel () const
 
QGraphicsWidgetactiveWindow () const
 
QGraphicsEllipseItemaddEllipse (const QRectF &rect, const QPen &pen=QPen (), const QBrush &brush=QBrush ())
 
QGraphicsEllipseItemaddEllipse (qreal x, qreal y, qreal w, qreal h, const QPen &pen=QPen (), const QBrush &brush=QBrush ())
 
void addItem (QGraphicsItem *item)
 
QGraphicsLineItemaddLine (const QLineF &line, const QPen &pen=QPen ())
 
QGraphicsLineItemaddLine (qreal x1, qreal y1, qreal x2, qreal y2, const QPen &pen=QPen ())
 
QGraphicsPathItemaddPath (const QPainterPath &path, const QPen &pen=QPen (), const QBrush &brush=QBrush ())
 
QGraphicsPixmapItemaddPixmap (const QPixmap &pixmap)
 
QGraphicsPolygonItemaddPolygon (const QPolygonF &polygon, const QPen &pen=QPen (), const QBrush &brush=QBrush ())
 
QGraphicsRectItemaddRect (const QRectF &rect, const QPen &pen=QPen (), const QBrush &brush=QBrush ())
 
QGraphicsRectItemaddRect (qreal x, qreal y, qreal w, qreal h, const QPen &pen=QPen (), const QBrush &brush=QBrush ())
 
QGraphicsSimpleTextItemaddSimpleText (const QString &text, const QFont &font=QFont ())
 
QGraphicsTextItemaddText (const QString &text, const QFont &font=QFont ())
 
QGraphicsProxyWidgetaddWidget (QWidget *widget, Qt::WindowFlags flags=Qt::EmptyFlag)
 
QBrush backgroundBrush () const
 
int bspTreeDepth () const
 
void clearFocus ()
 
QList< QGraphicsItem * > collidingItems (const QGraphicsItem *item, Qt::ItemSelectionMode mode=Qt::IntersectsItemShape) const
 
QGraphicsItemGroupcreateItemGroup (const QList< QGraphicsItem * > &items)
 
void destroyItemGroup (QGraphicsItemGroup *group)
 
QGraphicsItemfocusItem () const
 
QFont font () const
 
QBrush foregroundBrush () const
 
bool hasFocus () const
 
qreal height () const
 
virtual QVariant inputMethodQuery (Qt::InputMethodQuery query) const
 
void invalidate (qreal x, qreal y, qreal w, qreal h, SceneLayers layers=AllLayers)
 
bool isActive () const
 
QGraphicsItemitemAt (const QPointF &pos, const QTransform &deviceTransform) const
 
QGraphicsItemitemAt (qreal x, qreal y, const QTransform &deviceTransform) const
 
ItemIndexMethod itemIndexMethod () const
 
QList< QGraphicsItem * > items (const QPainterPath &path, Qt::ItemSelectionMode mode=Qt::IntersectsItemShape, Qt::SortOrder order=Qt::DescendingOrder, const QTransform &deviceTransform=QTransform ()) const
 
QList< QGraphicsItem * > items (const QPointF &pos, Qt::ItemSelectionMode mode=Qt::IntersectsItemShape, Qt::SortOrder order=Qt::DescendingOrder, const QTransform &deviceTransform=QTransform ()) const
 
QList< QGraphicsItem * > items (const QPolygonF &polygon, Qt::ItemSelectionMode mode=Qt::IntersectsItemShape, Qt::SortOrder order=Qt::DescendingOrder, const QTransform &deviceTransform=QTransform ()) const
 
QList< QGraphicsItem * > items (const QRectF &rect, Qt::ItemSelectionMode mode=Qt::IntersectsItemShape, Qt::SortOrder order=Qt::DescendingOrder, const QTransform &deviceTransform=QTransform ()) const
 
QList< QGraphicsItem * > items (qreal x, qreal y, qreal w, qreal h, Qt::ItemSelectionMode mode, Qt::SortOrder order, const QTransform &deviceTransform=QTransform ()) const
 
QList< QGraphicsItem * > items (Qt::SortOrder order=Qt::DescendingOrder) const
 
QRectF itemsBoundingRect () const
 
qreal minimumRenderSize () const
 
QGraphicsItemmouseGrabberItem () const
 
QPalette palette () const
 
void removeItem (QGraphicsItem *item)
 
void render (QPainter *painter, const QRectF &target=QRectF (), const QRectF &source=QRectF (), Qt::AspectRatioMode aspectRatioMode=Qt::KeepAspectRatio)
 
QRectF sceneRect () const
 
QList< QGraphicsItem * > selectedItems () const
 
QPainterPath selectionArea () const
 
bool sendEvent (QGraphicsItem *item, QEvent *event)
 
void setActivePanel (QGraphicsItem *item)
 
void setActiveWindow (QGraphicsWidget *widget)
 
void setBackgroundBrush (const QBrush &brush)
 
void setBspTreeDepth (int depth)
 
void setFocus (Qt::FocusReason focusReason=Qt::OtherFocusReason)
 
void setFocusItem (QGraphicsItem *item, Qt::FocusReason focusReason=Qt::OtherFocusReason)
 
void setFont (const QFont &font)
 
void setForegroundBrush (const QBrush &brush)
 
void setItemIndexMethod (ItemIndexMethod method)
 
void setMinimumRenderSize (qreal minSize)
 
void setPalette (const QPalette &palette)
 
void setSceneRect (const QRectF &rect)
 
void setSceneRect (qreal x, qreal y, qreal w, qreal h)
 
void setSelectionArea (const QPainterPath &path, const QTransform &deviceTransform)
 
void setSelectionArea (const QPainterPath &path, Qt::ItemSelectionOperation selectionOperation=Qt::ReplaceSelection, Qt::ItemSelectionMode mode=Qt::IntersectsItemShape, const QTransform &deviceTransform=QTransform ())
 
void setStickyFocus (bool enabled)
 
void setStyle (QStyle *style)
 
bool stickyFocus () const
 
QStylestyle () const
 
void update (qreal x, qreal y, qreal w, qreal h)
 
QList< QGraphicsView * > views () const
 
qreal width () const
 
- Public Methods inherited from QObject
 QObject (QObject *parent=nullptr)
 
 ~QObject ()
 
bool blockSignals (bool block)
 
const QList< QObject * > & children () const
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool disconnect (const QObject *receiver, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod, const QString &location, const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod=QString (), const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
void dumpObjectInfo ()
 
void dumpObjectTree ()
 
QList< QStringdynamicPropertyNames () const
 
template<typename T >
findChild (const QString &childName=QString ()) const
 
template<class T >
QList< T > findChildren (const QRegularExpression &regExp, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
template<class T >
QList< T > findChildren (const QString &childName=QString (), Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
bool inherits (const QString &className) const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const
 
bool isWindowType () const
 
void killTimer (int id)
 
const QMetaObjectmetaObject () const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const
 
QObject * parent () const
 
template<class T = QVariant>
property (const QString &name) const
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const QString &name, const QVariant &value)
 
bool signalsBlocked () const
 
int startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
 
QThreadthread () const
 

Protected Slots

bool focusNextPrevChild (bool next)
 

Protected Methods

virtual void contextMenuEvent (QGraphicsSceneContextMenuEvent *event)
 
virtual void dragEnterEvent (QGraphicsSceneDragDropEvent *event)
 
virtual void dragLeaveEvent (QGraphicsSceneDragDropEvent *event)
 
virtual void dragMoveEvent (QGraphicsSceneDragDropEvent *event)
 
virtual void drawBackground (QPainter *painter, const QRectF &rect)
 
virtual void drawForeground (QPainter *painter, const QRectF &rect)
 
virtual void drawItems (QPainter *painter, int numItems, QGraphicsItem *items[], const QStyleOptionGraphicsItem options[], QWidget *widget=nullptr)
 
virtual void dropEvent (QGraphicsSceneDragDropEvent *event)
 
bool event (QEvent *event) override
 
bool eventFilter (QObject *watched, QEvent *event) override
 
virtual void focusInEvent (QFocusEvent *event)
 
virtual void focusOutEvent (QFocusEvent *event)
 
virtual void helpEvent (QGraphicsSceneHelpEvent *event)
 
virtual void inputMethodEvent (QInputMethodEvent *event)
 
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)
 
virtual void wheelEvent (QGraphicsSceneWheelEvent *event)
 
- Protected Methods inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signalMethod) const
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signalMethod) const
 
bool isSignalConnected (const QMetaMethod &signalMethod) const
 
int receivers (const QString &signal) const
 
QObject * sender () const
 
int senderSignalIndex () const
 
virtual void timerEvent (QTimerEvent *event)
 

Properties

 backgroundBrush
 
 bspTreeDepth
 
 font
 
 foregroundBrush
 
 itemIndexMethod
 
 minimumRenderSize
 
 palette
 
 sceneRect
 
 stickyFocus
 
- Properties inherited from QObject
 objectName
 

Friends

class QGesture
 
class QGraphicsEffect
 
class QGraphicsItem
 
class QGraphicsObject
 
class QGraphicsView
 
class QGraphicsWidget
 

Additional Inherited Members

- Static Public Methods inherited from QObject
static bool connect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool connect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection, const QString &location=QString ())
 
static bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...), Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotLambda, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool disconnect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod)
 
static bool disconnect (const QObject *sender, std::nullptr_t, const QObject *receiver, std::nullptr_t)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...))
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, std::nullptr_t slotMethod=nullptr)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotMethod)
 
static QMetaObjectstaticMetaObject ()
 
static QString tr (const char *text, const char *comment=nullptr, std::optional< int > numArg=std::optional< int >())
 

Detailed Description

The QGraphicsScene class provides a surface for managing a large number of 2D graphical items. This class serves as a container for QGraphicsItems. It is used together with QGraphicsView for visualizing graphical items such as lines, rectangles, text, or even custom items, on a 2D surface.

QGraphicsScene provides functionality to efficiently determine both the location of items and what items are visible within an arbitrary area of the scene. With the QGraphicsView widget you can either visualize the whole scene or zoom in and view only parts of the scene. This class has no visual appearance of its own and only manages the items. You need to create a QGraphicsView widget to visualize the scene.

QGraphicsScene is part of the Graphics View System.

Adding Items to a Scene

To add items construct a QGraphicsScene object. Then either add the QGraphicsItem object by calling addItem() or call one of the following methods which all return a pointer to the newly added item. The dimensions of the items added with these methods are relative to the item's coordinate system, and the items position is initialized to (0, 0) in the scene.

scene.addText("Hello world");
QGraphicsView view(&scene);
view.show();

Items

QGraphicsScene uses an indexing algorithm to manage the location of items. A BSP (Binary Space Partitioning) tree is used which is an algorithm suitable for large scenes where most items remain static. You can choose to disable this index by calling setItemIndexMethod(). For more information about indexing algorithms refer to the itemIndexMethod property.

The scene's bounding rectangle is set by calling setSceneRect(). Items can be placed at any position on the scene and the size of the scene is by default unlimited. The scene rectangle is used only for internal bookkeeping and maintaining the scene's item index. If the scene rectangle is not set then QGraphicsScene will use the bounding area of all items as returned by itemsBoundingRect(). The method itemsBoundingRect() can be slow since it must collect positional information for every item on the scene. It is advisable to set a scene rectangle when the scene contains a large number of items.

The items() method can accommodate millions of items in the scene and determine the location of each one very quickly. The list of returned items will be sorted. The first element is drawn last since it is located in front of everything else.

The itemAt() method returns a single element at a given position. This is the item drawn in front of all others in the case of overlapping items.

QGraphicsScene is responsible for maintaining a list of selected items. To select items call setSelectionArea() and to clear the current selection call clearSelection(). The selectedItems() method is used to obtain the list of all selected items.

Event Handling and Propagation

QGraphicsView will send events to QGraphicsScene. The scene will then pass events to the appropriate event handler in QGraphicsItem. For example, when the user clicks a mouse button in a scene a mouse event will be delivered to the QGraphicsItem object corresponding to the item at that location.

To set which item in the scene has focus either call QGraphicsScene::setFocusItem() or QGraphicsItem::setFocus(). Calling QGraphicsScene::focusItem() will return which item currently has focus.

When a scene is constructed no item will have focus and the scene itself does not have focus. When an item in the scene gains focus the scene automatically gains focus. If the scene has focus the hasFocus() will return true and key press events will be passed to the QGraphicsItem which has focus.

QGraphicsScene also dispatches hover events. If an item accepts a hover event it will receive a GraphicsSceneHoverEnter event when the mouse is over the given item. As the mouse continues moving over the item QGraphicsScene will send GraphicsSceneHoverMove events. When the mouse leaves the item, a GraphicsSceneHoverLeave event is emitted.

See also
QGraphicsItem, QGraphicsView

Member Typedef Documentation

Member Enumeration Documentation

This enum describes the indexing algorithms QGraphicsScene provides for managing positional information about items on the scene.

ConstantValueDescription
QGraphicsScene::BspTreeIndex0 A Binary Space Partitioning tree is applied. All QGraphicsScene's item location algorithms are of an order close to logarithmic complexity, by making use of binary search. Adding, moving and removing items is logarithmic. This approach is best for static scenes where most items do not move.
QGraphicsScene::NoIndex-1No index is applied. Item location is of linear complexity, as all items on the scene are searched. Adding, moving and removing items, however, is done in constant time. This approach is ideal for dynamic scenes, where many items are added, moved or removed continuously.
See also
setItemIndexMethod(), bspTreeDepth

This enum describes the rendering layers in a QGraphicsScene. When QGraphicsScene draws the scene contents, it renders each of these layers separately, in order. Each layer represents a flag which can be OR'ed together when calling methods such as QGraphicsScene::invalidate() or QGraphicsView::invalidateScene().

ConstantValueDescription
QGraphicsScene::ItemLayer0x1 QGraphicsScene renders all items in this layer by calling drawItems(). Item layer is drawn after the background layer and before the foreground layer.
QGraphicsScene::BackgroundLayer0x2 QGraphicsScene renders the background in this layer by calling drawBackground(). Background layer is drawn before all other layers.
QGraphicsScene::ForegroundLayer0x4 QGraphicsScene renders the foreground in this layer by calling drawForeground(). Foreground layer is drawn after all other layers.
QGraphicsScene::AllLayers0xffff Represents a combination of all three layers.
See also
invalidate(), QGraphicsView::invalidateScene()

Constructor & Destructor Documentation

QGraphicsScene::QGraphicsScene ( QObject parent = nullptr)

Constructs a QGraphicsScene object. The parent is passed to the QObject constructor.

QGraphicsScene::QGraphicsScene ( const QRectF sceneRect,
QObject parent = nullptr 
)

Constructs a QGraphicsScene object using sceneRect for the scene rectangle. The parent is passed to the QObject constructor.

See also
sceneRect
QGraphicsScene::QGraphicsScene ( qreal  x,
qreal  y,
qreal  width,
qreal  height,
QObject parent = nullptr 
)

Constructs a QGraphicsScene object using the rectangle specified by (x, y), and the given width and height for its scene rectangle. The parent is passed to the QObject constructor.

See also
sceneRect
QGraphicsScene::~QGraphicsScene ( )
virtual

Removes and deletes all items from the scene object before destroying the scene object. The scene object is removed from the application global scene list and from all associated views.

Method Documentation

QGraphicsItem * QGraphicsScene::activePanel ( ) const

Returns the current active panel or a nullptr if no panel is currently active.

See also
QGraphicsScene::setActivePanel()
QGraphicsWidget * QGraphicsScene::activeWindow ( ) const

Returns the current active window or nullptr if no window is currently active.

See also
QGraphicsScene::setActiveWindow()
QGraphicsEllipseItem * QGraphicsScene::addEllipse ( const QRectF rect,
const QPen pen = QPen(),
const QBrush brush = QBrush() 
)

Creates and adds an ellipse item to the scene and returns a pointer to the new item. The geometry of the ellipse is defined by rect and is drawn using pen and brush. The item's geometry is provided in item coordinates and its position is initialized to (0, 0).

If the item is visible then QGraphicsScene will emit the changed() signal once control returns to the event loop.

See also
addLine(), addPath(), addPixmap(), addRect(), addText(), addItem(), addWidget()
QGraphicsEllipseItem * QGraphicsScene::addEllipse ( qreal  x,
qreal  y,
qreal  w,
qreal  h,
const QPen pen = QPen(),
const QBrush brush = QBrush() 
)
inline

Equivalent to calling addEllipse(QRectF(x, y, w, h), pen, brush).

void QGraphicsScene::addItem ( QGraphicsItem item)

Adds or moves the item and all its children to this scene. This scene takes ownership of the item. If the item is visible QGraphicsScene will emit changed() once control returns to the event loop. If the item is already in a different scene it will first be removed from the old scene and then added to this scene.

QGraphicsScene will send ItemSceneChange notifications to the given item when it is added to the scene. If the given item does not currently belong to a scene only one notification is sent. If it does belong to a scene QGraphicsScene will send an additional notification when the item is removed from its previous scene.

If all of these are true then the item will be activated.

  • item is a panel
  • current scene is active
  • no active panel in the scene
See also
removeItem(), addEllipse(), addLine(), addPath(), addPixmap(), addRect(), addText(), addWidget(), Sorting
QGraphicsLineItem * QGraphicsScene::addLine ( const QLineF line,
const QPen pen = QPen() 
)

Creates and adds a line item to the scene and returns a pointer to the new item. The geometry of the line is defined by line and is drawn using pen. The item's geometry is provided in item coordinates and the position is initialized to (0, 0).

If the item is visible QGraphicsScene will emit changed() once control returns to the event loop.

See also
addEllipse(), addPath(), addPixmap(), addRect(), addText(), addItem(), addWidget()
QGraphicsLineItem * QGraphicsScene::addLine ( qreal  x1,
qreal  y1,
qreal  x2,
qreal  y2,
const QPen pen = QPen() 
)
inline

Equivalent to calling addLine(QLineF(x1, y1, x2, y2), pen).

QGraphicsPathItem * QGraphicsScene::addPath ( const QPainterPath path,
const QPen pen = QPen(),
const QBrush brush = QBrush() 
)

Creates and adds a path item to the scene, and returns a pointer to the new item. The geometry of the path is defined by path and is drawn using pen and brush. The item's geometry is provided in item coordinates and its position is initialized to (0, 0).

If the item is visible QGraphicsScene will emit changed() once control returns to the event loop.

See also
addEllipse(), addLine(), addPixmap(), addRect(), addText(), addItem(), addWidget()
QGraphicsPixmapItem * QGraphicsScene::addPixmap ( const QPixmap pixmap)

Creates and adds the pixmap item to the scene and returns a pointer to the new item. The item's geometry is provided in item coordinates and its position is initialized to (0, 0).

If the item is visible QGraphicsScene will emit changed() once control returns to the event loop.

See also
addEllipse(), addLine(), addPath(), addRect(), addText(), addItem(), addWidget()
QGraphicsPolygonItem * QGraphicsScene::addPolygon ( const QPolygonF polygon,
const QPen pen = QPen(),
const QBrush brush = QBrush() 
)

Creates and adds a polygon item to the scene, and returns a pointer to the new item. The polygon is defined by polygon and is drawn using pen and brush. The item's geometry is provided in item coordinates and its position is initialized to (0, 0).

If the item is visible QGraphicsScene will emit changed() once control returns to the event loop.

See also
addEllipse(), addLine(), addPath(), addRect(), addText(), addItem(), addWidget()
QGraphicsRectItem * QGraphicsScene::addRect ( const QRectF rect,
const QPen pen = QPen(),
const QBrush brush = QBrush() 
)

Creates and adds a rectangle item to the scene and returns a pointer to the new item. The geometry of the rectangle is defined by rect and is drawn using pen and brush. The item's geometry is provided in item coordinates, and its position is initialized to (0, 0). For example, if a QRect(50, 50, 100, 100) is added the top-left corner will be at (50, 50) relative to the origin in the items coordinate system.

If the item is visible QGraphicsScene will emit changed() once control returns to the event loop.

See also
addEllipse(), addLine(), addPixmap(), addPixmap(), addText(), addItem(), addWidget()
QGraphicsRectItem * QGraphicsScene::addRect ( qreal  x,
qreal  y,
qreal  w,
qreal  h,
const QPen pen = QPen(),
const QBrush brush = QBrush() 
)
inline

Equivalent to calling addRect(QRectF(x, y, w, h), pen, brush).

QGraphicsSimpleTextItem * QGraphicsScene::addSimpleText ( const QString text,
const QFont font = QFont() 
)

Creates and adds a QGraphicsSimpleTextItem to the scene and returns a pointer to the new item. The text string is initialized to text and is drawn using font. The item's position is initialized to (0, 0).

If the item is visible QGraphicsScene will emit changed() once control returns to the event loop.

See also
addEllipse(), addLine(), addPixmap(), addPixmap(), addRect(), addItem(), addWidget()
QGraphicsTextItem * QGraphicsScene::addText ( const QString text,
const QFont font = QFont() 
)

Creates and adds a text item to the scene, and returns a pointer to the new item. The text string is initialized to text and is drawn using font. The item's position is initialized to (0, 0).

If the item is visible QGraphicsScene will emit changed() once control returns to the event loop.

See also
addEllipse(), addLine(), addPixmap(), addPixmap(), addRect(), addItem(), addWidget()
QGraphicsProxyWidget * QGraphicsScene::addWidget ( QWidget widget,
Qt::WindowFlags  flags = Qt::EmptyFlag 
)

Creates a new QGraphicsProxyWidget for widget, adds it to the scene, and then returns a pointer to the proxy. The value for flags sets the default window flags for the embedding proxy widget. The item's position is initialized to (0, 0). Widgets with the Qt::WA_PaintOnScreen widget attribute set and widgets which wrap an external application or controller are not supported.

If the item is visible QGraphicsScene will emit changed() once control returns to the event loop.

See also
addEllipse(), addLine(), addPixmap(), addPixmap(), addRect(), addText(), addSimpleText(), addItem()
void QGraphicsScene::advance ( )
slot

This slot advances the scene by one step by calling QGraphicsItem::advance() for all items on the scene. This is done in two phases. In the first phase all items are notified the scene is about to change. In the second phase all items are notified the items can move.

See also
QGraphicsItem::advance(), QGraphicsItemAnimation, QTimeLine
QBrush QGraphicsScene::backgroundBrush ( ) const

Returns the value of the backgroundBrush property.

int QGraphicsScene::bspTreeDepth ( ) const

Returns the value of the bspTreeDepth property.

void QGraphicsScene::changed ( const QList< QRectF > &  region)
signal

This signal is emitted by QGraphicsScene when control reaches the event loop if the scene content has changed. The region is a list of scene rectangles where the scene has changed.

See also
QGraphicsView::updateScene()
void QGraphicsScene::clear ( )
slot

Removes and deletes all items from the current scene. The properties of the scene are not changed.

See also
addItem()
void QGraphicsScene::clearFocus ( )

Clears focus from the scene. If any item has focus when this method is called it will lose focus and regain focus again once the scene regains focus. A scene which does not have focus ignores all key events.

See also
hasFocus(), setFocus(), setFocusItem()
void QGraphicsScene::clearSelection ( )
slot

Clears the current selection.

See also
setSelectionArea(), selectedItems()
QList< QGraphicsItem * > QGraphicsScene::collidingItems ( const QGraphicsItem item,
Qt::ItemSelectionMode  mode = Qt::IntersectsItemShape 
) const

Returns a list of all items which collide with item based on the given collision detection mode. Collisions are detected by calling QGraphicsItem::collidesWithItem(). The items are returned in order with the first element corresponding to the item in front.

See also
items(), itemAt(), QGraphicsItem::collidesWithItem(), Sorting
void QGraphicsScene::contextMenuEvent ( QGraphicsSceneContextMenuEvent event)
protectedvirtual

The event handler for the given event can be reimplemented in a subclass to receive context menu events. The default implementation forwards the event to the item in front which accepts context menu events at the position of the event. If no items accept context menu events at this position the event is ignored.

See also
QGraphicsItem::contextMenuEvent()
QGraphicsItemGroup * QGraphicsScene::createItemGroup ( const QList< QGraphicsItem * > &  items)

Groups all items into a new QGraphicsItemGroup and returns a pointer to the new group. The group is created with the common ancestor of items as its parent and with position (0, 0). The items become children of the new group. Their positions and transformations are mapped to the group. If items is empty this method will return an empty QGraphicsItemGroup.

QGraphicsScene has ownership of the group item so your code should not delete it. To remove the itmes from the group call destroyItemGroup().

See also
destroyItemGroup(), QGraphicsItemGroup::addToGroup()
void QGraphicsScene::destroyItemGroup ( QGraphicsItemGroup group)

Sets the parent for every item in group to the grand parent. Then the given group is removed from the scene and deleted. The items positions and transformations are mapped from the group to the grand parent.

See also
createItemGroup(), QGraphicsItemGroup::removeFromGroup()
void QGraphicsScene::dragEnterEvent ( QGraphicsSceneDragDropEvent event)
protectedvirtual

The event handler for the given event can be reimplemented in a subclass to receive drag enter events for the scene. The default implementation accepts the event and prepares the scene to accept drag move events.

See also
QGraphicsItem::dragEnterEvent(), dragMoveEvent(), dragLeaveEvent(), dropEvent()
void QGraphicsScene::dragLeaveEvent ( QGraphicsSceneDragDropEvent event)
protectedvirtual

The event handler for the given event can be reimplemented in a subclass to receive drag leave events for the scene.

See also
QGraphicsItem::dragLeaveEvent(), dragEnterEvent(), dragMoveEvent(), dropEvent()
void QGraphicsScene::dragMoveEvent ( QGraphicsSceneDragDropEvent event)
protectedvirtual

The event handler for the given event can be reimplemented in a subclass to receive drag move events for the scene.

See also
QGraphicsItem::dragMoveEvent(), dragEnterEvent(), dragLeaveEvent(), dropEvent()
void QGraphicsScene::drawBackground ( QPainter painter,
const QRectF rect 
)
protectedvirtual

Uses the given painter to draw the background of the scene before any items or the foreground are drawn. All painting is done in scene coordinates. The given rect is the region where the drawing occurs. Inherit QGraphicsScene and then reimplement this method to provide a custom background for the scene. If you only want to define a color, texture, or gradient for the background, then call setBackgroundBrush() instead of using this method.

See also
drawForeground(), drawItems()
void QGraphicsScene::drawForeground ( QPainter painter,
const QRectF rect 
)
protectedvirtual

Uses the given painter to draw the foreground of the scene after any items or the background are drawn. All painting is done in scene coordinates. The given rect is the region where the drawing occurs. Inherit QGraphicsScene and then reimplement this method to provide a custom foreground for the scene. If you only want to define a color, texture, or gradient for the foreground, then call setForegroundBrush() instead of using this method.

See also
drawBackground(), drawItems()
void QGraphicsScene::drawItems ( QPainter painter,
int  numItems,
QGraphicsItem items[],
const QStyleOptionGraphicsItem  options[],
QWidget widget = nullptr 
)
deprecatedprotectedvirtual
Deprecated:
Paints the given items using the provided painter, after the background has been drawn, and before the foreground has been drawn. All painting is done in scene coordinates. Before drawing each item, the painter must be transformed using QGraphicsItem::sceneTransform().

The options parameter is the list of style option objects for each item in items. The numItems parameter is the number of items in items and options in options. The widget parameter is optional; if specified, it should point to the widget that is being painted on.

The default implementation prepares the painter matrix, and calls QGraphicsItem::paint() on all items. Reimplement this function to provide custom painting of all items for the scene; gaining complete control over how each item is drawn. In some cases this can increase drawing performance significantly.

void CustomScene::drawItems(QPainter *painter, int numItems, QGraphicsItem *items[],
const QStyleOptionGraphicsItem options[], QWidget *widget)
{
for (int i = 0; i < numItems; ++i) {
// Draw the item
painter->save();
painter->setMatrix(items[i]->sceneMatrix(), true);
items[i]->paint(painter, &options[i], widget);
painter->restore();
}
}

This function is not called unless the QGraphicsView::IndirectPainting flag is given as an Optimization flag.

See also
drawBackground(), drawForeground()
void QGraphicsScene::dropEvent ( QGraphicsSceneDragDropEvent event)
protectedvirtual

The event handler for the given event can be reimplemented in a subclass to receive drop events for the scene.

See also
QGraphicsItem::dropEvent(), dragEnterEvent(), dragMoveEvent(), dragLeaveEvent()
bool QGraphicsScene::event ( QEvent event)
overrideprotectedvirtual

Processes the given event and dispatches it to the respective event handlers. In addition to calling the event handlers this method is responsible for converting mouse move events to hover events for when there is no mouse grabber item. Hover events are delivered directly to items.

QGraphicsScene does not have the methods enterEvent() and leaveEvent(). Override this method to handle these events.

See also
contextMenuEvent(), keyPressEvent(), keyReleaseEvent(), mousePressEvent(), mouseMoveEvent(), mouseReleaseEvent(), mouseDoubleClickEvent(), focusInEvent(), focusOutEvent()

Reimplemented from QObject::event()

bool QGraphicsScene::eventFilter ( QObject watched,
QEvent event 
)
overrideprotectedvirtual

QGraphicsScene filters QApplication's events to detect palette and font changes.

Reimplemented from QObject::eventFilter()

void QGraphicsScene::focusInEvent ( QFocusEvent event)
protectedvirtual

The event handler for the given event can be reimplemented to receive focus in events. The default implementation sets focus on the scene and then on the last focus item.

See also
QGraphicsItem::focusOutEvent()
QGraphicsItem * QGraphicsScene::focusItem ( ) const

When the scene is active this method returns the item which has keyboard focus or a nullptr if no item currently has focus. When the scene is inactive this methods returns the item which will gain input focus when the scene becomes active. The focus item receives keyboard input when the scene receives a key event.

See also
setFocusItem(), QGraphicsItem::hasFocus(), isActive()
void QGraphicsScene::focusItemChanged ( QGraphicsItem newFocus,
QGraphicsItem oldFocus,
Qt::FocusReason  reason 
)
signal

This signal is emitted any time focus changes in the scene. For example, when an item gains or loses input focus, or when focus passes from one item to another. You can connect to this signal to track when other items gain input focus. This can be useful when implementing virtual keyboards, input methods, and cursor items.

The value for oldFocus is a pointer to the item which previously had focus or a nullptr if no item had focus before the signal was emitted. The newFocus is a pointer to the item which has gained input focus or a nullptr if no item has focus. The value for reason indicates why the focus changed. For example, if the scene was deactivated while an input field had focus, oldFocus will point to the input field item, newFocus would be a nullptr, and the reason would be Qt::ActiveWindowFocusReason.

bool QGraphicsScene::focusNextPrevChild ( bool  next)
protectedslot

Changes keyboard focus to the next or previous item. Returns true if it can find a new widget or false if it can not. If next is true this method searches forward. If next is false, it searches backward.

Inherit from QGraphicsScene and reimplement this method to provide more control over how tab focus moves in your scene. The default implementation uses the QGraphicsWidget::setTabOrder().

void QGraphicsScene::focusOutEvent ( QFocusEvent event)
protectedvirtual

The event handler for the given event can be reimplemented in a subclass to receive focus out events. The default implementation clears the item which has focus then removes focus from the scene.

See also
QGraphicsItem::focusInEvent()
QFont QGraphicsScene::font ( ) const

Returns the value of the QGraphicsScene::font property.

QBrush QGraphicsScene::foregroundBrush ( ) const

Returns the value of the foregroundBrush property.

bool QGraphicsScene::hasFocus ( ) const

Returns true if the scene has focus, otherwise returns false. If the scene has focus it will forward key events from QKeyEvent to any item which has focus.

See also
setFocus(), setFocusItem()
qreal QGraphicsScene::height ( ) const
inline

Equivalent to calling sceneRect().height().

See also
width()
void QGraphicsScene::helpEvent ( QGraphicsSceneHelpEvent event)
protectedvirtual

This event handler for event can be reimplemented in a subclass to receive help events. The events are of type QEvent::ToolTip which are created when a tooltip is requested. The default implementation shows the tooltip of the item in front at the mouse cursor position. If no item at that position has a tooltip set this method does nothing.

See also
QGraphicsItem::toolTip(), QGraphicsSceneHelpEvent
void QGraphicsScene::inputMethodEvent ( QInputMethodEvent event)
protectedvirtual

This event handler for event can be reimplemented in a subclass to receive input method events for the scene. The default implementation forwards the event to the focusItem(). If no item currently has focus or the current focus item does not accept input methods then this method does nothing.

See also
QGraphicsItem::inputMethodEvent()
QVariant QGraphicsScene::inputMethodQuery ( Qt::InputMethodQuery  query) const
virtual

This method is used by input methods to query properties of the scene. The properties are used to support complex input method operations for surrounding text and reconversions. The value for query specifies which property is queried.

See also
QWidget::inputMethodQuery()
void QGraphicsScene::invalidate ( const QRectF rect = QRectF(),
SceneLayers  layers = AllLayers 
)
slot

Invalidates and schedules a redraw of the layers in rect on the scene. Any cached content in layers is unconditionally invalidated and redrawn. This method can be used to notify QGraphicsScene of changes to the background or the foreground. It is commonly used for scenes with tile-based backgrounds to notify changes when QGraphicsView has enabled CacheBackground.

QGraphicsView only supports caching the background layer. This method is equivalent to calling update() if any layer other than QGraphicsScene::BackgroundLayer is passed.

QRectF TileScene::rectForTile(int x, int y) const
{
// Return the rectangle for the tile at position (x, y).
return QRectF(x * tileWidth, y * tileHeight, tileWidth, tileHeight);
}
void TileScene::setTile(int x, int y, const QPixmap &pixmap)
{
// Sets or replaces the tile at position (x, y) with pixmap.
if (x >= 0 && x < numTilesH && y >= 0 && y < numTilesV) {
tiles[y][x] = pixmap;
invalidate(rectForTile(x, y), BackgroundLayer);
}
}
void TileScene::drawBackground(QPainter *painter, const QRectF &exposed)
{
// Draws all tiles that intersect the exposed area.
for (int y = 0; y < numTilesV; ++y) {
for (int x = 0; x < numTilesH; ++x) {
QRectF rect = rectForTile(x, y);
if (exposed.intersects(rect)) {
painter->drawPixmap(rect.topLeft(), tiles[y][x]);
}
}
}
}
See also
QGraphicsView::resetCachedContent()
void QGraphicsScene::invalidate ( qreal  x,
qreal  y,
qreal  w,
qreal  h,
SceneLayers  layers = AllLayers 
)
inline

Equivalent to calling invalidate(QRectF(x, y, w, h), layers).

bool QGraphicsScene::isActive ( ) const

Returns true if the scene is active otherwise returns false.

See also
QGraphicsItem::isActive(), QWidget::isActiveWindow()
QGraphicsItem * QGraphicsScene::itemAt ( const QPointF pos,
const QTransform deviceTransform 
) const

Returns the front most visible item at the specified pos or a nullptr if there are no visible items at this position. The deviceTransform is the transformation which applies to the view and needs to be provided if the scene contains items which ignore transformations.

See also
items(), collidingItems(), Sorting
QGraphicsItem * QGraphicsScene::itemAt ( qreal  x,
qreal  y,
const QTransform deviceTransform 
) const
inline

Returns the front most visible item at the position specified by (x, y) or a nullptr if there are no items at this position. The value for deviceTransform is the transformation which applies to the view and needs to be provided if the scene contains items which ignore transformations.

Equivalent to calling itemAt(QPointF(x, y), deviceTransform).

ItemIndexMethod QGraphicsScene::itemIndexMethod ( ) const

Returns the value of the itemIndexMethod property.

QList< QGraphicsItem * > QGraphicsScene::items ( const QPainterPath path,
Qt::ItemSelectionMode  mode = Qt::IntersectsItemShape,
Qt::SortOrder  order = Qt::DescendingOrder,
const QTransform deviceTransform = QTransform() 
) const

Returns all visible items matching the value of mode and the given path. Returns a list sorted using order. The default value for mode is Qt::IntersectsItemShape where all items whose exact shape intersects with or is contained by path are returned. The deviceTransform applies to the view and needs to be specified if the scene contains items which ignore transformations.

See also
itemAt(), Sorting
QList< QGraphicsItem * > QGraphicsScene::items ( const QPointF pos,
Qt::ItemSelectionMode  mode = Qt::IntersectsItemShape,
Qt::SortOrder  order = Qt::DescendingOrder,
const QTransform deviceTransform = QTransform() 
) const

Returns all visible items matching the value of mode and the given pos. Returns a list sorted using order. The default value for mode is Qt::IntersectsItemShape where all items whose exact shape intersects with or is contained by pos are returned. The deviceTransform applies to the view and needs to be specified if the scene contains items which ignore transformations.

See also
itemAt(), Sorting
QList< QGraphicsItem * > QGraphicsScene::items ( const QPolygonF polygon,
Qt::ItemSelectionMode  mode = Qt::IntersectsItemShape,
Qt::SortOrder  order = Qt::DescendingOrder,
const QTransform deviceTransform = QTransform() 
) const

Returns all visible items matching the value of mode and the given polygon. Returns a list sorted using order. The default value for mode is Qt::IntersectsItemShape where all items whose exact shape intersects with or is contained by polygon are returned. The deviceTransform applies to the view and needs to be specified if the scene contains items which ignore transformations.

See also
itemAt(), Sorting
QList< QGraphicsItem * > QGraphicsScene::items ( const QRectF rect,
Qt::ItemSelectionMode  mode = Qt::IntersectsItemShape,
Qt::SortOrder  order = Qt::DescendingOrder,
const QTransform deviceTransform = QTransform() 
) const

Returns all visible items matching the value of mode and the given rect. Returns a list sorted using order. The default value for mode is Qt::IntersectsItemShape where all items whose exact shape intersects with or is contained by rect are returned. The deviceTransform applies to the view and needs to be specified if the scene contains items which ignore transformations.

See also
itemAt(), Sorting
QList< QGraphicsItem * > QGraphicsScene::items ( qreal  x,
qreal  y,
qreal  w,
qreal  h,
Qt::ItemSelectionMode  mode,
Qt::SortOrder  order,
const QTransform deviceTransform = QTransform() 
) const
inline

Returns all visible items matching the value of mode and the rectangle defined by x, y, w and h. Returns a list sorted using order. The default value for mode is Qt::IntersectsItemShape where all items whose exact shape intersects with or is contained by the rectangle are returned. The deviceTransform applies to the view and needs to be specified if the scene contains items which ignore transformations.

QList< QGraphicsItem * > QGraphicsScene::items ( Qt::SortOrder  order = Qt::DescendingOrder) const

Returns a sorted list of all items in the scene. The given order defines which elements will appear first in the list.

See also
addItem(), removeItem(), Sorting
QRectF QGraphicsScene::itemsBoundingRect ( ) const

Calculates and returns the bounding rectangle of all items in the scene. This method works by iterating over all items and can be slow for large scenes.

See also
sceneRect()
void QGraphicsScene::keyPressEvent ( QKeyEvent event)
protectedvirtual

This event handler for event can be reimplemented in a subclass to receive key press events. The default implementation will forward the event to the item which has focus.

See also
QGraphicsItem::keyPressEvent(), focusItem()
void QGraphicsScene::keyReleaseEvent ( QKeyEvent event)
protectedvirtual

This event handler for event can be reimplemented in a subclass to receive key release events. The default implementation forwards the event to current focus item.

See also
QGraphicsItem::keyReleaseEvent(), focusItem()
qreal QGraphicsScene::minimumRenderSize ( ) const

Returns the value of the minimumRenderSize property.

void QGraphicsScene::mouseDoubleClickEvent ( QGraphicsSceneMouseEvent event)
protectedvirtual

This event handler for event can be reimplemented in a subclass to receive mouse doubleclick events. The default implementation is similar to mousePressEvent().

If a user doubleclicks on the scene multiple events are sent. The first will be a mouse press event followed by a release event. Then a doubleclick event and finally a second release event will be sent. If the doubleclick event is delivered to a different item than the one which received the first press and release it will be delivered as a press event. However, tripleclick events are not delivered as doubleclick events.

See also
QGraphicsItem::mousePressEvent(), QGraphicsItem::mouseMoveEvent(), QGraphicsItem::mouseReleaseEvent(), QGraphicsItem::setAcceptedMouseButtons()
QGraphicsItem * QGraphicsScene::mouseGrabberItem ( ) const

Returns the current mouse grabber item or a nullptr if no item is currently grabbing the mouse. The mouse grabber item is the item which receives all mouse events sent to the scene. If the item loses its mouse grab the scene will ignore all mouse events until a new item grabs the mouse.

An item becomes a mouse grabber when it receives and accepts a mouse press event and it continues to be the mouse grabber until one of the following events occur.

  • If the item receives a mouse release event when no other buttons are pressed
  • If the item becomes invisible or if it becomes disabled
  • If the item is removed from the scene
void QGraphicsScene::mouseMoveEvent ( QGraphicsSceneMouseEvent event)
protectedvirtual

This event handler for event can be reimplemented in a subclass to receive mouse move events for the scene.

The default implementation depends on the mouse grabber state. If there is a mouse grabber item the event is sent to the mouse grabber. If there are any items which accept hover events at the current position, the event is translated into a hover event and accepted, otherwise it is ignored.

See also
QGraphicsItem::mousePressEvent(), QGraphicsItem::mouseReleaseEvent(), QGraphicsItem::mouseDoubleClickEvent(), QGraphicsItem::setAcceptedMouseButtons()
void QGraphicsScene::mousePressEvent ( QGraphicsSceneMouseEvent event)
protectedvirtual

This event handler for event can be reimplemented in a subclass to receive mouse press events for the scene. If there is no item at the given position on the scene the selection area is reset. Any focus item loses its input focus and the event is then ignored.

The default implementation depends on the state of the scene. If there is a mouse grabber item then the event is sent to the mouse grabber. Otherwise, it is forwarded to the front item which accepts mouse events at the cursor position and this item becomes the mouse grabber item.

See also
QGraphicsItem::mousePressEvent(), QGraphicsItem::setAcceptedMouseButtons()
void QGraphicsScene::mouseReleaseEvent ( QGraphicsSceneMouseEvent event)
protectedvirtual

This event handler for event can be reimplemented in a subclass to receive mouse release events for the scene. The default implementation depends on the mouse grabber state. If there is no mouse grabber the event is ignored. Otherwise, the event is sent to the mouse grabber. If this mouse release represents the last pressed button on the mouse the mouse grabber item then loses the mouse grab.

See also
QGraphicsItem::mousePressEvent(), QGraphicsItem::mouseMoveEvent(), QGraphicsItem::mouseDoubleClickEvent(), QGraphicsItem::setAcceptedMouseButtons()
QPalette QGraphicsScene::palette ( ) const

Returns the value of the QGraphicsScene::palette property.

void QGraphicsScene::removeItem ( QGraphicsItem item)

Removes the item and all its children from the scene. The ownership of item is passed to the caller. This means the QGraphicsScene will no longer delete the given item when it is destroyed.

See also
addItem()
void QGraphicsScene::render ( QPainter painter,
const QRectF target = QRectF(),
const QRectF source = QRectF(),
Qt::AspectRatioMode  aspectRatioMode = Qt::KeepAspectRatio 
)

Renders the source rectangle from the current scene into the target rectangle using painter. This method is useful for rendering the contents of the scene onto a paint device, such as a QImage or for printing with QPrinter.

If source is a null rectangle this method will call sceneRect() to determine what to render. If target is a null rectangle the full dimensions of the QPainter device will be used. The source rectangle contents will be transformed according to aspectRatioMode to fit into the target rectangle. By default, the aspect ratio is kept and source is scaled to fit in target.

scene.addItem(...);
QPrinter printer(QPrinter::HighResolution);
printer.setPaperSize(QPrinter::A4);
QPainter painter(&printer);
scene.render(&painter);
See also
QGraphicsView::render()
QRectF QGraphicsScene::sceneRect ( ) const

Returns the value of the sceneRect property.

void QGraphicsScene::sceneRectChanged ( const QRectF rect)
signal

This signal is emitted by QGraphicsScene whenever the scene rectangle changes. The given rect is the new scene rectangle.

See also
QGraphicsView::updateSceneRect()
QList< QGraphicsItem * > QGraphicsScene::selectedItems ( ) const

Returns a list of all currently selected items. The items are returned in no particular order.

See also
setSelectionArea()
QPainterPath QGraphicsScene::selectionArea ( ) const

Returns the selection area which was previously set with setSelectionArea() or an empty QPainterPath if no selection area has been set.

See also
setSelectionArea()
void QGraphicsScene::selectionChanged ( )
signal

This signal is emitted by QGraphicsScene whenever the selection changes. Call selectedItems() to obtain the new list of selected items. The selection changes whenever an item is selected or unselected, a selection area is set, cleared, or otherwise changed. It also changes if a preselected item is added to the scene or if a selected item is removed from the scene.

QGraphicsScene emits this signal only once for group selection operations. For example, if you set a selection area, select or unselect a QGraphicsItemGroup, or add or remove an item which contains several selected children, this signal is emitted once.

See also
setSelectionArea(), selectedItems(), QGraphicsItem::setSelected()
bool QGraphicsScene::sendEvent ( QGraphicsItem item,
QEvent event 
)

Sends the given event to item using any installed event filters. The event is sent only if the item is enabled. Returns false if the event was filtered or if the item is disabled. Otherwise returns the value which was returned from the event handler.

See also
QGraphicsItem::sceneEvent(), QGraphicsItem::sceneEventFilter()
void QGraphicsScene::setActivePanel ( QGraphicsItem item)

Activates the item in this scene. If item is a nullptr then any currently active panel will be deactivated. If the scene is currently inactive item remains inactive until the scene becomes active.

See also
activePanel(), isActive(), QGraphicsItem::isActive()
void QGraphicsScene::setActiveWindow ( QGraphicsWidget widget)

Activates widget which must be a QGraphicsWidget in the current scene. If widget is a nullptr then QGraphicsScene will deactivate any currently active window.

See also
activeWindow(), QGraphicsWidget::isActiveWindow()
void QGraphicsScene::setBackgroundBrush ( const QBrush brush)

Sets the value of the backgroundBrush property to brush.

void QGraphicsScene::setBspTreeDepth ( int  depth)

Sets the value of the bspTreeDepth property to depth.

void QGraphicsScene::setFocus ( Qt::FocusReason  focusReason = Qt::OtherFocusReason)

Sets focus to the scene by sending a QFocusEvent and passing focusReason. If the scene regains focus after having previously lost focus while an item had focus, the last focus item will receive focus with focusReason as the reason. If the scene already has focus this method does nothing.

See also
hasFocus(), clearFocus(), setFocusItem()
void QGraphicsScene::setFocusItem ( QGraphicsItem item,
Qt::FocusReason  focusReason = Qt::OtherFocusReason 
)

Sets the focus in the current QGraphicsScene to item with the given focusReason. This happens after removing focus from any previous item. If the given item is a nullptr, does not accept focus, is not visible, or is not enabled, then this method only removes focus from any item which currently does have focus.

If item is not a nullptr and the scene does not currently have focus then this method will call QGraphicsScenesetFocus().

See also
focusItem(), hasFocus(), setFocus()
void QGraphicsScene::setFont ( const QFont font)

Sets the value of the QGraphicsScene::font property to font.

void QGraphicsScene::setForegroundBrush ( const QBrush brush)

Sets the value of the foregroundBrush property to brush.

void QGraphicsScene::setItemIndexMethod ( ItemIndexMethod  method)

Sets the value of the itemIndexMethod property to method.

void QGraphicsScene::setMinimumRenderSize ( qreal  minSize)

Sets the value of the minimumRenderSize property to minSize.

void QGraphicsScene::setPalette ( const QPalette palette)

Sets the value of the QGraphicsScene::palette property to palette.

void QGraphicsScene::setSceneRect ( const QRectF rect)

Sets the value of the sceneRect property to rect.

void QGraphicsScene::setSceneRect ( qreal  x,
qreal  y,
qreal  w,
qreal  h 
)
inline

Sets the value of the sceneRect property to x, y, w, h.

void QGraphicsScene::setSelectionArea ( const QPainterPath path,
const QTransform deviceTransform 
)

Sets the selection area to path. All items within this area are immediately selected and all items outside are unselected. The list of all selected items can be retrieved by calling selectedItems(). The deviceTransform is the transformation which applies to the view and needs to be provided if the scene contains items which ignore transformations. For an item to be selected it must be marked as selectable using QGraphicsItem::ItemIsSelectable.

See also
clearSelection(), selectionArea()
void QGraphicsScene::setSelectionArea ( const QPainterPath path,
Qt::ItemSelectionOperation  selectionOperation = Qt::ReplaceSelection,
Qt::ItemSelectionMode  mode = Qt::IntersectsItemShape,
const QTransform deviceTransform = QTransform() 
)

Sets the selection area to path using mode to determine if items are included in the selection area. The selectionOperation determines what to do with the currently selected items. The deviceTransform is the transformation which applies to the view and needs to be provided if the scene contains items which ignore transformations.

See also
clearSelection(), selectionArea()
void QGraphicsScene::setStickyFocus ( bool  enabled)

Sets the value of the stickyFocus property to enabled.

void QGraphicsScene::setStyle ( QStyle style)

Sets or replaces the style of the scene and makes the style a child of this scene. Any previously assigned style is deleted. The initial style is obtained by calling QApplication::style(). Changing the style, either directly by calling this method or indirectly by calling QApplication::setStyle(), will automatically update the style for all widgets which do not have a style explicitly assigned.

If style is a nullptr QGraphicsScene will revert to QApplication::style().

See also
style()
bool QGraphicsScene::stickyFocus ( ) const

Returns the value of the stickyFocus property.

QStyle * QGraphicsScene::style ( ) const

Returns the style for this scene. If the scene has not been explicitly assigned a style, the initial style is obtained by calling QApplication::style().

See also
setStyle()
void QGraphicsScene::update ( const QRectF rect = QRectF())
slot

Schedules a redraw of the given rect in the scene.

See also
sceneRect(), changed()
void QGraphicsScene::update ( qreal  x,
qreal  y,
qreal  w,
qreal  h 
)
inline

Equivalent to calling update(QRectF(x, y, w, h));

QList< QGraphicsView * > QGraphicsScene::views ( ) const

Returns a list of all the views which display this scene.

See also
QGraphicsView::scene()
void QGraphicsScene::wheelEvent ( QGraphicsSceneWheelEvent event)
protectedvirtual

This event handler for event can be reimplemented in a subclass to receive mouse wheel events. By default, the event is delivered to the front item under the cursor. If the event is ignored it will be passed to the next item and so on, until the event is accepted or it reaches the background of the scene. If no items accept the event it is ignored.

See also
QGraphicsItem::wheelEvent()
qreal QGraphicsScene::width ( ) const
inline

Equivalent to calling sceneRect().width().

See also
height()

Property Documentation

QGraphicsScene::backgroundBrush

This property holds the background brush of the scene. Set this property to changes the scene's background to a different color, gradient or texture. The default background brush is Qt::NoBrush. The background is drawn behind all items. QGraphicsScene::render() calls drawBackground() to draw the scene background.

For more detailed control over how the background is drawn reimplement drawBackground() in a subclass of QGraphicsScene.

QGraphicsView view(&scene);
view.show();
// blue background
scene.setBackgroundBrush(Qt::blue);
// gradient background
QRadialGradient gradient(0, 0, 10);
gradient.setSpread(QGradient::RepeatSpread);
scene.setBackgroundBrush(gradient);
PropertiesClass Methods
read backgroundBrush
write setBackgroundBrush
QGraphicsScene::bspTreeDepth

This property holds the depth of the QGraphicsScene BSP index tree. This tree depth has no effect on the scene when the property itemIndexMethod is set to ItemIndexMethod::NoIndex. The depth affects the performance and memory usage of the index, which will grow exponentially as the depth of the tree increases.

By default the value of this property is 0. When this property is 0 a default depth will be chosen based on the size, location, and number of items in the scene. If the items change frequently you may experience some lag as QGraphicsScene recalculates the depth. To avoid this lag set the tree depth explicitly.

The depth of the tree and the size of the scene rectangle decide the granularity of the scene's partitioning. The size of each scene segment is determined by the following algorithm. The BSP tree has an optimal size when each segment contains between 0 and 10 items.

QSizeF segmentSize = sceneRect().size() / pow(2, depth - 1);
See also
itemIndexMethod
PropertiesClass Methods
read bspTreeDepth
write setBspTreeDepth
QGraphicsScene::font

This property holds the default font for the scene. The scene font defaults to QApplication::font.

If the font changes, either directly by calling setFont() or indirectly when the application font changes, QGraphicsScene first sends itself a FontChange event. Then it sends FontChange events to all top level widget items in the scene. Changing the scene font automatically schedules a redraw of the entire scene.

See also
style(), palette, QWidget::font, QApplication::setFont()
PropertiesClass Methods
read font
write setFont
QGraphicsScene::foregroundBrush

This property holds the foreground brush of the scene. Change this property to set the foreground to a different color, gradient, or texture. The foreground is drawn in front of the items. The default foreground brush is Qt::NoBrush.

For more detailed control over how the foreground is drawn, reimplement the drawForeground() method in a QGraphicsScene subclass.

QGraphicsView view(&scene);
view.show();
// white semi-transparent foreground
scene.setForegroundBrush(QColor(255, 255, 255, 127));
// grid foreground
scene.setForegroundBrush(QBrush(Qt::lightGray, Qt::CrossPattern));
PropertiesClass Methods
read foregroundBrush
write setForegroundBrush
QGraphicsScene::itemIndexMethod

This property holds the item indexing method. QGraphicsScene applies an indexing algorithm to the scene, to speed up item discovery methods like items() and itemAt(). Indexing is most efficient for static scenes. For dynamic scenes or scenes with lots of animated items the index overhead can outweigh the fast lookup speeds.

The default index method BspTreeIndex works fine for most applications. If your scene uses lots of animations and you are experiencing some degradation in speed, you can disable indexing by calling setItemIndexMethod(NoIndex).

See also
bspTreeDepth
PropertiesClass Methods
read itemIndexMethod
write setItemIndexMethod
QGraphicsScene::minimumRenderSize

When the scene is rendered any item whose width or height is smaller than the value of this property will not be rendered. If an item is not rendered and the QGrapicsItem::ItemClipsChildrenToShape flag is set then child items will also not be rendered. The default value is 0. If not set, set to 0, or a negative value, all items will always be rendered.

Adjust this value to speed up rendering of scenes which contain lots of small items. Items which are not drawn as a result of being too small are still returned by methods such as items() and itemAt() and participate in collision detection and interactions. Setting the minimumRenderSize() to a value less than 2 may avoid large unrendered items.

See also
QStyleOptionGraphicsItem::levelOfDetailFromTransform()
PropertiesClass Methods
read minimumRenderSize
write setMinimumRenderSize
QGraphicsScene::palette

This property holds the default palette for the scene. The scene palette default is QApplication::palette.

If the palette changes, either directly by calling setPalette() or indirectly when the application palette changes, QGraphicsScene first sends itself a PaletteChange event. Then it sends PaletteChange events to all top level widget items in the scene. Changing the scene palette automatically schedules a redraw of the entire scene.

See also
style(), font, QWidget::palette, QApplication::setPalette()
PropertiesClass Methods
read palette
write setPalette
QGraphicsScene::sceneRect

This property holds the bounding rectangle of the scene. The sceneRect property is primarily used by QGraphicsView to determine the view's default scrollable area and by QGraphicsScene to manage item indexing.

If this property is not set or set to a null QRectF the sceneRect() method will return the largest bounding rectangle of all items which have ever been added to the scene.

See also
width(), height(), QGraphicsView::sceneRect
PropertiesClass Methods
read sceneRect
write setSceneRect
QGraphicsScene::stickyFocus

This property holds whether clicking on the scene background will clear focus. In a QGraphicsScene with a value of stickyFocus set to true, the item with focus will retain focus when the user clicks on the background. Focus will also be retained when an item does not accept focus. If stickyFocus is set to false any mouse click will clear focus. By default this property is false.

Reimplement mousePressEvent() in a subclass of QGraphicsScene to toggle this property based on where the user has clicked.

See also
clearFocus(), setFocusItem()
PropertiesClass Methods
read stickyFocus
write setStickyFocus