/****************************************************************************

**

** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the documentation of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** 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.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

    \example itemviews/frozencolumn

    \title Frozen Column Example

    This example demonstrates how to freeze a column within a QTableView.

    \image frozencolumn-example.png "Screenshot of the example"

    We use Qt's model/view framework to implement a table with its first

    column frozen. This technique can be aplied to several columns or rows,

    as long as they are on the edge of the table.

    The model/view framework allows for one model to be displayed in different

    ways using multiple views. For this example, we use two views on the same

    model - two \l {QTableView}{table views} sharing one model. The frozen

    column is a child of the main tableview, and we provide the desired visual

    effect using an overlay technique which will be described step by step in

    the coming sections.

    \image frozencolumn-tableview.png

    \section1 FreezeTableWidget Class Definition

    The \c FreezeTableWidget class has a constructor and a destructor. Also, it

    has two private members: the table view that we will use as an overlay, and

    the shared model for both table views. Two slots are added to help keep the

    section sizes in sync, as well as a function to readjust the frozen

    column's geometry. In addition, we reimplement two functions:

    \l{QAbstractItemView::}{resizeEvent()} and \l{QTableView::}{moveCursor()}.

    \snippet examples/itemviews/frozencolumn/freezetablewidget.h Widget definition

    \note QAbstractItemView is \l{QTableView}'s ancestor.

    \section1 FreezeTableWidget Class Implementation

    The constructor takes \a model as an argument and creates a table view that

    we will use to display the frozen column. Then, within the constructor, we

    invoke the \c init() function to set up the frozen column. Finally, we

    connect the \l{QHeaderView::sectionResized()} signals (for horizontal and

    vertical headers) to the appropriate slots. This ensures that our frozen

    column's sections are in sync with the headers. We also connect the

    vertical scrollbars together so that the frozen column scrolls vertically

    with the rest of our table.

    \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp constructor

    In the \c init() function, we ensure that the overlay table view

    responsible for displaying the frozen column, is set up properly. This

    means that this table view, \c frozenTableView, has to have the same model

    as the main table view. However, the difference here is: \c frozenTableView's

    only visible column is its first column; we hide the others using

    \l{QTableView::}{setColumnHidden()}

    \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp init part1

    In terms of the frozen column's z-order, we stack it on top of the

    viewport. This is achieved by calling \l{QWidget::}{stackUnder()} on the

    viewport. For appearance's sake, we prevent the column from stealing focus

    from the main tableview. Also, we make sure that both views share the same

    selection model, so only one cell can be selected at a time. A few other

    tweaks are done to make our application look good and behave consistently

    with the main tableview. Note that we called \c updateFrozenTableGeometry()

    to make the column occupy the correct spot.

    \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp init part2

    When you resize the frozen column, the same column on the main table view

    must resize accordingly, to provide seamless integration. This is

    accomplished by getting the new size of the column from the \c newSize

    value from the \l{QHeaderView::}{sectionResized()} signal, emitted by both

    the horizontal and vertical header.

    \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp sections

    Since the width of the frozen column is modified, we adjust the geometry of

    the widget accordingly by invoking \c updateFrozenTableGeometry(). This

    function is further explained below.

    In our reimplementation of QTableView::resizeEvent(), we call

    \c updateFrozenTableGeometry() after invoking the base class

    implementation.

    \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp resize

    When navigating around the table with the keyboard, we need to ensure that

    the current selection does not disappear behind the frozen column. To

    synchronize this, we reimplement QTableView::moveCursor() and adjust the

    scrollbar positions if needed, after calling the base class implementation.

    \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp navigate

    The frozen column's geometry calculation is based on the geometry of the

    table underneath, so it always appears in the right place. Using the

    QFrame::frameWidth() function helps to calculate this geometry correctly,

    no matter which style is used. We rely on the geometry of the viewport and

    headers to set the boundaries for the frozen column.

    \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp geometry

*/