source: trunk/doc/src/frameworks-technologies/graphicsview.qdoc@ 568

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** 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.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $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