Skip to content

PythonQt.QtGui.QGraphicsScene

QGraphicsScene

PythonQtInstanceWrapper object

Native bases: PythonQtInstanceWrapper

Supplemental documentation: Qt 5 reference:

Detailed Description

The 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 is part of the Graphics View Framework.

QGraphicsScene also provides functionality that lets you efficiently determine both the location of items, and for determining what items are visible within an arbitrary area on the scene. With the QGraphicsView widget, you can either visualize the whole scene, or zoom in and view only parts of the scene.

Example:

QGraphicsScene scene;
scene.addText("Hello, world!");

QGraphicsView view(&scene);
view.show();

Note that QGraphicsScene has no visual appearance of its own; it only manages the items. You need to create a QGraphicsView widget to visualize the scene.

To add items to a scene, you start off by constructing a QGraphicsScene object. Then, you have two options: either add your existing QGraphicsItem objects by calling addItem(), or you can call one of the convenience functions addEllipse(), addLine(), addPath(), addPixmap(), addPolygon(), addRect(), or addText(), which all return a pointer to the newly added item. The dimensions of the items added with these functions are relative to the item's coordinate system, and the items position is initialized to (0, 0) in the scene.

You can then visualize the scene using QGraphicsView. When the scene changes, (e.g., when an item moves or is transformed) QGraphicsScene emits the changed() signal. To remove an item, call removeItem().

QGraphicsScene uses an indexing algorithm to manage the location of items efficiently. By default, a BSP (Binary Space Partitioning) tree is used; an algorithm suitable for large scenes where most items remain static (i.e., do not move around). You can choose to disable this index by calling setItemIndexMethod(). For more information about the available indexing algorithms, see the itemIndexMethod property.

The scene's bounding rect 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 rect is used only for internal bookkeeping, maintaining the scene's item index. If the scene rect is unset, QGraphicsScene will use the bounding area of all items, as returned by itemsBoundingRect(), as the scene rect. However, itemsBoundingRect() is a relatively time consuming function, as it operates by collecting positional information for every item on the scene. Because of this, you should always set the scene rect when operating on large scenes.

One of QGraphicsScene's greatest strengths is its ability to efficiently determine the location of items. Even with millions of items on the scene, the items() functions can determine the location of an item within a few milliseconds. There are several overloads to items(): one that finds items at a certain position, one that finds items inside or intersecting with a polygon or a rectangle, and more. The list of returned items is sorted by stacking order, with the topmost item being the first item in the list. For convenience, there is also an itemAt() function that returns the topmost item at a given position.

QGraphicsScene maintains selection information for the scene. To select items, call setSelectionArea(), and to clear the current selection, call clearSelection(). Call selectedItems() to get the list of all selected items.

Event Handling and Propagation

Another responsibility that QGraphicsScene has, is to propagate events from QGraphicsView. To send an event to a scene, you construct an event that inherits QEvent, and then send it using, for example, QCoreApplication::sendEvent(). event() is responsible for dispatching the event to the individual items. Some common events are handled by convenience event handlers. For example, key press events are handled by keyPressEvent(), and mouse press events are handled by mousePressEvent().

Key events are delivered to the focus item. To set the focus item, you can either call setFocusItem(), passing an item that accepts focus, or the item itself can call QGraphicsItem::setFocus(). Call focusItem() to get the current focus item. For compatibility with widgets, the scene also maintains its own focus information. By default, the scene does not have focus, and all key events are discarded. If setFocus() is called, or if an item on the scene gains focus, the scene automatically gains focus. If the scene has focus, hasFocus() will return true, and key events will be forwarded to the focus item, if any. If the scene loses focus, (i.e., someone calls clearFocus()) while an item has focus, the scene will maintain its item focus information, and once the scene regains focus, it will make sure the last focus item regains focus.

For mouse-over effects, QGraphicsScene dispatches hover events. If an item accepts hover events (see QGraphicsItem::acceptHoverEvents()), it will receive a GraphicsSceneHoverEnter event when the mouse enters its area. As the mouse continues moving inside the item's area, QGraphicsScene will send it GraphicsSceneHoverMove events. When the mouse leaves the item's area, the item will receive a GraphicsSceneHoverLeave event.

All mouse events are delivered to the current mouse grabber item. An item becomes the scene's mouse grabber if it accepts mouse events (see QGraphicsItem::acceptedMouseButtons()) and it receives a mouse press. It stays the mouse grabber until it receives a mouse release when no other mouse buttons are pressed. You can call mouseGrabberItem() to determine what item is currently grabbing the mouse.

Source: https://doc.qt.io/archives/qt-5.15/qgraphicsscene.html

Complete member index

Every captured member retains its own identity. Identical captured declaration text is linked once; this does not establish native inheritance or interchangeable objects.

