QGraphicsView Class Reference
[QtGui module]

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 QTransform. You can either pass a matrix to setTransform(), 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.

Member Type Documentation

 QGraphicsView view;
 view.setBackgroundBrush(QImage(":/images/backgroundtile.png"));
 view.setCacheMode(QGraphicsView::CacheBackground);

 QGraphicsScene scene;
 scene.addRect(QRectF(-10, -10, 20, 20));

 QGraphicsView view(&scene);
 view.setRenderHints(QPainter::Antialiasing | QPainter::SmoothPixmapTransform);
 view.show();

 void CustomView::mousePressEvent(QMouseEvent *event)
 {
     if (QGraphicsItem *item = itemAt(event->pos())) {
         qDebug() << "You clicked on item" << item;
     } else {
         qDebug() << "You didn't click on an item.";
     }
 }

 void CustomView::mousePressEvent(QMouseEvent *event)
 {
     qDebug() << "There are" << items(event->pos()).size()
              << "items at position" << mapToScene(event->pos());
 }

 QGraphicsScene scene;
 scene.addItem(...
 ...

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

 QPrinter printer(QPrinter::HighResolution);
 printer.setPageSize(QPrinter::A4);
 QPainter painter(&printer);

 // print, fitting the viewport contents into a full page
 view.render(&painter);

 // print the upper half of the viewport into the lower.
 // half of the page.
 QRect viewport = view.viewport()->rect();
 view.render(&painter,
             QRectF(0, printer.height() / 2,
                    printer.width(), printer.height() / 2),
             viewport.adjusted(0, 0, 0, -viewport.height() / 2));

 QGraphicsScene scene;
 scene.addText("GraphicsView rotated clockwise");

 QGraphicsView view(&scene);
 view.rotate(90); // the text is rendered with a 90 degree clockwise rotation
 view.show();

 QGraphicsScene scene;
 scene.addText("GraphicsView rotated clockwise");

 QGraphicsView view(&scene);
 view.rotate(90); // the text is rendered with a 90 degree clockwise rotation
 view.show();