Doc - Adding Pierre Rossi's frozen column example

Reviewed-By: TrustMe

4 files changed, 387 insertions, 0 deletions

diff --git a/doc/src/diagrams/frozencolumn/tableview-overlay.svg b/doc/src/diagrams/frozencolumn/tableview-overlay.svg
new file mode 100644
index 0000000..fafdc23
--- /dev/null
+++ b/doc/src/diagrams/frozencolumn/tableview-overlay.svg
@@ -0,0 +1,240 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="744.09448819"
+   height="1052.3622047"
+   id="svg2"
+   sodipodi:version="0.32"
+   inkscape:version="0.46"
+   sodipodi:docname="table.svg"
+   inkscape:output_extension="org.inkscape.output.svg.inkscape">
+  <defs
+     id="defs4">
+    <inkscape:perspective
+       sodipodi:type="inkscape:persp3d"
+       inkscape:vp_x="0 : 526.18109 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_z="744.09448 : 526.18109 : 1"
+       inkscape:persp3d-origin="372.04724 : 350.78739 : 1"
+       id="perspective10" />
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     gridtolerance="10000"
+     guidetolerance="10"
+     objecttolerance="10"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.98994949"
+     inkscape:cx="388.18807"
+     inkscape:cy="731.8625"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     inkscape:window-width="1920"
+     inkscape:window-height="1125"
+     inkscape:window-x="-4"
+     inkscape:window-y="-4" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1">
+    <rect
+       style="fill:#f2f2f2;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       id="rect2385"
+       width="517.14294"
+       height="358.57147"
+       x="97.142853"
+       y="190.93361"
+       ry="2.5253813" />
+    <rect
+       style="opacity:1;fill:#808080;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker:none;marker-start:none;marker-mid:none;marker-end:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;visibility:visible;display:inline;overflow:visible;enable-background:accumulate"
+       id="rect2387"
+       width="51.42857"
+       height="355.71429"
+       x="98.571426"
+       y="193.79076" />
+    <rect
+       style="opacity:1;fill:#808080;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker:none;marker-start:none;marker-mid:none;marker-end:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;visibility:visible;display:inline;overflow:visible;enable-background:accumulate"
+       id="rect3159"
+       width="515.71429"
+       height="12.857142"
+       x="98.571426"
+       y="192.36218" />
+    <rect
+       style="opacity:1;fill:#b3b3b3;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker:none;marker-start:none;marker-mid:none;marker-end:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;visibility:visible;display:inline;overflow:visible;enable-background:accumulate"
+       id="rect3161"
+       width="464.28571"
+       height="10"
+       x="150"
+       y="538.07648" />
+    <rect
+       style="opacity:1;fill:#b3b3b3;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker:none;marker-start:none;marker-mid:none;marker-end:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;visibility:visible;display:inline;overflow:visible;enable-background:accumulate"
+       id="rect3163"
+       width="10.00007"
+       height="330.00003"
+       x="603.57141"
+       y="206.6479" />
+    <rect
+       style="opacity:1;fill:#99ff55;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.10637689px;stroke-linecap:butt;stroke-linejoin:miter;marker:none;marker-start:none;marker-mid:none;marker-end:none;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;visibility:visible;display:inline;overflow:visible;enable-background:accumulate"
+       id="rect3167"
+       width="84.8367"
+       height="344.89362"
+       x="150.47162"
+       y="192.41537"
+       ry="3.0295234" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 340.92648,197.77313 L 377.79705,175.0447 L 405.07117,175.0447"
+       id="path3193" />
+    <text
+       xml:space="preserve"
+       style="font-size:20px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="407.09146"
+       y="177.57007"
+       id="text3195"><tspan
+         sodipodi:role="line"
+         x="407.09146"
+         y="177.57007"
+         id="tspan3199">horizontal header</tspan></text>
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 320.72343,426.0676 L 232.84016,619.51182 L 209.10158,620.01689"
+       id="path3205" />
+    <text
+       xml:space="preserve"
+       style="font-size:20px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="117.1777"
+       y="622.5423"
+       id="text3207"><tspan
+         sodipodi:role="line"
+         id="tspan3209"
+         x="117.1777"
+         y="622.5423">viewport</tspan></text>
+    <path
+       sodipodi:type="arc"
+       style="fill:#000000;fill-opacity:1"
+       id="path3215"
+       sodipodi:cx="320.78656"
+       sodipodi:cy="426.0676"
+       sodipodi:rx="1.8309015"
+       sodipodi:ry="1.8940361"
+       d="M 322.61746,426.0676 A 1.8309015,1.8940361 0 1 1 318.95566,426.0676 A 1.8309015,1.8940361 0 1 1 322.61746,426.0676 z" />
+    <path
+       sodipodi:type="arc"
+       style="fill:#000000;fill-opacity:1"
+       id="path3217"
+       sodipodi:cx="341.24216"
+       sodipodi:cy="197.64687"
+       sodipodi:rx="1.1995561"
+       sodipodi:ry="1.1364216"
+       d="M 342.44171,197.64687 A 1.1995561,1.1364216 0 1 1 340.0426,197.64687 A 1.1995561,1.1364216 0 1 1 342.44171,197.64687 z" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 109.09647,228.07771 L 137.38075,156.35687 L 176.7767,156.35687"
+       id="path3219" />
+    <text
+       xml:space="preserve"
+       style="font-size:20px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="177.94707"
+       y="158.76218"
+       id="text3221"><tspan
+         sodipodi:role="line"
+         x="177.94707"
+         y="158.76218"
+         id="tspan3229">vertical header</tspan></text>
+    <path
+       sodipodi:type="arc"
+       style="fill:#000000;fill-opacity:1"
+       id="path3233"
+       sodipodi:cx="109.03334"
+       sodipodi:cy="228.26711"
+       sodipodi:rx="1.4520943"
+       sodipodi:ry="1.3258252"
+       d="M 110.48543,228.26711 A 1.4520943,1.3258252 0 1 1 107.58125,228.26711 A 1.4520943,1.3258252 0 1 1 110.48543,228.26711 z" />
+    <path
+       sodipodi:type="arc"
+       id="path3239"
+       style="fill:#000000;stroke:none"
+       sodipodi:cx="608.61688"
+       sodipodi:cy="466.47372"
+       sodipodi:rx="1.5"
+       sodipodi:ry="1.5"
+       d="M 610.11688,466.47372 A 1.5,1.5 0 1 1 607.11688,466.47372 A 1.5,1.5 0 1 1 610.11688,466.47372 z" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 608.61691,466.47371 C 679.32759,523.04225 576.29203,608.40014 576.29203,608.40014 C 576.29203,608.40014 594.00783,590.22921 587.58437,566.25655 C 581.16091,542.28388 564.87674,543.54891 564.87674,543.54891 L 565.68543,542.74022"
+       id="path3241" />
+    <path
+       sodipodi:type="arc"
+       id="path3243"
+       style="fill:#000000;stroke:none"
+       sodipodi:cx="565.18036"
+       sodipodi:cy="543.49786"
+       sodipodi:rx="1.5"
+       sodipodi:ry="1.5"
+       d="M 566.68036,543.49786 A 1.5,1.5 0 1 1 563.68036,543.49786 A 1.5,1.5 0 1 1 566.68036,543.49786 z" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 576.78572,607.8979 C 576.78572,607.8979 585.44643,599.23718 576.78572,607.8979 z"
+       id="path3247" />
+    <text
+       xml:space="preserve"
+       style="font-size:20px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="435.89288"
+       y="615.66577"
+       id="text3251"><tspan
+         sodipodi:role="line"
+         id="tspan3253"
+         x="435.89288"
+         y="615.66577">scrollbars</tspan></text>
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 536.70668,615.02926 L 559.18257,614.96613 C 559.18257,614.96613 569.50507,615.1871 576.48143,608.21073"
+       id="path3257" />
+    <path
+       sodipodi:type="arc"
+       id="path3261"
+       style="fill:#000000;stroke:none"
+       sodipodi:cx="198.74751"
+       sodipodi:cy="310.65768"
+       sodipodi:rx="1.5"
+       sodipodi:ry="1.5"
+       d="M 200.24751,310.65768 A 1.5,1.5 0 1 1 197.24751,310.65768 A 1.5,1.5 0 1 1 200.24751,310.65768 z" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 198.74751,310.65768 C 301.278,280.60564 301.278,280.60564 301.278,280.60564 L 333.85542,280.60564"
+       id="path3263" />
+    <text
+       xml:space="preserve"
+       style="font-size:20px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="337.64349"
+       y="281.36328"
+       id="text3265"><tspan
+         sodipodi:role="line"
+         id="tspan3267"
+         x="337.64349"
+         y="281.36328">second QTableView</tspan></text>
+  </g>
+</svg>
diff --git a/doc/src/examples/frozencolumn.qdoc b/doc/src/examples/frozencolumn.qdoc
new file mode 100644
index 0000000..e5a3b59
--- /dev/null
+++ b/doc/src/examples/frozencolumn.qdoc
@@ -0,0 +1,147 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@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
+
+*/
+
diff --git a/doc/src/images/frozencolumn-example.png b/doc/src/images/frozencolumn-example.png
new file mode 100644
index 0000000..66b5c10
--- /dev/null
+++ b/doc/src/images/frozencolumn-example.png
diff --git a/doc/src/images/frozencolumn-tableview.png b/doc/src/images/frozencolumn-tableview.png
new file mode 100644
index 0000000..d829ff5
--- /dev/null
+++ b/doc/src/images/frozencolumn-tableview.png