|  | Home · Overviews · Examples

# QGraphicsScene Class Reference
[com.trolltech.qt.gui module]

The `QGraphicsScene` class provides a surface for managing a large number of 2D graphical items. More...

Inherits `QObject`.

## Detailed Description

The `QGraphicsScene` class provides a surface for managing a large number of 2D graphical items.

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 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, QApplication::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::acceptsHoverEvents()), 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.

See also `QGraphicsItem` and `QGraphicsView`.