QGraphicsScene Class

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

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

Property Documentation

backgroundBrush : QBrush

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 before (behind) the items.

Example:

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

 // a blue background
 scene.setBackgroundBrush(Qt::blue);

 // a gradient background
 QRadialGradient gradient(0, 0, 10);
 gradient.setSpread(QGradient::RepeatSpread);
 scene.setBackgroundBrush(gradient);

QGraphicsScene::render() calls drawBackground() to draw the scene background. For more detailed control over how the background is drawn, you can reimplement drawBackground() in a subclass of QGraphicsScene.

Access functions:

bspTreeDepth : int

This property holds the depth of QGraphicsScene's BSP index tree

This property has no effect when NoIndex is used.

This value determines the depth of QGraphicsScene's BSP tree. The depth directly affects QGraphicsScene's performance and memory usage; the latter growing exponentially with the depth of the tree. With an optimal tree depth, QGraphicsScene can instantly determine the locality of items, even for scenes with thousands or millions of items. This also greatly improves rendering performance.

By default, the value is 0, in which case Qt will guess a reasonable default depth based on the size, location and number of items in the scene. If these parameters change frequently, however, you may experience slowdowns as QGraphicsScene retunes the depth internally. You can avoid potential slowdowns by fixating the tree depth through setting this property.

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:

 QSizeF segmentSize = sceneRect().size() / pow(2, depth - 1);

The BSP tree has an optimal size when each segment contains between 0 and 10 items.

This property was introduced in Qt 4.3.

Access functions:

See also itemIndexMethod.

focusOnTouch : bool

This property holds whether items gain focus when receiving a touch begin event.

The usual behavior is to transfer focus only when an item is clicked. Often a tap on a touchpad is interpreted as equivalent to a mouse click by the operating system, generating a synthesized click event in response. However, at least on macOS you can configure this behavior.

By default, QGraphicsScene also transfers focus when you touch on a trackpad or similar. If the operating system is configured to not generate a synthetic mouse click on tapping the trackpad, this is surprising. If the operating system does generate synthetic mouse clicks on tapping the trackpad, the focus transfer on starting a touch gesture is unnecessary.

With focusOnTouch switched off, QGraphicsScene behaves as one would expect on macOS.

The default value is true, ensuring that the default behavior is just as in Qt versions prior to 5.12. Set to false to prevent touch events from triggering focus changes.

This property was introduced in Qt 5.12.

Access functions:

font : QFont

This property holds the scene's default font

This property provides the scene's font. The scene font defaults to, and resolves all its entries from, QApplication::font.

If the scene's font changes, either directly through setFont() or indirectly when the application font changes, QGraphicsScene first sends itself a FontChange event, and it then sends FontChange events to all top-level widget items in the scene. These items respond by resolving their own fonts to the scene, and they then notify their children, who again notify their children, and so on, until all widget items have updated their fonts.

Changing the scene font, (directly or indirectly through QApplication::setFont(),) automatically schedules a redraw the entire scene.

This property was introduced in Qt 4.4.

Access functions:

See also QWidget::font, QApplication::setFont(), palette, and style().

foregroundBrush : QBrush

This property holds the foreground brush of the scene.

Change this property to set the scene's foreground to a different color, gradient or texture.

The foreground is drawn after (on top of) the items. The default foreground brush is Qt::NoBrush ( i.e. the foreground is not drawn).

Example:

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

 // a white semi-transparent foreground
 scene.setForegroundBrush(QColor(255, 255, 255, 127));

 // a grid foreground
 scene.setForegroundBrush(QBrush(Qt::lightGray, Qt::CrossPattern));

QGraphicsScene::render() calls drawForeground() to draw the scene foreground. For more detailed control over how the foreground is drawn, you can reimplement the drawForeground() function in a QGraphicsScene subclass.

Access functions:

itemIndexMethod : ItemIndexMethod

This property holds the item indexing method.

QGraphicsScene applies an indexing algorithm to the scene, to speed up item discovery functions like items() and itemAt(). Indexing is most efficient for static scenes (i.e., where items don't move around). For dynamic scenes, or scenes with many animated items, the index bookkeeping can outweigh the fast lookup speeds.

For the common case, the default index method BspTreeIndex works fine. If your scene uses many animations and you are experiencing slowness, you can disable indexing by calling setItemIndexMethod(NoIndex).

Access functions:

See also bspTreeDepth.

minimumRenderSize : qreal

This property holds the minimal view-transformed size an item must have to be drawn

When the scene is rendered, any item whose width or height, transformed to the target view, is smaller that minimumRenderSize(), will not be rendered. If an item is not rendered and it clips its children items they will also not be rendered. Set this value to speed up rendering of scenes with many objects rendered on a zoomed out view.

The default value is 0. If unset, or if set to 0 or a negative value, all items will always be rendered.

For example, setting this property can be especially useful if a scene is rendered by multiple views, one of which serves as an overview which always displays all items. In scenes with many items, such a view will use a high scaling factor so that all items can be shown. Due to the scaling, smaller items will only make an insignificant contribution to the final rendered scene. To avoid drawing these items and reduce the time necessary to render the scene, you can call setMinimumRenderSize() with a non-negative value.

This property was introduced in Qt 5.4.

Access functions:

See also QStyleOptionGraphicsItem::levelOfDetailFromTransform().

palette : QPalette

This property holds the scene's default palette

This property provides the scene's palette. The scene palette defaults to, and resolves all its entries from, QApplication::palette.

If the scene's palette changes, either directly through setPalette() or indirectly when the application palette changes, QGraphicsScene first sends itself a PaletteChange event, and it then sends PaletteChange events to all top-level widget items in the scene. These items respond by resolving their own palettes to the scene, and they then notify their children, who again notify their children, and so on, until all widget items have updated their palettes.

Changing the scene palette, (directly or indirectly through QApplication::setPalette(),) automatically schedules a redraw the entire scene.

This property was introduced in Qt 4.4.

Access functions:

See also QWidget::palette, QApplication::setPalette(), font, and style().

sceneRect : QRectF

This property holds the scene rectangle; the bounding rectangle of the scene

The scene rectangle defines the extent of the scene. It is primarily used by QGraphicsView to determine the view's default scrollable area, and by QGraphicsScene to manage item indexing.

If unset, or if set to a null QRectF, sceneRect() will return the largest bounding rect of all items on the scene since the scene was created (i.e., a rectangle that grows when items are added to or moved in the scene, but never shrinks).

Access functions:

See also width(), height(), and QGraphicsView::sceneRect.

stickyFocus : bool

This property holds whether clicking into the scene background will clear focus

In a QGraphicsScene with stickyFocus set to true, focus will remain unchanged when the user clicks into the scene background or on an item that does not accept focus. Otherwise, focus will be cleared.

By default, this property is false.

Focus changes in response to a mouse press. You can reimplement mousePressEvent() in a subclass of QGraphicsScene to toggle this property based on where the user has clicked.

This property was introduced in Qt 4.6.

Access functions:

See also clearFocus() and setFocusItem().