List of classes for managing 2D graphic widgets. More...

Classes
class	QAbstractGraphicsShapeItem
	Common base for all path items More...
class	QGraphicsEllipseItem
	Ellipse item which can added to a QGraphicsScene More...
class	QGraphicsGridLayout
	Grid layout for managing widgets in Graphics View More...
class	QGraphicsItem
	Base class for all graphical items in a QGraphicsScene More...
class	QGraphicsItemAnimation
	Simple animation support for QGraphicsItem More...
class	QGraphicsItemGroup
	Container that treats a group of items as a single item More...
class	QGraphicsLayout
	Base class for all layouts in a Graphics View More...
class	QGraphicsLayoutItem
	Can be inherited to allow your custom items to be managed by layouts More...
class	QGraphicsLineItem
	QGraphicsLineItem class provides a line item you can add to a QGraphicsScene More...
class	QGraphicsLinearLayout
	Horizontal or vertical layout for managing widgets in Graphics View More...
class	QGraphicsObject
	Base class for all graphics items that require signals, slots and properties More...
class	QGraphicsPathItem
	Path item that you can add to a QGraphicsScene More...
class	QGraphicsPixmapItem
	Pixmap item which can be added to a QGraphicsScene More...
class	QGraphicsPolygonItem
	Polygon item that you can add to a QGraphicsScene More...
class	QGraphicsProxyWidget
	Proxy layer for embedding a QWidget in a QGraphicsScene More...
class	QGraphicsRectItem
	Rectangle item which can be added to a QGraphicsScene More...
class	QGraphicsScene
	Provides a surface for managing a large number of 2D graphical items More...
class	QGraphicsSceneContextMenuEvent
	Context menu events in the graphics view system More...
class	QGraphicsSceneDragDropEvent
	Events for drag and drop in the graphics view system More...
class	QGraphicsSceneEvent
	Base class for all graphics view related events More...
class	QGraphicsSceneHelpEvent
	Events when a tooltip is requested More...
class	QGraphicsSceneHoverEvent
	Hover events in the graphics view system More...
class	QGraphicsSceneMouseEvent
	Mouse events in the graphics view system More...
class	QGraphicsSceneMoveEvent
	Events for widget moving in the graphics view system More...
class	QGraphicsSceneResizeEvent
	Events for widget resizing in the graphics view system More...
class	QGraphicsSceneWheelEvent
	Provides wheel events in the graphics view system More...
class	QGraphicsSimpleTextItem
	Simple text path item that you can add to a QGraphicsScene More...
class	QGraphicsSvgItem
	QGraphicsItem which can be used to render the contents of SVG files More...
class	QGraphicsTextItem
	Text item which can be added to a QGraphicsScene to display formatted text More...
class	QGraphicsTransform
	Abstract base class for building advanced transformations on QGraphicsItems More...
class	QGraphicsView
	Widget for displaying the contents of a QGraphicsScene More...
class	QGraphicsWidget
	Base class for all widget items in a QGraphicsScene More...
class	QStyleOptionGraphicsItem
	Stores parameters used to draw a QGraphicsItem More...

Detailed Description

Graphics View classes provide a surface for managing and interacting with a large number of custom 2D graphical items and a view widget for visualizing the items and support for zooming and rotation. This system includes an event propagation architecture that allows precise double-precision interaction capabilities for the items on the scene. Items can handle key events, mouse press, move events, and release and double click mouse events.

Graphics View uses a BSP (Binary Space Partitioning) tree to provide very fast item lookup. The view can display large scenes in real time and smoothly, even when there are millions of items.

Graphics View Architecture

A Graphics View provides an item based approach, much like the classes QTableView, QTreeView and QListView provide for model view programming. Multiple views can observe a single scene and the scene can contains items of varying geometric shapes.

Scenes

The QGraphicsScene class creates a Graphics View scene. The scene has the following responsibilities.

• Provide a fast interface for managing a large number of items
• Propagate events to each item
• Manage item state such as selection and focus handling
• Provide untransformed rendering functionality, mainly for printing

The scene serves as a container for QGraphicsItem objects. Items are added to the scene by calling QGraphicsScene::addItem() and then retrieved by calling one of the many item lookup methods.

• Methods like QGraphicsScene::items() return a list of items contained by or intersecting with a point, a rectangle, a polygon, or a general vector path.

• QGraphicsScene::itemAt() returns the topmost item at a particular point.

• To retrieve a list of the currently selected items call QGraphicsScene::selectedItems().

