Skip to content

PythonQt.Qt.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 (shared captured text)
BackgroundLayer attribute Any (shared captured text)
BspTreeIndex attribute Any (shared captured text)
ForegroundLayer attribute Any (shared captured text)
ItemIndexMethod attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
ItemLayer attribute Any (shared captured text)
NoIndex attribute Any (shared captured text)
SceneLayer attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
SceneLayers attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
__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 (shared captured text)
activeWindow function (self) -> Any X.activeWindow() -> PythonQt.QtGui.QGraphicsWidget (shared captured text)
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 (shared captured text)
addItem function (self, item: Any) -> None Adds or moves the item and all its children to this scene. (shared captured text)
addLine function (self, x1: Any, y1: Any, x2: Any, y2: Any, pen: Any) -> Any X.addLine(x1, y1, x2, y2, pen) -> PythonQt.QtGui.QGraphicsLineItem (shared captured text)
addPath function (self, path: Any, pen: Any, brush: Any) -> Any X.addPath(path, pen, brush) -> PythonQt.QtGui.QGraphicsPathItem (shared captured text)
addPixmap function (self, pixmap: Any) -> Any X.addPixmap(pixmap) -> PythonQt.QtGui.QGraphicsPixmapItem (shared captured text)
addPolygon function (self, polygon: Any, pen: Any, brush: Any) -> Any X.addPolygon(polygon, pen, brush) -> PythonQt.QtGui.QGraphicsPolygonItem (shared captured text)
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 (shared captured text)
addSimpleText function (self, text: str, font: Any) -> Any X.addSimpleText(text, font) -> PythonQt.QtGui.QGraphicsSimpleTextItem (shared captured text)
addText function (self, text: str, font: Any) -> Any X.addText(text, font) -> PythonQt.QtGui.QGraphicsTextItem (shared captured text)
addWidget function (self, widget: Any, wFlags: Any) -> Any X.addWidget(widget, wFlags) -> PythonQt.QtGui.QGraphicsProxyWidget (shared captured text)
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. (shared captured text)
backgroundBrush attribute QBrush This property holds the background brush of the scene. (shared captured text)
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 (shared captured text)
changed function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.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. (shared captured text)
clearFocus function (self) -> None Clears focus from the scene. (shared captured text)
clearSelection function (self) -> None Clears the current selection. (shared captured text)
collidingItems function (self, item: Any, mode: Any) -> tuple X.collidingItems(item, mode) -> tuple (shared captured text)
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. (shared captured text)
createItemGroup function (self, items: Any) -> Any X.createItemGroup(items) -> PythonQt.QtGui.QGraphicsItemGroup (shared captured text)
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. (shared captured text)
destroyed function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.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. (shared captured text)
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. (shared captured text)
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. (shared captured text)
drawBackground function (self, painter: Any, rect: Any) -> None X.drawBackground(painter, rect) (shared captured text)
drawForeground function (self, painter: Any, rect: Any) -> None X.drawForeground(painter, rect) (shared captured text)
drawItems function (self, painter: Any, numItems: Any, items: Any, options: Any, widget: Any) -> Any X.drawItems(painter, numItems, items, options, widget) (shared captured text)
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. (shared captured text)
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 (shared captured text)
eventFilter function (self, watched: Any, event: Any) -> bool X.eventFilter(watched, event) -> bool (shared captured text)
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. (shared captured text)
focusItem function (self) -> Any X.focusItem() -> PythonQt.QtGui.QGraphicsItem (shared captured text)
focusItemChanged function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QGraphicsScene.focusItemChanged; argument details are not documented.
focusOnTouch attribute bool This property holds whether items gain focus when receiving a touch begin event. (shared captured text)
focusOutEvent function (self, event: Any) -> None This event handler, for event focusEvent, can be reimplemented in a subclass to receive focus out events. (shared captured text)
font attribute QFont This property holds the scene's default font (shared captured text)
foregroundBrush attribute QBrush This property holds the foreground brush of the scene. (shared captured text)
hasFocus function (self) -> bool X.hasFocus() -> bool (shared captured text)
height function (self) -> float X.height() -> float (shared captured text)
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. (shared captured text)
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. (shared captured text)
inputMethodQuery function (self, query: Any) -> Any X.inputMethodQuery(query) -> object (shared captured text)
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) (shared captured text)
isActive function (self) -> bool X.isActive() -> bool (shared captured text)
isSignalConnected function (self, signal: Any) -> bool X.isSignalConnected(signal) -> bool (shared captured text)
isSortCacheEnabled function (self) -> bool X.isSortCacheEnabled() -> bool (shared captured text)
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 (shared captured text)
itemIndexMethod attribute Any This property holds the item indexing method. (shared captured text)
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 (shared captured text)
itemsBoundingRect function (self) -> Any X.itemsBoundingRect() -> PythonQt.QtCore.QRectF (shared captured text)
keyPressEvent function (self, event: Any) -> None This event handler, for event keyEvent, can be reimplemented in a subclass to receive keypress events. (shared captured text)
keyReleaseEvent function (self, event: Any) -> None This event handler, for event keyEvent, can be reimplemented in a subclass to receive key release events. (shared captured text)
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 (shared captured text)
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. (shared captured text)
mouseGrabberItem function (self) -> Any X.mouseGrabberItem() -> PythonQt.QtGui.QGraphicsItem (shared captured text)
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. (shared captured text)
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. (shared captured text)
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. (shared captured text)
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.Qt.QGraphicsScene.objectNameChanged; argument details are not documented.
palette attribute QPalette This property holds the scene's default palette (shared captured text)
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. (shared captured text)
render function (self, painter: Any, target: Any, source: Any, aspectRatioMode: Any) -> None X.render(painter, target, source, aspectRatioMode) (shared captured text)
sceneRect attribute QRectF This property holds the scene rectangle; the bounding rectangle of the scene (shared captured text)
sceneRectChanged function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QGraphicsScene.sceneRectChanged; argument details are not documented.
selectedItems function (self) -> tuple X.selectedItems() -> tuple (shared captured text)
selectionArea function (self) -> Any X.selectionArea() -> PythonQt.QtGui.QPainterPath (shared captured text)
selectionChanged function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QGraphicsScene.selectionChanged; argument details are not documented.
sendEvent function (self, item: Any, event: Any) -> bool X.sendEvent(item, event) -> bool (shared captured text)
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. (shared captured text)
setActiveWindow function (self, widget: Any) -> None Activates widget, which must be a widget in this scene. (shared captured text)
setBackgroundBrush function (self, brush: Any) -> None (shared captured text)
setBspTreeDepth function (self, depth: int) -> None (shared captured text)
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. (shared captured text)
setFocusItem function (self, item: Any, focusReason: Any) -> None X.setFocusItem(item, focusReason) (shared captured text)
setFont function (self, font: Any) -> None (shared captured text)
setForegroundBrush function (self, brush: Any) -> None (shared captured text)
setItemIndexMethod function (self, method: Any) -> None (shared captured text)
setMinimumRenderSize function (self, minSize: float) -> None (shared captured text)
setObjectName function (self, name: Any) -> Any (shared captured text)
setPalette function (self, palette: Any) -> None (shared captured text)
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) (shared captured text)
setSelectionArea function (self, path: Any, selectionOperation: Any, mode: Any, deviceTransform: Any) -> None X.setSelectionArea(path, selectionOperation, mode, deviceTransform) (shared captured text)
setSortCacheEnabled function (self, enabled: bool) -> None (shared captured text)
setStickyFocus function (self, enabled: bool) -> None (shared captured text)
setStyle function (self, style: Any) -> None Sets or replaces the style of the scene to style, and reparents the style to this scene. (shared captured text)
signalsBlocked function (self) -> bool X.signalsBlocked() -> bool (shared captured text)
sortCacheEnabled attribute Any (shared captured text)
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 (shared captured text)
style function (self) -> Any X.style() -> PythonQt.QtGui.QStyle (shared captured text)
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) (shared captured text)
views function (self) -> tuple X.views() -> tuple (shared captured text)
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. (shared captured text)
width function (self) -> float X.width() -> float (shared captured text)