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