The QGraphicsScene event propagation architecture schedules scene events for delivery to items and also manages propagation between items. If the scene receives a mouse press event at a certain position the scene passes the event on to whichever item is at that position.

The sceene also manages item states such as item selection and keyboard focus. You can select items on the scene by calling QGraphicsScene::setSelectionArea() and passing an arbitrary shape. This functionality is also used as a basis for rubberband selection in QGraphicsView. Another state which is handled by QGraphicsScene is whether or not an item has keyboard input focus. Focus can be set on an item by calling QGraphicsScene::setFocusItem() or QGraphicsItem::setFocus().

The item which currently has focus can be retrieved by calling QGraphicsScene::focusItem(). QGraphicsScene also allows rendering parts of the scene into a paint device by using QGraphicsScene::render().

Views

QGraphicsView provides the view widget which displays the contents of a scene. You can attach several views to the same scene to provide several viewports into the same data set. The view widget is a scroll area and provides scroll bars for navigating through large scenes. To enable OpenGL support set a QGLWidget as the viewport by calling QGraphicsView::setViewport().

The view receives input events from the keyboard and mouse and translates them to scene events. The coordinates are mapped to scene coordinates before the event is sent to the scene.

Using its transformation matrix, QGraphicsView::transform(), the view can transform the scene's coordinate system. This allows advanced navigation features such as zooming and rotation. QGraphicsView also provides methods for translating between view and scene coordinates, like QGraphicsView::mapToScene() and QGraphicsView::mapFromScene().

Items

QGraphicsItem is the base class for graphical items in a scene. Graphics View provides several standard items for typical shapes, such as rectangles (QGraphicsRectItem), ellipses (QGraphicsEllipseItem) and text items (QGraphicsTextItem), but the most powerful QGraphicsItem features are available when you write a custom item. Among other things, QGraphicsItem supports the following features.

• Mouse press, move, release and double click events, as well as mouse hover events, wheel events, and context menu events.
• Keyboard input focus, and key events
• Drag and drop
• Grouping, both through parent child relationships and with QGraphicsItemGroup
• Collision detection

Items have a local coordinate system and QGraphicsItem has methods for converting between item and scene coordinates. There are also methods to transform the local coordinate system using a matrix. This is useful for rotating and scaling individual items.

Items can contain other child items. Parent item transformations are inherited by all children. Regardless of an item's accumulated transformation, all the QGraphicsItem methods still use local coordinates.

QGraphicsItem supports collision detection using QGraphicsItem::shape() and QGraphicsItem::collidesWithItem(), which are both virtual methods. To provide your own collision detection override QGraphicsItem::collidesWithItem().

QGraphicsItem can handle part of the collision detection process, however you will need to override QGraphicsItem::shape() to return the shape of the item in local coordinates.

Graphics View Coordinate System

Graphics View is based on the Cartesian coordinate system. The item position and geometry on the scene are represented by sets of two numbers, the x-coordinate, and the y-coordinate. When observing a scene using an untransformed view one unit on the scene is represented by one pixel on the screen.

There are three effective coordinate systems in a Graphics View: item coordinates, scene coordinates, and view coordinates. To simplify implementation, Graphics View provides methods which map between the three coordinate systems.

When rendering, Graphics View's scene coordinates correspond to QPainter logical coordinates. View coordinates are the same as device coordinates. Refer to the Coordinate System documentation for more information about the relationship between logical coordinates and device coordinates.

Item Coordinates

Items live in their own local coordinate system. Their coordinates are usually centered around its center point (0, 0), and this is also the center for all transformations. Geometric primitives in the item coordinate system are often referred to as item points, item lines, or item rectangles.

When creating a custom item, item coordinates are all you need to worry about, QGraphicsScene and QGraphicsView will perform all transformations for you. This makes it very easy to implement custom items. For example, if you receive a mouse press or a drag enter event, the event position is given in item coordinates. QGraphicsItem::contains() is a virtual method which returns true if a certain point is inside the item, otherwise false is returned.

An item's position is expressed in the parent's coordinate system. The scene is considered to be the parent for items which do not have a parent. Top level item positions are in scene coordinates.

Child coordinates are relative to the parent's coordinates. If the child is untransformed, the difference between a child coordinate and a parent coordinate is the same as the distance between the items in parent coordinates. For example, if an untransformed child item is positioned precisely in its parent's center point, then the two item coordinate systems will be identical. For example, if the child's position is (10, 0), the child's (0, 10) point will correspond to its parent's (10, 10) point.

