doc/src/examples/frozencolumn.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \example itemviews/frozencolumn
  30     \title Frozen Column Example
  31
  32     \brief The Frozen Column 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