summaryrefslogtreecommitdiffstats
path: root/doc/src
diff options
context:
space:
mode:
authorKavindra Devi Palaraja <kavindra.palaraja@nokia.com>2009-06-23 08:33:05 (GMT)
committerKavindra Devi Palaraja <kavindra.palaraja@nokia.com>2009-06-23 08:33:05 (GMT)
commit764a3dd99072cde27fdf7887cd40f4db54796781 (patch)
treee456fc51052bc752ebceaaa9e6404651b464b78c /doc/src
parentaf6fb86be2fc711cbaf10a482ad84d6f207f5d27 (diff)
downloadQt-764a3dd99072cde27fdf7887cd40f4db54796781.zip
Qt-764a3dd99072cde27fdf7887cd40f4db54796781.tar.gz
Qt-764a3dd99072cde27fdf7887cd40f4db54796781.tar.bz2
Doc - Adding Pierre Rossi's frozen column example
Reviewed-By: TrustMe
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/diagrams/frozencolumn/tableview-overlay.svg240
-rw-r--r--doc/src/examples/frozencolumn.qdoc147
-rw-r--r--doc/src/images/frozencolumn-example.pngbin0 -> 41102 bytes
-rw-r--r--doc/src/images/frozencolumn-tableview.pngbin0 -> 22942 bytes
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
Binary files differ
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
Binary files differ