--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/frameworks-technologies/graphicsview.qdoc Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,574 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \group graphicsview-api
+ \title Graphics View Classes
+*/
+
+/*!
+ \page graphicsview.html
+ \title The Graphics View Framework
+ \brief An overview of the Graphics View framework for interactive 2D
+ graphics.
+
+ \ingroup frameworks-technologies
+
+ \keyword Graphics View
+ \keyword GraphicsView
+ \keyword Graphics
+ \keyword Canvas
+ \since 4.2
+
+ Graphics View provides a surface for managing and interacting with a large
+ number of custom-made 2D graphical items, and a view widget for
+ visualizing the items, with support for zooming and rotation.
+
+ The framework 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, release and
+ double click events, and they can also track mouse movement.
+
+ Graphics View uses a BSP (Binary Space Partitioning) tree to provide very
+ fast item discovery, and as a result of this, it can visualize large
+ scenes in real-time, even with millions of items.
+
+ Graphics View was introduced in Qt 4.2, replacing its predecessor,
+ QCanvas. If you are porting from QCanvas, see \l{Porting to Graphics
+ View}.
+
+ Topics:
+
+ \tableofcontents
+
+ \section1 The Graphics View Architecture
+
+ Graphics View provides an item-based approach to model-view programming,
+ much like InterView's convenience classes QTableView, QTreeView and
+ QListView. Several views can observe a single scene, and the scene
+ contains items of varying geometric shapes.
+
+ \section2 The Scene
+
+ QGraphicsScene provides the Graphics View scene. The scene has the
+ following responsibilities:
+
+ \list
+ \o Providing a fast interface for managing a large number of items
+ \o Propagating events to each item
+ \o Managing item state, such as selection and focus handling
+ \o Providing untransformed rendering functionality; mainly for printing
+ \endlist
+
+ 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 discovery functions.
+ QGraphicsScene::items() and its overloads return all 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. All item discovery functions return the items in
+ descending stacking order (i.e., the first returned item is topmost,
+ and the last item is bottom-most).
+
+ \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 0
+
+ QGraphicsScene's 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.
+
+ QGraphicsScene also manages certain item states, such as item
+ selection and focus. You can select items on the scene by calling
+ QGraphicsScene::setSelectionArea(), passing an arbitrary shape. This
+ functionality is also used as a basis for rubberband selection in
+ QGraphicsView. To get the list of all currently selected items, call
+ QGraphicsScene::selectedItems(). Another state handled by
+ QGraphicsScene is whether or not an item has keyboard input focus. You
+ can set focus on an item by calling QGraphicsScene::setFocusItem() or
+ QGraphicsItem::setFocus(), or get the current focus item by calling
+ QGraphicsScene::focusItem().
+
+ Finally, QGraphicsScene allows you to render parts of the scene into a
+ paint device through the QGraphicsScene::render() function. You can
+ read more about this in the Printing section later in this document.
+
+ \section2 The View
+
+ QGraphicsView provides the view widget, which visualizes 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, you can set a QGLWidget as the viewport by
+ calling QGraphicsView::setViewport().
+
+ \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 1
+
+ The view receives input events from the keyboard and mouse, and
+ translates these to scene events (converting the coordinates used
+ to scene coordinates where appropriate), before sending the events
+ to the visualized scene.
+
+ Using its transformation matrix, QGraphicsView::transform(), the view can
+ \e transform the scene's coordinate system. This allows advanced
+ navigation features such as zooming and rotation. For convenience,
+ QGraphicsView also provides functions for translating between view and
+ scene coordinates: QGraphicsView::mapToScene() and
+ QGraphicsView::mapFromScene().
+
+ \img graphicsview-view.png
+
+ \section2 The Item
+
+ 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:
+
+ \list
+ \o Mouse press, move, release and double click events, as well as mouse
+ hover events, wheel events, and context menu events.
+ \o Keyboard input focus, and key events
+ \o Drag and drop
+ \o Grouping, both through parent-child relationships, and with
+ QGraphicsItemGroup
+ \o Collision detection
+ \endlist
+
+ Items live in a local coordinate system, and like QGraphicsView, it
+ also provides many functions for mapping coordinates between the item
+ and the scene, and from item to item. Also, like QGraphicsView, it can
+ transform its coordinate system using a matrix:
+ QGraphicsItem::transform(). This is useful for rotating and scaling
+ individual items.
+
+ Items can contain other items (children). Parent items'
+ transformations are inherited by all its children. Regardless of an
+ item's accumulated transformation, though, all its functions (e.g.,
+ QGraphicsItem::contains(), QGraphicsItem::boundingRect(),
+ QGraphicsItem::collidesWith()) still operate in local coordinates.
+
+ QGraphicsItem supports collision detection through the
+ QGraphicsItem::shape() function, and QGraphicsItem::collidesWith(),
+ which are both virtual functions. By returning your item's shape as a
+ local coordinate QPainterPath from QGraphicsItem::shape(),
+ QGraphicsItem will handle all collision detection for you. If you want
+ to provide your own collision detection, however, you can reimplement
+ QGraphicsItem::collidesWith().
+
+ \img graphicsview-items.png
+
+ \section1 Classes in the Graphics View Framework
+
+ These classes provide a framework for creating interactive applications.
+
+ \annotatedlist graphicsview-api
+
+ \section1 The Graphics View Coordinate System
+
+ Graphics View is based on the Cartesian coordinate system; items'
+ 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.
+
+ \note The inverted Y-axis coordinate system (where \c y grows upwards)
+ is unsupported as Graphics Views uses Qt's coordinate system.
+
+ There are three effective coordinate systems in play in Graphics View:
+ Item coordinates, scene coordinates, and view coordinates. To simplify
+ your implementation, Graphics View provides convenience functions that
+ allow you to map between the three coordinate systems.
+
+ When rendering, Graphics View's scene coordinates correspond to
+ QPainter's \e logical coordinates, and view coordinates are the same as
+ \e device coordinates. In \l{The Coordinate System}, you can read about
+ the relationship between logical coordinates and device coordinates.
+
+ \img graphicsview-parentchild.png
+
+ \section2 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. The
+ QGraphicsItem::contains() virtual function, which returns true if a
+ certain point is inside your item, and false otherwise, takes a
+ point argument in item coordinates. Similarly, an item's bounding
+ rect and shape are in item coordinates.
+
+ At item's \e position is the coordinate of the item's center point
+ in its parent's coordinate system; sometimes referred to as \e
+ parent coordinates. The scene is in this sense regarded as all
+ parent-less items' "parent". Top level items' position 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 items' coordinate systems will be identical. If the child's
+ position is (10, 0), however, the child's (0, 10) point will
+ correspond to its parent's (10, 10) point.
+
+ Because items' position and transformation are relative to the
+ parent, child items' coordinates are unaffected by the parent's
+ transformation, although the parent's transformation implicitly
+ 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.
+
+ With QGraphicsItem::pos() being one of the few exceptions,
+ QGraphicsItem's functions operate in item coordinates, regardless of
+ the item, or any of its parents' transformation. For example, an
+ item's bounding rect (i.e. QGraphicsItem::boundingRect()) is always
+ given in item coordinates.
+
+ \section2 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 (QGraphicsItem::scenePos(),
+ QGraphicsItem::sceneBoundingRect()), in addition to its local item
+ pos and bounding rectangle. The scene position describes the item's
+ position in scene coordinates, and its scene bounding rect forms 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.
+
+ \section2 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.
+
+ \section2 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 functions can map both points, rectangles, polygons and
+ paths.
+
+ The same mapping functions are available in the view, for mapping to
+ and from the scene. QGraphicsView::mapFromScene() and
+ QGraphicsView::mapToScene(). To map from a view to an item, you
+ first map to the scene, and then map from the scene to the item.
+
+ \section1 Key Features
+
+ \section2 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 slots in a
+ subclass of QGraphicsView:
+
+ \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 2
+
+ The slots could be connected to \l{QToolButton}{QToolButtons} with
+ \l{QAbstractButton::autoRepeat}{autoRepeat} enabled.
+
+ QGraphicsView keeps the center of the view aligned when you transform
+ the view.
+
+ See also the \l{Elastic Nodes Example}{Elastic Nodes} example for
+ code that shows how to implement basic zooming features.
+
+ \section2 Printing
+
+ Graphics View provides single-line printing through its rendering
+ functions, QGraphicsScene::render() and QGraphicsView::render(). The
+ functions provide the same API: You can have the scene or the view
+ render all or parts of their contents into any paint device by passing
+ a QPainter to either of the rendering functions. This example shows
+ how to print the whole scene into a full page, using QPrinter.
+
+ \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 3
+
+ The difference between the scene and view rendering functions is that
+ 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(), on the
+ other hand, is suitable for taking screenshots; its default behavior
+ is to render the exact contents of the viewport using the provided
+ painter.
+
+ \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 4
+
+ When the source and target areas' sizes do not match, the source
+ contents are stretched to fit into the target area. By passing a
+ Qt::AspectRatioMode to the rendering function you are using, you can
+ choose to maintain or ignore the aspect ratio of the scene when the
+ contents are stretched.
+
+ \section2 Drag and Drop
+
+ Because QGraphicsView inherits QWidget indirectly, it already provides
+ the same drag and drop functionality that QWidget provides. In
+ addition, as a convenience, the Graphics View framework provides drag
+ and drop support for the scene, and for each and every item. As the
+ view receives a drag, it translates the drag and drop events into a
+ QGraphicsSceneDragDropEvent, which is then forwarded to the scene. The
+ scene takes over scheduling of this event, and sends it to the first
+ item under the mouse cursor that accepts drops.
+
+ To start a drag from an item, create a QDrag object, passing a pointer
+ to the widget that starts the drag. Items can be observed by many
+ views at the same time, but only one view can start the drag. Drags
+ are in most cases started as a result of pressing or moving the mouse,
+ so in mousePressEvent() or mouseMoveEvent(), you can get the
+ originating widget pointer from the event. For example:
+
+ \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 5
+
+ To intercept drag and drop events for the scene, you reimplement
+ QGraphicsScene::dragEnterEvent() and whichever event handlers your
+ particular scene needs, in a QGraphicsItem subclass. You can read more
+ about drag and drop in Graphics View in the documentation for each of
+ QGraphicsScene's event handlers.
+
+ Items can enable drag and drop support by calling
+ QGraphicsItem::setAcceptDrops(). To handle the incoming drag,
+ reimplement QGraphicsItem::dragEnterEvent(),
+ QGraphicsItem::dragMoveEvent(), QGraphicsItem::dragLeaveEvent(), and
+ QGraphicsItem::dropEvent().
+
+ See also the \l{Drag and Drop Robot Example}{Drag and Drop Robot} example
+ for a demonstration of Graphics View's support for drag and drop
+ operations.
+
+ \section2 Cursors and Tooltips
+
+ Like QWidget, QGraphicsItem also supports cursors
+ (QGraphicsItem::setCursor()), and tooltips
+ (QGraphicsItem::setToolTip()). The cursors and tooltips are activated
+ by QGraphicsView as the mouse cursor enters the item's area (detected
+ by calling QGraphicsItem::contains()).
+
+ You can also set a default cursor directly on the view by calling
+ QGraphicsView::setCursor().
+
+ See also the \l{Drag and Drop Robot Example}{Drag and Drop Robot}
+ example for code that implements tooltips and cursor shape handling.
+
+ \section2 Animation
+
+ Graphics View supports animation at several levels. You can easily
+ assemble animation paths by associating a QGraphicsItemAnimation with
+ your item. This allows timeline controlled animations that operate at
+ a steady speed on all platforms (although the frame rate may vary
+ depending on the platform's performance). QGraphicsItemAnimation
+ allows you to create a path for an item's position, rotation, scale,
+ shear and translation. The animation can be controlled by a QSlider,
+ or more commonly by QTimeLine.
+
+ Another option is to create a custom item that inherits from QObject
+ and QGraphicsItem. The item can the set up its own timers, and control
+ animations with incremental steps in QObject::timerEvent().
+
+ A third option, which is mostly available for compatibility with
+ QCanvas in Qt 3, is to \e advance the scene by calling
+ QGraphicsScene::advance(), which in turn calls
+ QGraphicsItem::advance().
+
+ See also the \l{Drag and Drop Robot Example}{Drag and Drop Robot}
+ example for an illustration of timeline-based animation techniques.
+
+ \section2 OpenGL Rendering
+
+ To enable OpenGL rendering, you simply set a new QGLWidget as the
+ viewport of QGraphicsView by calling QGraphicsView::setViewport(). If
+ you want OpenGL with antialiasing, you need OpenGL sample buffer
+ support (see QGLFormat::sampleBuffers()).
+
+ Example:
+
+ \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 6
+
+ \section2 Item Groups
+
+ By making an item a child of another, you can achieve the most
+ essential feature of item grouping: the items will move together, and
+ all transformations are propagated from parent to child.
+
+ In addition, QGraphicsItemGroup is a special item that combines child
+ event handling with a useful interface for adding and removing items
+ to and from a group. Adding an item to a QGraphicsItemGroup will keep
+ the item's original position and transformation, whereas reparenting
+ items in general will cause the child to reposition itself relative to
+ its new parent. For convenience, you can create
+ \l{QGraphicsItemGroup}s through the scene by calling
+ QGraphicsScene::createItemGroup().
+
+ \section2 Widgets and Layouts
+
+ Qt 4.4 introduced support for geometry and layout-aware items through
+ QGraphicsWidget. This special base item is similar to QWidget, but
+ unlike QWidget, it doesn't inherit from QPaintDevice; rather from
+ QGraphicsItem instead. This allows you to write complete widgets with
+ events, signals & slots, size hints and policies, and you can also
+ manage your widgets geometries in layouts through
+ QGraphicsLinearLayout and QGraphicsGridLayout.
+
+ \section3 QGraphicsWidget
+
+ Building on top of QGraphicsItem's capabilities and lean footprint,
+ QGraphicsWidget provides the best of both worlds: extra
+ functionality from QWidget, such as the style, font, palette, layout
+ direction, and its geometry, and resolution independence and
+ transformation support from QGraphicsItem. Because Graphics View
+ uses real coordinates instead of integers, QGraphicsWidget's
+ geometry functions also operate on QRectF and QPointF. This also
+ applies to frame rects, margins and spacing. With QGraphicsWidget
+ it's not uncommon to specify contents margins of (0.5, 0.5, 0.5,
+ 0.5), for example. You can create both subwidgets and "top-level"
+ windows; in some cases you can now use Graphics View for advanced
+ MDI applications.
+
+ Some of QWidget's properties are supported, including window flags
+ and attributes, but not all. You should refer to QGraphicsWidget's
+ class documentation for a complete overview of what is and what is
+ not supported. For example, you can create decorated windows by
+ passing the Qt::Window window flag to QGraphicsWidget's constructor,
+ but Graphics View currently doesn't support the Qt::Sheet and
+ Qt::Drawer flags that are common on Mac OS X.
+
+ The capabilities of QGraphicsWidget are expected to grow depending
+ on community feedback.
+
+ \section3 QGraphicsLayout
+
+ QGraphicsLayout is part of a second-generation layout framework
+ designed specifically for QGraphicsWidget. Its API is very similar
+ to that of QLayout. You can manage widgets and sublayouts inside
+ either QGraphicsLinearLayout and QGraphicsGridLayout. You can also
+ easily write your own layout by subclassing QGraphicsLayout
+ yourself, or add your own QGraphicsItem items to the layout by
+ writing an adaptor subclass of QGraphicsLayoutItem.
+
+ \section2 Embedded Widget Support
+
+ Graphics View provides seamless support for embedding any widget
+ into the scene. You can embed simple widgets, such as QLineEdit or
+ QPushButton, complex widgets such as QTabWidget, and even complete
+ main windows. To embed your widget to the scene, simply call
+ QGraphicsScene::addWidget(), or create an instance of
+ QGraphicsProxyWidget to embed your widget manually.
+
+ Through QGraphicsProxyWidget, Graphics View is able to deeply
+ integrate the client widget features including its cursors,
+ tooltips, mouse, tablet and keyboard events, child widgets,
+ animations, pop-ups (e.g., QComboBox or QCompleter), 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 makes sure that
+ the widget is transformed resolution independently, allowing the
+ fonts and style to stay crisp when zoomed in. (Note that the effect
+ of resolution independence depends on the style.)
+
+ \section1 Performance
+
+ \section2 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 \l{#OpenGL Rendering}{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.
+*/