|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the documentation of the Qt Toolkit. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
38 ** $QT_END_LICENSE$ |
|
39 ** |
|
40 ****************************************************************************/ |
|
41 |
|
42 /*! |
|
43 \example itemviews/frozencolumn |
|
44 \title Frozen Column Example |
|
45 |
|
46 This example demonstrates how to freeze a column within a QTableView. |
|
47 |
|
48 \image frozencolumn-example.png "Screenshot of the example" |
|
49 |
|
50 We use Qt's model/view framework to implement a table with its first |
|
51 column frozen. This technique can be aplied to several columns or rows, |
|
52 as long as they are on the edge of the table. |
|
53 |
|
54 The model/view framework allows for one model to be displayed in different |
|
55 ways using multiple views. For this example, we use two views on the same |
|
56 model - two \l {QTableView}{table views} sharing one model. The frozen |
|
57 column is a child of the main tableview, and we provide the desired visual |
|
58 effect using an overlay technique which will be described step by step in |
|
59 the coming sections. |
|
60 |
|
61 \image frozencolumn-tableview.png |
|
62 |
|
63 |
|
64 \section1 FreezeTableWidget Class Definition |
|
65 |
|
66 The \c FreezeTableWidget class has a constructor and a destructor. Also, it |
|
67 has two private members: the table view that we will use as an overlay, and |
|
68 the shared model for both table views. Two slots are added to help keep the |
|
69 section sizes in sync, as well as a function to readjust the frozen |
|
70 column's geometry. In addition, we reimplement two functions: |
|
71 \l{QAbstractItemView::}{resizeEvent()} and \l{QTableView::}{moveCursor()}. |
|
72 |
|
73 \snippet examples/itemviews/frozencolumn/freezetablewidget.h Widget definition |
|
74 |
|
75 \note QAbstractItemView is \l{QTableView}'s ancestor. |
|
76 |
|
77 |
|
78 \section1 FreezeTableWidget Class Implementation |
|
79 |
|
80 The constructor takes \a model as an argument and creates a table view that |
|
81 we will use to display the frozen column. Then, within the constructor, we |
|
82 invoke the \c init() function to set up the frozen column. Finally, we |
|
83 connect the \l{QHeaderView::sectionResized()} signals (for horizontal and |
|
84 vertical headers) to the appropriate slots. This ensures that our frozen |
|
85 column's sections are in sync with the headers. We also connect the |
|
86 vertical scrollbars together so that the frozen column scrolls vertically |
|
87 with the rest of our table. |
|
88 |
|
89 \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp constructor |
|
90 |
|
91 |
|
92 In the \c init() function, we ensure that the overlay table view |
|
93 responsible for displaying the frozen column, is set up properly. This |
|
94 means that this table view, \c frozenTableView, has to have the same model |
|
95 as the main table view. However, the difference here is: \c frozenTableView's |
|
96 only visible column is its first column; we hide the others using |
|
97 \l{QTableView::}{setColumnHidden()} |
|
98 |
|
99 \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp init part1 |
|
100 |
|
101 |
|
102 In terms of the frozen column's z-order, we stack it on top of the |
|
103 viewport. This is achieved by calling \l{QWidget::}{stackUnder()} on the |
|
104 viewport. For appearance's sake, we prevent the column from stealing focus |
|
105 from the main tableview. Also, we make sure that both views share the same |
|
106 selection model, so only one cell can be selected at a time. A few other |
|
107 tweaks are done to make our application look good and behave consistently |
|
108 with the main tableview. Note that we called \c updateFrozenTableGeometry() |
|
109 to make the column occupy the correct spot. |
|
110 |
|
111 \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp init part2 |
|
112 |
|
113 When you resize the frozen column, the same column on the main table view |
|
114 must resize accordingly, to provide seamless integration. This is |
|
115 accomplished by getting the new size of the column from the \c newSize |
|
116 value from the \l{QHeaderView::}{sectionResized()} signal, emitted by both |
|
117 the horizontal and vertical header. |
|
118 |
|
119 \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp sections |
|
120 |
|
121 Since the width of the frozen column is modified, we adjust the geometry of |
|
122 the widget accordingly by invoking \c updateFrozenTableGeometry(). This |
|
123 function is further explained below. |
|
124 |
|
125 In our reimplementation of QTableView::resizeEvent(), we call |
|
126 \c updateFrozenTableGeometry() after invoking the base class |
|
127 implementation. |
|
128 |
|
129 \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp resize |
|
130 |
|
131 When navigating around the table with the keyboard, we need to ensure that |
|
132 the current selection does not disappear behind the frozen column. To |
|
133 synchronize this, we reimplement QTableView::moveCursor() and adjust the |
|
134 scrollbar positions if needed, after calling the base class implementation. |
|
135 |
|
136 \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp navigate |
|
137 |
|
138 The frozen column's geometry calculation is based on the geometry of the |
|
139 table underneath, so it always appears in the right place. Using the |
|
140 QFrame::frameWidth() function helps to calculate this geometry correctly, |
|
141 no matter which style is used. We rely on the geometry of the viewport and |
|
142 headers to set the boundaries for the frozen column. |
|
143 |
|
144 \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp geometry |
|
145 |
|
146 */ |
|
147 |