Member Kind Signature Summary
AllLayers attribute Any
BackgroundLayer attribute Any
BspTreeIndex attribute Any
ForegroundLayer attribute Any
ItemIndexMethod attribute type Convert a number or string to an integer, or return 0 if no arguments are given.
ItemLayer attribute Any
NoIndex attribute Any
SceneLayer attribute type Convert a number or string to an integer, or return 0 if no arguments are given.
SceneLayers attribute type Convert a number or string to an integer, or return 0 if no arguments are given.
__init__ function (self, *args: Any, **kwargs: Any) -> None Native constructor; consult class documentation for supported overloads. (shared captured text)
activePanel function (self) -> Any X.activePanel() -> PythonQt.QtGui.QGraphicsItem
activeWindow function (self) -> Any X.activeWindow() -> PythonQt.QtGui.QGraphicsWidget
addEllipse function (self, x: Any, y: Any, w: Any, h: Any, pen: Any, brush: Any) -> Any X.addEllipse(x, y, w, h, pen, brush) -> PythonQt.QtGui.QGraphicsEllipseItem
addItem function (self, item: Any) -> None Adds or moves the item and all its children to this scene.
addLine function (self, x1: Any, y1: Any, x2: Any, y2: Any, pen: Any) -> Any X.addLine(x1, y1, x2, y2, pen) -> PythonQt.QtGui.QGraphicsLineItem
addPath function (self, path: Any, pen: Any, brush: Any) -> Any X.addPath(path, pen, brush) -> PythonQt.QtGui.QGraphicsPathItem
addPixmap function (self, pixmap: Any) -> Any X.addPixmap(pixmap) -> PythonQt.QtGui.QGraphicsPixmapItem
addPolygon function (self, polygon: Any, pen: Any, brush: Any) -> Any X.addPolygon(polygon, pen, brush) -> PythonQt.QtGui.QGraphicsPolygonItem
addRect function (self, x: Any, y: Any, w: Any, h: Any, pen: Any, brush: Any) -> Any X.addRect(x, y, w, h, pen, brush) -> PythonQt.QtGui.QGraphicsRectItem
addSimpleText function (self, text: str, font: Any) -> Any X.addSimpleText(text, font) -> PythonQt.QtGui.QGraphicsSimpleTextItem
addText function (self, text: str, font: Any) -> Any X.addText(text, font) -> PythonQt.QtGui.QGraphicsTextItem
addWidget function (self, widget: Any, wFlags: Any) -> Any X.addWidget(widget, wFlags) -> PythonQt.QtGui.QGraphicsProxyWidget
advance function (self) -> None This slot advances the scene by one step, by calling [QGraphicsItem::advance](https://doc.qt.io/archives/qt-5.15/qgraphicsitem.html#advance)() for all items on the scene.
backgroundBrush attribute QBrush This property holds the background brush of the scene.
blockSignals function (self, b: Any) -> bool X.blockSignals(b) -> bool (shared captured text)
bspTreeDepth attribute int This property holds the depth of [QGraphicsScene](https://doc.qt.io/archives/qt-5.15/qgraphicsscene.html)'s BSP index tree
changed function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.QtGui.QGraphicsScene.changed; argument details are not documented.
childEvent function (self, event: Any) -> Any (shared captured text)
children function (self) -> tuple X.children() -> tuple (shared captured text)
className function (self, *args: Any, **kwargs: Any) -> Any Return the classname of the object (shared captured text)
clear function (self) -> None Removes and deletes all items from the scene, but otherwise leaves the state of the scene unchanged.
clearFocus function (self) -> None Clears focus from the scene.
clearSelection function (self) -> None Clears the current selection.
collidingItems function (self, item: Any, mode: Any) -> tuple X.collidingItems(item, mode) -> tuple
connect function (self, signal: Any, receiver: Any, slot: Any, type: Any) -> bool X.connect(signal, receiver, slot, type) -> bool (shared captured text)
contextMenuEvent function (self, event: Any) -> None This event handler, for event contextMenuEvent, can be reimplemented in a subclass to receive context menu events.
createItemGroup function (self, items: Any) -> Any X.createItemGroup(items) -> PythonQt.QtGui.QGraphicsItemGroup
customEvent function (self, event: Any) -> Any (shared captured text)
delete function (self, *args: Any, **kwargs: Any) -> Any Deletes the C++ object (at your own risk, my friend!) (shared captured text)
deleteLater function (self) -> Any (shared captured text)
destroyItemGroup function (self, group: Any) -> None Reparents all items in group to group's parent item, then removes group from the scene, and finally deletes it.
destroyed function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.QtGui.QGraphicsScene.destroyed; argument details are not documented.
disconnect function (self, signal: Any, receiver: Any, slot: Any) -> bool X.disconnect(signal, receiver, slot) -> bool (shared captured text)
dragEnterEvent function (self, event: Any) -> None This event handler, for event event, can be reimplemented in a subclass to receive drag enter events for the scene.
dragLeaveEvent function (self, event: Any) -> None This event handler, for event event, can be reimplemented in a subclass to receive drag leave events for the scene.
dragMoveEvent function (self, event: Any) -> None This event handler, for event event, can be reimplemented in a subclass to receive drag move events for the scene.
drawBackground function (self, painter: Any, rect: Any) -> None X.drawBackground(painter, rect)
drawForeground function (self, painter: Any, rect: Any) -> None X.drawForeground(painter, rect)
drawItems function (self, painter: Any, numItems: Any, items: Any, options: Any, widget: Any) -> Any X.drawItems(painter, numItems, items, options, widget)
dropEvent function (self, event: Any) -> None This event handler, for event event, can be reimplemented in a subclass to receive drop events for the scene.
dumpObjectInfo function (self) -> Any (shared captured text)
dumpObjectTree function (self) -> Any (shared captured text)
dynamicPropertyNames function (self) -> Any (shared captured text)
event function (self, event: Any) -> bool X.event(event) -> bool
eventFilter function (self, watched: Any, event: Any) -> bool X.eventFilter(watched, event) -> bool
findChild function (self, type: Any, name: Any) -> Any X.findChild(type, name) -> PythonQt.private.QObject (shared captured text)
findChildren function (self, type: Any, name: Any) -> tuple X.findChildren(type, name) -> tuple (shared captured text)
focusInEvent function (self, event: Any) -> None This event handler, for event focusEvent, can be reimplemented in a subclass to receive focus in events.
focusItem function (self) -> Any X.focusItem() -> PythonQt.QtGui.QGraphicsItem
focusItemChanged function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.QtGui.QGraphicsScene.focusItemChanged; argument details are not documented.
focusOnTouch attribute bool This property holds whether items gain focus when receiving a touch begin event.
focusOutEvent function (self, event: Any) -> None This event handler, for event focusEvent, can be reimplemented in a subclass to receive focus out events.
font attribute QFont This property holds the scene's default font
foregroundBrush attribute QBrush This property holds the foreground brush of the scene.
hasFocus function (self) -> bool X.hasFocus() -> bool
height function (self) -> float X.height() -> float
help function (self, *args: Any, **kwargs: Any) -> Any Shows the help of available methods for this class (shared captured text)
helpEvent function (self, event: Any) -> None This event handler, for event helpEvent, can be reimplemented in a subclass to receive help events.
inherits function (self, *args: Any, **kwargs: Any) -> Any Returns if the class inherits or is of given type name (shared captured text)
inputMethodEvent function (self, event: Any) -> None This event handler, for event event, can be reimplemented in a subclass to receive input method events for the scene.
inputMethodQuery function (self, query: Any) -> Any X.inputMethodQuery(query) -> object
installEventFilter function (self, filterObj: Any) -> Any (shared captured text)
invalidate function (self, x: Any, y: Any, w: Any, h: Any, layers: Any) -> None X.invalidate(x, y, w, h, layers)
isActive function (self) -> bool X.isActive() -> bool
isSignalConnected function (self, signal: Any) -> bool X.isSignalConnected(signal) -> bool (shared captured text)
isSortCacheEnabled function (self) -> bool X.isSortCacheEnabled() -> bool
isWidgetType function (self) -> bool X.isWidgetType() -> bool (shared captured text)
isWindowType function (self) -> bool X.isWindowType() -> bool (shared captured text)
itemAt function (self, x: Any, y: Any, deviceTransform: Any) -> Any X.itemAt(x, y, deviceTransform) -> PythonQt.QtGui.QGraphicsItem
itemIndexMethod attribute Any This property holds the item indexing method.
items function (self, x: Any, y: Any, w: Any, h: Any, mode: Any, order: Any, deviceTransform: Any) -> tuple X.items(x, y, w, h, mode, order, deviceTransform) -> tuple
itemsBoundingRect function (self) -> Any X.itemsBoundingRect() -> PythonQt.QtCore.QRectF
keyPressEvent function (self, event: Any) -> None This event handler, for event keyEvent, can be reimplemented in a subclass to receive keypress events.
keyReleaseEvent function (self, event: Any) -> None This event handler, for event keyEvent, can be reimplemented in a subclass to receive key release events.
killTimer function (self, id: Any) -> Any (shared captured text)
metaObject function (self) -> Any X.metaObject() -> PythonQt.QtCore.QMetaObject (shared captured text)
minimumRenderSize attribute float This property holds the minimal view-transformed size an item must have to be drawn
mouseDoubleClickEvent function (self, event: Any) -> None This event handler, for event mouseEvent, can be reimplemented in a subclass to receive mouse double-click events for the scene.
mouseGrabberItem function (self) -> Any X.mouseGrabberItem() -> PythonQt.QtGui.QGraphicsItem
mouseMoveEvent function (self, event: Any) -> None This event handler, for event mouseEvent, can be reimplemented in a subclass to receive mouse move events for the scene.
mousePressEvent function (self, event: Any) -> None This event handler, for event mouseEvent, can be reimplemented in a subclass to receive mouse press events for the scene.
mouseReleaseEvent function (self, event: Any) -> None This event handler, for event mouseEvent, can be reimplemented in a subclass to receive mouse release events for the scene.
moveToThread function (self, thread: Any) -> Any (shared captured text)
objectName attribute Any (shared captured text)
objectNameChanged function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.QtGui.QGraphicsScene.objectNameChanged; argument details are not documented.
palette attribute QPalette This property holds the scene's default palette
parent function (self) -> Any X.parent() -> PythonQt.private.QObject (shared captured text)
property function (self, name: Any) -> Any X.property(name) -> object (shared captured text)
removeEventFilter function (self, obj: Any) -> Any (shared captured text)
removeItem function (self, item: Any) -> None Removes the item item and all its children from the scene.
render function (self, painter: Any, target: Any, source: Any, aspectRatioMode: Any) -> None X.render(painter, target, source, aspectRatioMode)
sceneRect attribute QRectF This property holds the scene rectangle; the bounding rectangle of the scene
sceneRectChanged function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.QtGui.QGraphicsScene.sceneRectChanged; argument details are not documented.
selectedItems function (self) -> tuple X.selectedItems() -> tuple
selectionArea function (self) -> Any X.selectionArea() -> PythonQt.QtGui.QPainterPath
selectionChanged function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.QtGui.QGraphicsScene.selectionChanged; argument details are not documented.
sendEvent function (self, item: Any, event: Any) -> bool X.sendEvent(item, event) -> bool
sender function (self) -> Any X.sender() -> PythonQt.private.QObject (shared captured text)
senderSignalIndex function (self) -> int X.senderSignalIndex() -> int (shared captured text)
setActivePanel function (self, item: Any) -> None Activates item, which must be an item in this scene.
setActiveWindow function (self, widget: Any) -> None Activates widget, which must be a widget in this scene.
setBackgroundBrush function (self, brush: Any) -> None
setBspTreeDepth function (self, depth: int) -> None
setFocus function (self, focusReason: Any) -> None Sets focus on the scene by sending a [QFocusEvent](https://doc.qt.io/archives/qt-5.15/qfocusevent.html) to the scene, passing focusReason as the reason.
setFocusItem function (self, item: Any, focusReason: Any) -> None X.setFocusItem(item, focusReason)
setFont function (self, font: Any) -> None
setForegroundBrush function (self, brush: Any) -> None
setItemIndexMethod function (self, method: Any) -> None
setMinimumRenderSize function (self, minSize: float) -> None
setObjectName function (self, name: Any) -> Any (shared captured text)
setPalette function (self, palette: Any) -> None
setParent function (self, parent: Any) -> Any (shared captured text)
setProperty function (self, name: Any, value: Any) -> bool X.setProperty(name, value) -> bool (shared captured text)
setSceneRect function (self, x: Any, y: Any, w: Any, h: Any) -> None X.setSceneRect(x, y, w, h)
setSelectionArea function (self, path: Any, selectionOperation: Any, mode: Any, deviceTransform: Any) -> None X.setSelectionArea(path, selectionOperation, mode, deviceTransform)
setSortCacheEnabled function (self, enabled: bool) -> None
setStickyFocus function (self, enabled: bool) -> None
setStyle function (self, style: Any) -> None Sets or replaces the style of the scene to style, and reparents the style to this scene.
signalsBlocked function (self) -> bool X.signalsBlocked() -> bool (shared captured text)
sortCacheEnabled attribute Any
startTimer function (self, interval: Any, timerType: Any) -> int X.startTimer(interval, timerType) -> int (shared captured text)
stickyFocus attribute bool This property holds whether clicking into the scene background will clear focus
style function (self) -> Any X.style() -> PythonQt.QtGui.QStyle
thread function (self) -> Any (shared captured text)
timerEvent function (self, event: Any) -> Any (shared captured text)
tr function (self, text: Any, ambig: Any, n: Any) -> str X.tr(text, ambig, n) -> str (shared captured text)
update function (self, x: Any, y: Any, w: Any, h: Any) -> None X.update(x, y, w, h)
views function (self) -> tuple X.views() -> tuple
wheelEvent function (self, event: Any) -> None This event handler, for event wheelEvent, can be reimplemented in a subclass to receive mouse wheel events for the scene.
width function (self) -> float X.width() -> float