src/frontends/qt2/qgridview.C

   1 /****************************************************************************
   2 ** $Id: qgridview.C,v 1.3 2003/08/23 00:16:39 leeming Exp $
   3 **
   4 ** Implementation of QGridView class
   5 **
   6 ** Created: 010523
   7 **
   8 ** Copyright (C) 1992-2001 Trolltech AS.  All rights reserved.
   9 **
  10 ** This file is part of the widgets module of the Qt GUI Toolkit.
  11 **
  12 ** This file may be distributed under the terms of the Q Public License
  13 ** as defined by Trolltech AS of Norway and appearing in the file
  14 ** LICENSE.QPL included in the packaging of this file.
  15 **
  16 ** This file may be distributed and/or modified under the terms of the
  17 ** GNU General Public License version 2 as published by the Free Software
  18 ** Foundation and appearing in the file LICENSE.GPL included in the
  19 ** packaging of this file.
  20 **
  21 ** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
  22 ** licenses may use this file in accordance with the Qt Commercial License
  23 ** Agreement provided with the Software.
  24 **
  25 ** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
  26 ** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  27 **
  28 ** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
  29 **   information about Qt Commercial License Agreements.
  30 ** See http://www.trolltech.com/qpl/ for QPL licensing information.
  31 ** See http://www.trolltech.com/gpl/ for GPL licensing information.
  32 **
  33 ** Contact info@trolltech.com if any conditions of this licensing are
  34 ** not clear to you.
  35 **
  36 **********************************************************************/
  37
  38
  39 #include <config.h>
  40
  41 #include "qgridview.h"
  42
  43 #ifndef QT_NO_GRIDVIEW
  44
  45 #include <qpainter.h>
  46
  47 /*!
  48   \class QGridView qgridview.h
  49   \brief The QGridView class provides an abstract base for fixed-size
  50   grids.
  51
  52   \ingroup abstractwidgets
  53
  54   A grid view consists of a number of abstract cells organized in rows
  55   and columns. The cells have a fixed size and are identified with a
  56   row index and a column index. The top-left cell is in row 0, column
  57   0. The bottom-right cell is in row numRows()-1, column numCols()-1.
  58
  59   You can define \l numRows, \l numCols, \l cellWidth and
  60   \l cellHeight. Reimplement the pure virtual function paintCell() to
  61   draw the content of a cell.
  62
  63   With ensureCellVisible(), you can ensure a certain cell is
  64   visible. With rowAt() and columnAt() you can find a cell based on
  65   the given x- and y-coordinates.
  66
  67   If you need to monitor changes to the grid's dimensions (i.e. when
  68   numRows or numCols is changed), reimplement the dimensionChange()
  69   change handler.
  70
  71   Note: the row, column indices are always given in the order, row
  72   (vertical offset) then column (horizontal offset). This order is the
  73   opposite of all pixel operations, which are given in the order x
  74   (horizontal offset), y (vertical offset).
  75
  76   QGridView is a very simple abstract class based on QScrollView. It
  77   is designed to simplify the task of drawing many cells of the same
  78   size in a potentially scrollable canvas. If you need rows and
  79   columns in different sizes, use a QTable instead. If you need a
  80   simple list of items, use a QListBox. If you need to present
  81   hierachical data use a QListView, and if you need random objects at
  82   random positions, consider using either a QIconView or a QCanvas.
  83
  84 */
  85
  86
  87 /*!
  88   Constructs a grid view.
  89
  90   The \a parent, \a name and widget flag, \a f, arguments are passed to the
  91   QScrollView constructor.
  92 */
  93 QGridView::QGridView( QWidget *parent, const char *name, WFlags f )
  94     :QScrollView( parent, name ,f ),nrows(5),ncols(5),cellw(12),cellh(12)
  95 {
  96     viewport()->setBackgroundMode( PaletteBase );
  97     setBackgroundMode( PaletteBackground );
  98     viewport()->setFocusProxy( this );
  99 }
 100
 101 /*!
 102   Destroys the grid view.
 103 */
 104 QGridView::~QGridView()
 105 {
 106 }
 107
 108 void QGridView::updateGrid()
 109 {
 110     resizeContents( ncols * cellw, nrows * cellh );
 111 }
 112
 113 /*! \property QGridView::numRows
 114   \brief The number of rows in the grid
 115
 116   \sa numCols
 117 */
 118 void QGridView::setNumRows( int numRows )
 119 {
 120     int oldnrows = nrows;
 121     nrows = numRows;
 122     dimensionChange( oldnrows, ncols );
 123     updateGrid();
 124 }
 125
 126 /*! \property QGridView::numCols
 127   \brief The number of columns in the grid
 128
 129   \sa numRows
 130 */
 131 void QGridView::setNumCols( int numCols )
 132 {
 133     int oldncols = ncols;
 134     ncols = numCols;
 135     dimensionChange( nrows, oldncols );
 136     updateGrid();
 137 }
 138
 139 /*! \property QGridView::cellWidth
 140   \brief The width of a grid column
 141
 142   All columns in a grid view have the same width.
 143
 144   \sa cellHeight
 145 */
 146 void QGridView::setCellWidth( int cellWidth )
 147 {
 148     cellw = cellWidth;
 149     updateGrid();
 150     updateContents( contentsX(), contentsY(), visibleWidth(), visibleHeight() );
 151
 152 }
 153
 154 /*! \property QGridView::cellHeight
 155   \brief The height of a grid row
 156
 157   All rows in a grid view have the same height.
 158
 159   \sa cellWidth
 160 */
 161 void QGridView::setCellHeight( int cellHeight )
 162 {
 163     cellh = cellHeight;
 164     updateGrid();
 165     updateContents( contentsX(), contentsY(), visibleWidth(), visibleHeight() );
 166
 167 }
 168
 169 /*!
 170   Returns the geometry of cell (\a row, \a column) in the content
 171   coordinate system.
 172
 173   \sa cellRect()
 174  */
 175 QRect QGridView::cellGeometry( int row, int column )
 176 {
 177     QRect r;
 178     if ( row >= 0 && row < nrows && column >= 0 && column < ncols )
 179         r.setRect( cellw * column, cellh * row, cellw, cellh );
 180     return r;
 181 }
 182
 183 /*!  Repaints cell (\a row, \a column).
 184
 185   If \a erase is TRUE, Qt erases the area of the cell before the
 186   paintCell() call; otherwise no erasing takes place.
 187
 188   \sa QWidget::repaint()
 189  */
 190 void QGridView::repaintCell( int row, int column, bool erase )
 191 {
 192     repaintContents( cellGeometry( row, column ), erase );
 193 }
 194
 195 /*!  Updates cell (\a row, \a column).
 196
 197   \sa QWidget::update()
 198  */
 199 void QGridView::updateCell( int row, int column )
 200 {
 201     updateContents( cellGeometry( row, column ) );
 202 }
 203
 204 /*!
 205   Ensure cell (\a row, \a column) is visible, scrolling the grid view
 206   if necessary.
 207  */
 208 void QGridView::ensureCellVisible( int row, int column )
 209 {
 210     QRect r = cellGeometry( row, column );
 211     ensureVisible( r.x(), r.y(), r.width(), r.height() );
 212 }
 213
 214 /*! This function fills the \a cw pixels wide and \a ch pixels high
 215   rectangle starting at position (\a cx, \a cy) with the
 216   background color using the painter \a p.
 217
 218   paintEmptyArea() is invoked by drawContents() to erase
 219   or fill unused areas.
 220 */
 221
 222 void QGridView::paintEmptyArea( QPainter *p, int cx ,int cy, int cw, int ch)
 223 {
 224     if ( gridSize().width() >= contentsWidth() && gridSize().height() >= contentsHeight() )
 225         return;
 226     // Region of the rect we should draw
 227     contentsToViewport( cx, cy, cx, cy );
 228     QRegion reg( QRect( cx, cy, cw, ch ) );
 229     // Subtract the table from it
 230     reg = reg.subtract( QRect( contentsToViewport( QPoint( 0, 0 ) ), gridSize() ) );
 231
 232     // And draw the rectangles (transformed as needed)
 233     QArray<QRect> r = reg.rects();
 234     const QBrush &brush = colorGroup().brush(QColorGroup::Background);
 235     for ( int i = 0; i < (int)r.count(); ++i)
 236         p->fillRect( r[ i ], brush );
 237 }
 238
 239 /*!\reimp
 240  */
 241 void QGridView::drawContents( QPainter *p, int cx, int cy, int cw, int ch )
 242 {
 243     int colfirst = columnAt( cx );
 244     int collast = columnAt( cx + cw );
 245     int rowfirst = rowAt( cy );
 246     int rowlast = rowAt( cy + ch );
 247
 248     if ( rowfirst == -1 || colfirst == -1 ) {
 249         paintEmptyArea( p, cx, cy, cw, ch );
 250         return;
 251     }
 252
 253     if ( collast < 0 || collast >= ncols )
 254         collast = ncols-1;
 255     if ( rowlast < 0 || rowlast >= nrows )
 256         rowlast = nrows-1;
 257
 258     // Go through the rows
 259     for ( int r = rowfirst; r <= rowlast; ++r ) {
 260         // get row position and height
 261         int rowp = r * cellh;
 262
 263         // Go through the columns in the row r
 264         // if we know from where to where, go through [colfirst, collast],
 265         // else go through all of them
 266         for ( int c = colfirst; c <= collast; ++c ) {
 267             // get position and width of column c
 268             int colp = c * cellw;
 269             // Translate painter and draw the cell
 270             p->translate( colp, rowp );
 271             paintCell( p, r, c );
 272             p->translate( -colp, -rowp );
 273         }
 274     }
 275
 276     // Paint empty rects
 277     paintEmptyArea( p, cx, cy, cw, ch );
 278 }
 279
 280 /*!
 281   \reimp
 282
 283   (Implemented to get rid of a compiler warning.)
 284 */
 285 void QGridView::drawContents( QPainter * )
 286 {
 287 }
 288
 289 /*! \fn void QGridView::dimensionChange( int oldNumRows, int oldNumCols )
 290
 291   This change handler is called whenever any of the grid's dimensions
 292   changes. \a oldNumRows and \a oldNumCols contain the old dimensions,
 293   numRows() and numCols() contain the new dimensions.
 294  */
 295 void QGridView::dimensionChange( int, int ) {}
 296
 297
 298
 299 /*! \fn int QGridView::rowAt( int y ) const
 300
 301   Returns the number of the row at position \a y. \a y must be given in
 302   content coordinates.
 303
 304   \sa columnAt()
 305  */
 306
 307 /*! \fn int QGridView::columnAt( int x ) const
 308
 309   Returns the number of the column at position \a x. \a x must be
 310   given in content coordinates.
 311
 312   \sa rowAt()
 313  */
 314
 315 /*!
 316   \fn void QGridView::paintCell( QPainter *p, int row, int col )
 317
 318   This pure virtual function is called to paint the single cell at
 319   (\a row, \a col) using painter \a p. The painter must be open when
 320   paintCell() is called and must remain open.
 321
 322   The coordinate system is \link QPainter::translate() translated \endlink
 323   so that the origin is at the top-left corner of the cell to be
 324   painted, i.e. \e cell coordinates.  Do not scale or shear the coordinate
 325   system (or if you do, restore the transformation matrix before you
 326   return).
 327
 328   The painter is not clipped by default in order to get maximum
 329   efficiency. If you want clipping, use
 330
 331   \code
 332     p->setClipRect( cellRect(), QPainter::CoordPainter );
 333     //... your drawing code
 334     p->setClipping( FALSE );
 335
 336  \endcode
 337
 338 */
 339
 340 /*! \fn  QRect QGridView::cellRect() const
 341
 342   Returns the geometry of a cell in a cell's coordinate system. This
 343   is a convenience function useful in paintCell(). It is equivalent to
 344   QRect( 0, 0, cellWidth(), cellHeight() ).
 345
 346   \sa cellGeometry()
 347
 348  */
 349
 350 /*!\fn  QSize QGridView::gridSize() const
 351
 352   Returns the size of the grid in pixels.
 353
 354  */
 355
 356 #endif // QT_NO_GRIDVIEW