1QTableItem(3qt) QTableItem(3qt)
2
6 QTableItem - The cell content for QTable cells
7
9 #include <qtable.h>
10 Inherits Qt.
12 Inherited by QComboTableItem and QCheckTableItem.
14 Public Members
16 enum EditType { Never, OnTyping, WhenCurrent, Always }
17 QTableItem ( QTable * table, EditType et )
18 QTableItem ( QTable * table, EditType et, const QString & text )
19 QTableItem ( QTable * table, EditType et, const QString & text, const
20 QPixmap & p )
21 virtual ~QTableItem ()
22 virtual QPixmap pixmap () const
23 virtual QString text () const
24 virtual void setPixmap ( const QPixmap & p )
25 virtual void setText ( const QString & str )
26 QTable * table () const
27 virtual int alignment () const
28 virtual void setWordWrap ( bool b )
29 bool wordWrap () const
30 EditType editType () const
31 virtual QWidget * createEditor () const
32 virtual void setContentFromEditor ( QWidget * w )
33 virtual void setReplaceable ( bool b )
34 bool isReplaceable () const
35 virtual QString key () const
36 virtual QSize sizeHint () const
37 virtual void setSpan ( int rs, int cs )
38 int rowSpan () const
39 int colSpan () const
40 virtual void setRow ( int r )
41 virtual void setCol ( int c )
42 int row () const
43 int col () const
44 virtual void paint ( QPainter * p, const QColorGroup & cg, const QRect
45 & cr, bool selected )
46 virtual void setEnabled ( bool b )
47 bool isEnabled () const
48 virtual int rtti () const
49
51 The QTableItem class provides the cell content for QTable cells.
52 For many applications QTableItems are ideal for presenting and editing
54 the contents of QTable cells. In situations where you need to create
55 very large tables you may prefer an alternative approach to using
56 QTableItems: see the notes on large tables.
57 A QTableItem contains a cell's data, by default, a string and a pixmap.
59 The table item also holds the cell's display size and how the data
60 should be aligned. The table item specifies the cell's EditType and the
61 editor used for in-place editing (by default a QLineEdit). If you want
62 checkboxes use QCheckTableItem, and if you want comboboxes use
63 QComboTableItem. The EditType (set in the constructor) determines
64 whether the cell's contents may be edited.
65 If a pixmap is specified it is displayed to the left of any text. You
67 can change the text or pixmap with setText() and setPixmap()
68 respectively. For text you can use setWordWrap().
69 When sorting table items the key() function is used; by default this
71 returns the table item's text(). Reimplement key() to customize how
72 your table items will sort.
73 Table items are inserted into a table using QTable::setItem(). If you
75 insert an item into a cell that already contains a table item the
76 original item will be deleted.
77 Example:
79 for ( int row = 0; row < table->numRows(); row++ ) {
81 for ( int col = 0; col < table->numCols(); col++ ) {
82 table->setItem( row, col,
83 new QTableItem( table, QTableItem::WhenCurrent, QString::number( row * col ) ) );
84 }
85 }
86 You can move a table item from one cell to another, in the same or a
88 different table, using QTable::takeItem() and QTable::setItem() but see
89 also QTable::swapCells().
90 Table items can be deleted with delete in the standard way; the table
92 and cell will be updated accordingly.
93 Note, that if you have a table item that is not currently in a table
95 then anything you do to that item other than insert it into a table
96 will result in undefined behaviour.
97 Reimplement createEditor() and setContentFromEditor() if you want to
99 use your own widget instead of a QLineEdit for editing cell contents.
100 Reimplement paint() if you want to display custom content.
101 It is important to ensure that your custom widget can accept the
103 keyboard focus, so that the user can use the tab key to navigate the
104 table as normal. Therefore, if the widget returned by createEditor()
105 does not itself accept the keyboard focus, it is necessary to nominate
106 a child widget to do so on its behalf. For example, a QHBox with two
107 child QLineEdit widgets may use one of them to accept the keyboard
108 focus:
109 QWidget* MyTableItem::createEditor() const
111 {
112 QHBox* hbox = new QHBox( table()->viewport() );
113 hbox->setFocusProxy(new QLineEdit( hbox ));
114 new QLineEdit( hbox );
115 return hbox;
116 }
117 By default, table items may be replaced by new QTableItems during the
119 lifetime of a QTable. Therefore, if you create your own subclass of
120 QTableItem, and you want to ensure that this does not happen, you must
121 call setReplaceable(FALSE) in the constructor of your subclass.
122 <center>
124 [Image Omitted]
125 </center>
127 See also QCheckTableItem, QComboTableItem, and Advanced Widgets.
129 Member Type Documentation
132 This enum is used to define whether a cell is editable or read-only (in
133 conjunction with other settings), and how the cell should be displayed.
134 QTableItem::Always - The cell always looks editable.
136 Using this EditType ensures that the editor created with createEditor()
138 (by default a QLineEdit) is always visible. This has implications for
139 the alignment of the content: the default editor aligns everything
140 (even numbers) to the left whilst numerical values in the cell are by
141 default aligned to the right.
142 If a cell with the edit type Always looks misaligned you could
144 reimplement createEditor() for these items.
145 QTableItem::WhenCurrent - The cell looks editable only when it has
147 keyboard focus (see QTable::setCurrentCell()).
148 QTableItem::OnTyping - The cell looks editable only when the user types
150 in it or double-clicks it. It resembles the WhenCurrent functionality
151 but is, perhaps, nicer.
152 The OnTyping edit type is the default when QTableItem objects are
154 created by the convenience functions QTable::setText() and
155 QTable::setPixmap().
156 QTableItem::Never - The cell is not editable.
158 The cell is actually editable only if QTable::isRowReadOnly() is FALSE
160 for its row, QTable::isColumnReadOnly() is FALSE for its column, and
161 QTable::isReadOnly() is FALSE.
162 QComboTableItems have an isEditable() property. This property is used
164 to indicate whether the user may enter their own text or are restricted
165 to choosing one of the choices in the list. QComboTableItems may be
166 interacted with only if they are editable in accordance with their
167 EditType as described above.
168
171 Creates a table item that is a child of table table with no text. The
172 item has the EditType et.
173 The table item will use a QLineEdit for its editor, will not word-wrap
175 and will occupy a single cell. Insert the table item into a table with
176 QTable::setItem().
177 The table takes ownership of the table item, so a table item should not
179 be inserted into more than one table at a time.
180
182 Creates a table item that is a child of table table with text text. The
183 item has the EditType et.
184 The table item will use a QLineEdit for its editor, will not word-wrap
186 and will occupy a single cell. Insert the table item into a table with
187 QTable::setItem().
188 The table takes ownership of the table item, so a table item should not
190 be inserted into more than one table at a time.
191
193 const QPixmap & p )
194 Creates a table item that is a child of table table with text text and
195 pixmap p. The item has the EditType et.
196 The table item will display the pixmap to the left of the text. It will
198 use a QLineEdit for editing the text, will not word-wrap and will
199 occupy a single cell. Insert the table item into a table with
200 QTable::setItem().
201 The table takes ownership of the table item, so a table item should not
203 be inserted in more than one table at a time.
204
206 The destructor deletes this item and frees all allocated resources.
207 If the table item is in a table (i.e. was inserted with setItem()), it
209 will be removed from the table and the cell it occupied.
210
212 The alignment function returns how the text contents of the cell are
213 aligned when drawn. The default implementation aligns numbers to the
214 right and any other text to the left.
215 See also Qt::AlignmentFlags.
217
219 Returns the column where the table item is located. If the cell spans
220 multiple columns, this function returns the left-most column.
221 See also row() and setCol().
223 Example: table/bigtable/main.cpp.
225
227 Returns the column span of the table item, usually 1.
228 See also setSpan() and rowSpan().
230
232 This virtual function creates an editor which the user can interact
233 with to edit the cell's contents. The default implementation creates a
234 QLineEdit.
235 If the function returns 0, the cell is read-only.
237 The returned widget should preferably be invisible, ideally with
239 QTable::viewport() as parent.
240 If you reimplement this function you'll almost certainly need to
242 reimplement setContentFromEditor(), and may need to reimplement
243 sizeHint().
244 QWidget *ComboItem::createEditor() const
246 {
247 // create an editor - a combobox in our case
248 ( (ComboItem*)this )->cb = new QComboBox( table()->viewport() );
249 QObject::connect( cb, SIGNAL( activated( int ) ), table(), SLOT( doValueChanged() ) );
250 cb->insertItem( "Yes" );
251 cb->insertItem( "No" );
252 // and initialize it
253 cb->setCurrentItem( text() == "No" ? 1 : 0 );
254 return cb;
255 See also QTable::createEditor(), setContentFromEditor(),
257 QTable::viewport(), and setReplaceable().
258 Example: table/statistics/statistics.cpp.
260
262 Returns the table item's edit type.
263 This is set when the table item is constructed.
265 See also EditType and QTableItem().
267
269 Returns TRUE if the table item is enabled; otherwise returns FALSE.
270 See also setEnabled().
272
274 This function returns whether the contents of the cell may be replaced
275 with the contents of another table item. Regardless of this setting,
276 table items that span more than one cell may not have their contents
277 replaced by another table item.
278 (This differs from EditType because EditType is concerned with whether
280 the user is able to change the contents of a cell.)
281 See also setReplaceable() and EditType.
283
285 This virtual function returns the key that should be used for sorting.
286 The default implementation returns the text() of the relevant item.
287 See also QTable::sorting.
289
291 cr, bool selected ) [virtual]
292 This virtual function is used to paint the contents of an item using
293 the painter p in the rectangular area cr using the color group cg.
294 If selected is TRUE the cell is displayed in a way that indicates that
296 it is highlighted.
297 You don't usually need to use this function but if you want to draw
299 custom content in a cell you will need to reimplement it.
300 The painter passed to this function is translated so that 0, 0 is the
302 top-left corner of the item that is being painted.
303 Note that the painter is not clipped by default in order to get maximum
305 efficiency. If you want clipping, use
306 p->setClipRect( table()->cellRect(row, col), QPainter::ClipPainter );
308 //... your drawing code
309 p->setClipping( FALSE );
310 Example: table/statistics/statistics.cpp.
312
314 Returns the table item's pixmap or a null pixmap if no pixmap has been
315 set.
316 See also setPixmap() and text().
318
320 Returns the row where the table item is located. If the cell spans
321 multiple rows, this function returns the top-most row.
322 See also col() and setRow().
324 Example: table/bigtable/main.cpp.
326
328 Returns the row span of the table item, usually 1.
329 See also setSpan() and colSpan().
331
333 Returns the Run Time Type Identification value for this table item
334 which for QTableItems is 0.
335 When you create subclasses based on QTableItem make sure that each
337 subclass returns a unique rtti() value. It is advisable to use values
338 greater than 1000, preferably large random numbers, to allow for
339 extensions to this class.
340 See also QCheckTableItem::rtti() and QComboTableItem::rtti().
342 Reimplemented in QComboTableItem and QCheckTableItem.
344
346 Sets column c as the table item's column. Usually you will not need to
347 call this function.
348 If the cell spans multiple columns, this function sets the left-most
350 column and retains the width of the multi-cell table item.
351 See also col(), setRow(), and colSpan().
353
355 Whenever the content of a cell has been edited by the editor w, QTable
356 calls this virtual function to copy the new values into the QTableItem.
357 If you reimplement createEditor() and return something that is not a
359 QLineEdit you will need to reimplement this function.
360 void ComboItem::setContentFromEditor( QWidget *w )
362 {
363 // the user changed the value of the combobox, so synchronize the
364 // value of the item (its text), with the value of the combobox
365 if ( w->inherits( "QComboBox" ) )
366 setText( ( (QComboBox*)w )->currentText() );
367 else
368 QTableItem::setContentFromEditor( w );
369 See also QTable::setCellContentFromEditor().
371 Example: table/statistics/statistics.cpp.
373
375 If b is TRUE, the table item is enabled; if b is FALSE the table item
376 is disabled.
377 A disabled item doesn't respond to user interaction.
379 See also isEnabled().
381
383 Sets pixmap p to be this item's pixmap.
384 Note that setPixmap() does not update the cell the table item belongs
386 to. Use QTable::updateCell() to repaint the cell's contents.
387 For QComboTableItems and QCheckTableItems this function has no visible
389 effect.
390 See also QTable::setPixmap(), pixmap(), and setText().
392
394 If b is TRUE it is acceptable to replace the contents of the cell with
395 the contents of another QTableItem. If b is FALSE the contents of the
396 cell may not be replaced by the contents of another table item. Table
397 items that span more than one cell may not have their contents replaced
398 by another table item.
399 (This differs from EditType because EditType is concerned with whether
401 the user is able to change the contents of a cell.)
402 See also isReplaceable().
404
406 Sets row r as the table item's row. Usually you do not need to call
407 this function.
408 If the cell spans multiple rows, this function sets the top row and
410 retains the height of the multi-cell table item.
411 See also row(), setCol(), and rowSpan().
413
415 Changes the extent of the QTableItem so that it spans multiple cells
416 covering rs rows and cs columns. The top left cell is the original
417 cell.
418 Warning: This function only works if the item has already been inserted
420 into the table using e.g. QTable::setItem(). This function also checks
421 to make sure if rs and cs are within the bounds of the table and
422 returns without changing the span if they are not. In addition
423 swapping, inserting or removing rows and columns that cross QTableItems
424 spanning more than one cell is not supported.
425 See also rowSpan() and colSpan().
427
429 Changes the table item's text to str.
430 Note that setText() does not update the cell the table item belongs to.
432 Use QTable::updateCell() to repaint the cell's contents.
433 See also QTable::setText(), text(), setPixmap(), and
435 QTable::updateCell().
436 Example: table/statistics/statistics.cpp.
438
440 If b is TRUE, the cell's text will be wrapped over multiple lines, when
441 necessary, to fit the width of the cell; otherwise the text will be
442 written as a single line.
443 See also wordWrap(), QTable::adjustColumn(), and
445 QTable::setColumnStretchable().
446
448 This virtual function returns the size a cell needs to show its entire
449 content.
450 If you subclass QTableItem you will often need to reimplement this
452 function.
453
455 Returns the QTable the table item belongs to.
456 See also QTable::setItem() and QTableItem().
458
460 Returns the text of the table item or QString::null if there is no
461 text.
462 To ensure that the current value of the editor is returned,
464 setContentFromEditor() is called: <ol type=1>
465 if the editMode() is Always, or
467 if editMode() is not Always but the editor of the cell is active and
469 the editor is not a QLineEdit.
470 This means that text() returns the original text value of the item if
472 the editor is a line edit, until the user commits an edit (e.g. by
473 pressing Enter or Tab) in which case the new text is returned. For
474 other editors (e.g. a combobox) setContentFromEditor() is always called
475 so the currently display value is the one returned.
476 See also setText() and pixmap().
478
480 Returns TRUE if word wrap is enabled for the cell; otherwise returns
481 FALSE.
482 See also setWordWrap().
484
487 http://doc.trolltech.com/qtableitem.html
488 http://www.trolltech.com/faq/tech.html
489
491 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
492 license file included in the distribution for a complete license
493 statement.
494
496 Generated automatically from the source code.
497
499 If you find a bug in Qt, please report it as described in
500 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
501 help you. Thank you.
502 The definitive Qt documentation is provided in HTML format; it is
504 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
505 web browser. This man page is provided as a convenience for those users
506 who prefer man pages, although this format is not officially supported
507 by Trolltech.
508 If you find errors in this manual page, please report them to qt-
510 bugs@trolltech.com. Please include the name of the manual page
511 (qtableitem.3qt) and the Qt version (3.3.8).
512Trolltech AS 2 February 2007 QTableItem(3qt)