|  | Home · Overviews · Examples

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

The `QGraphicsView` class provides a widget for displaying the contents of a `QGraphicsScene`. More...

Inherits `QAbstractScrollArea`.

## Detailed Description

The `QGraphicsView` class provides a widget for displaying the contents of a `QGraphicsScene`.

`QGraphicsView` visualizes the contents of a `QGraphicsScene` in a scrollable viewport. To create a scene with geometrical items, see `QGraphicsScene`'s documentation. `QGraphicsView` is part of The Graphics View Framework.

To visualize a scene, you start by constructing a `QGraphicsView` object, passing the address of the scene you want to visualize to `QGraphicsView`'s constructor. Alternatively, you can call `setScene` to set the scene at a later point. After you call `show`, the view will by default scroll to the center of the scene and display any items that are visible at this point. For example:

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

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

You can explicitly scroll to any position on the scene by using the scroll bars, or by calling `centerOn`. By passing a point to `centerOn`, `QGraphicsView` will scroll its viewport to ensure that the point is centered in the view. An overload is provided for scrolling to a `QGraphicsItem`, in which case `QGraphicsView` will see to that the center of the item is centered in the view. If all you want is to ensure that a certain area is visible, (but not necessarily centered,) you can call `ensureVisible` instead.

`QGraphicsView` can be used to visualize a whole scene, or only parts of it. The visualized area is by default detected automatically when the view is displayed for the first time (by calling QGraphicsScene::itemsBoundingRect()). To set the visualized area rectangle yourself, you can call `setSceneRect`. This will adjust the scroll bars' ranges appropriately. Note that although the scene supports a virtually unlimited size, the range of the scroll bars will never exceed the range of an integer (INT_MIN, INT_MAX). When the scene is larger than the scroll bars' values, you can choose to use `translate` to navigate the scene instead.

`QGraphicsView` visualizes the scene by calling `render`. By default, the items are drawn onto the viewport by using a regular `QPainter`, and using default render hints. To change the default render hints that `QGraphicsView` passes to `QPainter` when painting items, you can call `setRenderHints`.

By default, `QGraphicsView` provides a regular `QWidget` for the viewport widget. You can access this widget by calling `viewport`, or you can replace it by calling `setViewport`. To render using OpenGL, simply call `setViewport`(new `QGLWidget`). `QGraphicsView` takes ownership of the viewport widget.

`QGraphicsView` supports affine transformations, using `QMatrix`. You can either pass a matrix to `setMatrix`, or you can call one of the convenience functions `rotate`, `scale`, `translate` or `shear`. The most two common transformations are scaling, which is used to implement zooming, and rotation. `QGraphicsView` keeps the center of the view fixed during a transformation.

You can interact with the items on the scene by using the mouse and keyboard. `QGraphicsView` translates the mouse and key events into scene events, (events that inherit `QGraphicsSceneEvent`,), and forward them to the visualized scene. In the end, it's the individual item that handles the events and reacts to them. For example, if you click on a selectable item, the item will typically let the scene know that it has been selected, and it will also redraw itself to display a selection rectangle. Similiary, if you click and drag the mouse to move a movable item, it's the item that handles the mouse moves and moves itself. Item interaction is enabled by default, and you can toggle it by calling `setInteractive`.

You can also provide your own custom scene interaction, by creating a subclass of `QGraphicsView`, and reimplementing the mouse and key event handlers. To simplify how you programmatically interact with items in the view, `QGraphicsView` provides the mapping functions `mapToScene` and `mapFromScene`, and the item accessors `items` and `itemAt`. These functions allow you to map points, rectangles, polygons and paths between view coordinates and scene coordinates, and to find items on the scene using view coordinates.

See also `QGraphicsScene`, `QGraphicsItem`, and `QGraphicsSceneEvent`.