Because the item position and transformation are relative to the parent, child item coordinates are unaffected by the parent's transformation, although the parent's transformation transforms the child. In the above example, even if the parent is rotated and scaled, the child's (0, 10) point will still correspond to the parent's (10, 10) point. Relative to the scene, however, the child will follow the parent's transformation and position. If the parent is scaled (2x, 2x), the child's position will be at scene coordinate (20, 0), and its (10, 0) point will correspond to the point (40, 0) on the scene.

Most of the methods in QGraphicsItem use item coordianates. QGraphicsItem::pos() is one of the few exceptions and this method returns the parents coordinates.

Scene Coordinates

The scene represents the base coordinate system for all its items. The scene coordinate system describes the position of each top-level item, and also forms the basis for all scene events delivered to the scene from the view. Each item on the scene has a scene position and bounding rectangle in addition to a local item position and bounding rectangle. The scene position describes the items position in scene coordinates and the scene bounding rectangle form the basis for how QGraphicsScene determines what areas of the scene have changed. Changes in the scene are communicated through the QGraphicsScene::changed() signal and the argument is a list of scene rectangles.

View Coordinates

View coordinates are the coordinates of the widget. Each unit in view coordinates corresponds to one pixel. What's special about this coordinate system is that it is relative to the widget, or viewport, and unaffected by the observed scene. The top left corner of QGraphicsView's viewport is always (0, 0), and the bottom right corner is always (viewport width, viewport height). All mouse events and drag and drop events are originally received as view coordinates, and you need to map these coordinates to the scene in order to interact with items.

Coordinate Mapping

Often when dealing with items in a scene, it can be useful to map coordinates and arbitrary shapes from the scene to an item, from item to item, or from the view to the scene. For example, when you click your mouse in QGraphicsView's viewport, you can ask the scene what item is under the cursor by calling QGraphicsView::mapToScene(), followed by QGraphicsScene::itemAt(). If you want to know where in the viewport an item is located, you can call QGraphicsItem::mapToScene() on the item, then QGraphicsView::mapFromScene() on the view. Finally, if you use want to find what items are inside a view ellipse, you can pass a QPainterPath to mapToScene() and then pass the mapped path to QGraphicsScene::items().

You can map coordinates and shapes to and from and item's scene by calling QGraphicsItem::mapToScene() and QGraphicsItem::mapFromScene(). You can also map to an item's parent item by calling QGraphicsItem::mapToParent() and QGraphicsItem::mapFromParent(), or between items by calling QGraphicsItem::mapToItem() and QGraphicsItem::mapFromItem(). All mapping methods can map points, rectangles, polygons, and paths.

The same mapping methods are available in the view for mapping to and from the scene using QGraphicsView::mapFromScene() and QGraphicsView::mapToScene(). To map from a view to an item, map to the scene and then map from the scene to the item.

Zooming and Rotating

QGraphicsView supports the same affine transformations as QPainter does through QGraphicsView::setMatrix(). By applying a transformation to the view, you can easily add support for common navigation features such as zooming and rotating.

Here is an example of how to implement zoom and rotate in a subclass of QGraphicsView.

Printing

Graphics View provides single line printing through its rendering methods, QGraphicsScene::render() and QGraphicsView::render(). These methods have the same API. Either the scene or the view can render all or parts of their contents into any paint device by passing a QPainter to the render methods.

This example shows how to print the whole scene into a full page using QPrinter.

The difference between the scene and view rendering methods is one operates in scene coordinates and the other in view coordinates. QGraphicsScene::render() is often preferred for printing whole segments of a scene untransformed, such as for plotting geometrical data or for printing a text document. QGraphicsView::render() is suitable for taking screenshots. The default behavior is to render the exact contents of the viewport using the provided painter.

When the source and target sizes do not match, the source contents are stretched to fit into the target area. By passing Qt::AspectRatioMode to the rendering method, you can choose to maintain or ignore the aspect ratio of the scene when the contents are stretched.

Drag and Drop

QGraphicsView has drag and drop functionality because it inherits from QWidget. In addition, the Graphics View system provides drag and drop support for the scene and for every item.

When the view receives a drag it translates the drag and drop events into a QGraphicsSceneDragDropEvent. This information is then forwarded to the scene.

To start a drag from an item create a QDrag object and pass a pointer to the widget which is starting the drag operation.

Drag and drop can be enabled or disabled by calling QGraphicsItem::setAcceptDrops().

To handle the drag event override QGraphicsItem::dragEnterEvent(), QGraphicsItem::dragMoveEvent(), QGraphicsItem::dragLeaveEvent(), and QGraphicsItem::dropEvent().

