source: trunk/doc/src/graphicsview.qdoc@ 477

Last change on this file since 477 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.
File size: 27.3 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information ([email protected])
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you are unsure which license is appropriate for your use, please
37** contact the sales department at [email protected].
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42/*!
43 \page graphicsview.html
44 \title The Graphics View Framework
45 \ingroup architecture
46 \ingroup multimedia
47 \brief An overview of the Graphics View framework for interactive 2D
48 graphics.
49
50 \keyword Graphics View
51 \keyword GraphicsView
52 \keyword Graphics
53 \keyword Canvas
54 \since 4.2
55
56 Graphics View provides a surface for managing and interacting with a large
57 number of custom-made 2D graphical items, and a view widget for
58 visualizing the items, with support for zooming and rotation.
59
60 The framework includes an event propagation architecture that allows
61 precise double-precision interaction capabilities for the items on the
62 scene. Items can handle key events, mouse press, move, release and
63 double click events, and they can also track mouse movement.
64
65 Graphics View uses a BSP (Binary Space Partitioning) tree to provide very
66 fast item discovery, and as a result of this, it can visualize large
67 scenes in real-time, even with millions of items.
68
69 Graphics View was introduced in Qt 4.2, replacing its predecessor,
70 QCanvas. If you are porting from QCanvas, see \l{Porting to Graphics
71 View}.
72
73 Topics:
74
75 \tableofcontents
76
77 \section1 The Graphics View Architecture
78
79 Graphics View provides an item-based approach to model-view programming,
80 much like InterView's convenience classes QTableView, QTreeView and
81 QListView. Several views can observe a single scene, and the scene
82 contains items of varying geometric shapes.
83
84 \section2 The Scene
85
86 QGraphicsScene provides the Graphics View scene. The scene has the
87 following responsibilities:
88
89 \list
90 \o Providing a fast interface for managing a large number of items
91 \o Propagating events to each item
92 \o Managing item state, such as selection and focus handling
93 \o Providing untransformed rendering functionality; mainly for printing
94 \endlist
95
96 The scene serves as a container for QGraphicsItem objects. Items are
97 added to the scene by calling QGraphicsScene::addItem(), and then
98 retrieved by calling one of the many item discovery functions.
99 QGraphicsScene::items() and its overloads return all items contained
100 by or intersecting with a point, a rectangle, a polygon or a general
101 vector path. QGraphicsScene::itemAt() returns the topmost item at a
102 particular point. All item discovery functions return the items in
103 descending stacking order (i.e., the first returned item is topmost,
104 and the last item is bottom-most).
105
106 \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 0
107
108 QGraphicsScene's event propagation architecture schedules scene events
109 for delivery to items, and also manages propagation between items. If
110 the scene receives a mouse press event at a certain position, the
111 scene passes the event on to whichever item is at that position.
112
113 QGraphicsScene also manages certain item states, such as item
114 selection and focus. You can select items on the scene by calling
115 QGraphicsScene::setSelectionArea(), passing an arbitrary shape. This
116 functionality is also used as a basis for rubberband selection in
117 QGraphicsView. To get the list of all currently selected items, call
118 QGraphicsScene::selectedItems(). Another state handled by
119 QGraphicsScene is whether or not an item has keyboard input focus. You
120 can set focus on an item by calling QGraphicsScene::setFocusItem() or
121 QGraphicsItem::setFocus(), or get the current focus item by calling
122 QGraphicsScene::focusItem().
123
124 Finally, QGraphicsScene allows you to render parts of the scene into a
125 paint device through the QGraphicsScene::render() function. You can
126 read more about this in the Printing section later in this document.
127
128 \section2 The View
129
130 QGraphicsView provides the view widget, which visualizes the contents
131 of a scene. You can attach several views to the same scene, to provide
132 several viewports into the same data set. The view widget is a scroll
133 area, and provides scroll bars for navigating through large scenes. To
134 enable OpenGL support, you can set a QGLWidget as the viewport by
135 calling QGraphicsView::setViewport().
136
137 \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 1
138
139 The view receives input events from the keyboard and mouse, and
140 translates these to scene events (converting the coordinates used