To intercept drag and drop events for the scene, inherit from QGraphicsItem and override QGraphicsScene::dragEnterEvent().

Cursors and Tooltips

Like QWidget, QGraphicsItem also supports cursors and tooltips. The cursors and tooltips are activated by QGraphicsView as the mouse cursor enters the item's area. You can also set a default cursor directly on the view by calling QGraphicsView::setCursor().

Animation

Graphics View supports animation at several levels. You can easily combine animations by using the Animation System. In order to annimate items they must inherit from QGraphicsObject and have a QPropertyAnimation configured. QPropertyAnimation allows animating any QObject property.

Another option is to create a custom item which inherits from QObject and QGraphicsItem. The item can then set up its own timers and control animations with incremental steps in QObject::timerEvent().

A third option is to advance the scene by calling QGraphicsScene::advance(), which in turn calls QGraphicsItem::advance().

OpenGL Rendering

To enable OpenGL rendering set a QGLWidget as the viewport of QGraphicsView by calling QGraphicsView::setViewport(). If you want OpenGL with antialiasing use an OpenGL sample buffer. Refer to QGLFormat::sampleBuffers().

Item Groups

When you make an item a child of another item, the two items become part of a group. If the parent item is moved all child items will move together since all transformations are propagated from parent to child. By changing the parent of the child, the position of the child is adjusted relative to its new parent.

The class QGraphicsItemGroup is used to create special items which combine child event handling to add and remove items to a group. Adding an item to a QGraphicsItemGroup will keep the original position and transformation of the child. To create a QGraphicsItemGroup call QGraphicsScene::createItemGroup().

Widgets and Layouts

The QGraphicsWidget class supports geometry and layout aware items. QGraphicsWidget inherits from QGraphicsItem wheareas QWidget inherits from QPaintDevice. This inheritance is what makes it possible for a QGraphicsWidget to be added to a QGraphicsScene.

Custom graphic widgets can be created with events, signals / slots, size hints, and policies. Layouts can be managed by using QGraphicsLinearLayout and QGraphicsGridLayout.

QGraphicsWidget

QGraphicsWidget provides extra functionality not found in QGraphicsItem. The additional features are similar to those found in QWidget like the style, font, palette, layout direction, geometry, and resolution independence and transformation support.

Because a Graphics View uses real coordinates instead of integers, the QGraphicsWidget geometry methods use QRectF and QPointF. This also applies to frame rectangles, margins, and spacing. For example, with QGraphicsWidget you can specify margins by calling setContentsMargins(0.5, 0.5, 0.5, 0.5).

QGraphicsLayout

QGraphicsLayout is part of a second layout system designed specifically for QGraphicsWidget. The API is very similar to the QLayout class. You can manage widgets and sublayouts using QGraphicsLinearLayout and QGraphicsGridLayout.

You can also write your own layout by inheriting from QGraphicsLayout or add custom layout items by inheriting from QGraphicsLayoutItem.

Embedded Widget Support

Graphics View provides seamless support for embedding any widget into the scene. You can embed simple widgets like QLineEdit or QPushButton, complex widgets like QTabWidget, and even a main window. To embed a widget to the scene call QGraphicsScene::addWidget() or create a QGraphicsProxyWidget to embed the widget manually.

Using QGraphicsProxyWidget, a Graphics View is able to integrate the client widget features including its cursors, tooltips, mouse, tablet and keyboard events, child widgets, animations, pop-ups, and the widget's input focus and activation. QGraphicsProxyWidget even integrates the embedded widget's tab order so that you can tab in and out of embedded widgets. You can even embed a new QGraphicsView into your scene to provide complex nested scenes.

When transforming an embedded widget Graphics View ensures the widget is transformed in a resolution independent way. This allows the fonts and style to stay clean when zoomed in. The effect of resolution independence depends on the style.

Floating Point Instructions

In order to accurately and quickly apply transformations and effects to items, Graphics View is built with the assumption that the user's hardware is able to provide reasonable performance for floating point instructions.

Many workstations and desktop computers are equipped with suitable hardware to accelerate this kind of computation, but some embedded devices may only provide libraries to handle mathematical operations or emulate floating point instructions in software.

As a result, certain kinds of effects may be slower than expected on certain devices. It may be possible to compensate for this performance hit by making optimizations in other areas. For example, by using OpenGL to render a scene. However, any such optimizations may themselves cause a reduction in performance if they also rely on the presence of floating point hardware.