1QTableItem(3qt)                                                QTableItem(3qt)
2
3
4

NAME

6       QTableItem - The cell content for QTable cells
7

SYNOPSIS

9       #include <qtable.h>
10
11       Inherits Qt.
12
13       Inherited by QComboTableItem and QCheckTableItem.
14
15   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

DESCRIPTION

51       The QTableItem class provides the cell content for QTable cells.
52
53       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
58       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
66       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
70       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
74       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
78       Example:
79
80           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
87       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
91       Table items can be deleted with delete in the standard way; the table
92       and cell will be updated accordingly.
93
94       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
98       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
102       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
110           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
118       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
123       <center>
124                                   [Image Omitted]
125
126       </center>
127
128       See also QCheckTableItem, QComboTableItem, and Advanced Widgets.
129
130   Member Type Documentation

QTableItem::EditType

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
135       QTableItem::Always - The cell always looks editable.
136
137       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
143       If a cell with the edit type Always looks misaligned you could
144       reimplement createEditor() for these items.
145
146       QTableItem::WhenCurrent - The cell looks editable only when it has
147       keyboard focus (see QTable::setCurrentCell()).
148
149       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
153       The OnTyping edit type is the default when QTableItem objects are
154       created by the convenience functions QTable::setText() and
155       QTable::setPixmap().
156
157       QTableItem::Never - The cell is not editable.
158
159       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
163       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

MEMBER FUNCTION DOCUMENTATION

QTableItem::QTableItem ( QTable * table, EditType et )

171       Creates a table item that is a child of table table with no text. The
172       item has the EditType et.
173
174       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
178       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

QTableItem::QTableItem ( QTable * table, EditType et, const QString & text )

182       Creates a table item that is a child of table table with text text. The
183       item has the EditType et.
184
185       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
189       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

QTableItem::QTableItem ( QTable * table, EditType et, const QString & text,

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
197       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
202       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

QTableItem::~QTableItem () [virtual]

206       The destructor deletes this item and frees all allocated resources.
207
208       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

int QTableItem::alignment () const [virtual]

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
216       See also Qt::AlignmentFlags.
217

int QTableItem::col () const

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
222       See also row() and setCol().
223
224       Example: table/bigtable/main.cpp.
225

int QTableItem::colSpan () const

227       Returns the column span of the table item, usually 1.
228
229       See also setSpan() and rowSpan().
230

QWidget * QTableItem::createEditor () const [virtual]

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
236       If the function returns 0, the cell is read-only.
237
238       The returned widget should preferably be invisible, ideally with
239       QTable::viewport() as parent.
240
241       If you reimplement this function you'll almost certainly need to
242       reimplement setContentFromEditor(), and may need to reimplement
243       sizeHint().
244
245           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
256       See also QTable::createEditor(), setContentFromEditor(),
257       QTable::viewport(), and setReplaceable().
258
259       Example: table/statistics/statistics.cpp.
260

EditType QTableItem::editType () const

262       Returns the table item's edit type.
263
264       This is set when the table item is constructed.
265
266       See also EditType and QTableItem().
267

bool QTableItem::isEnabled () const

269       Returns TRUE if the table item is enabled; otherwise returns FALSE.
270
271       See also setEnabled().
272

bool QTableItem::isReplaceable () const

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
279       (This differs from EditType because EditType is concerned with whether
280       the user is able to change the contents of a cell.)
281
282       See also setReplaceable() and EditType.
283

QString QTableItem::key () const [virtual]

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
288       See also QTable::sorting.
289

void QTableItem::paint ( QPainter * p, const QColorGroup & cg, const QRect &

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
295       If selected is TRUE the cell is displayed in a way that indicates that
296       it is highlighted.
297
298       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
301       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
304       Note that the painter is not clipped by default in order to get maximum
305       efficiency. If you want clipping, use
306
307           p->setClipRect( table()->cellRect(row, col), QPainter::ClipPainter );
308           //... your drawing code
309           p->setClipping( FALSE );
310
311       Example: table/statistics/statistics.cpp.
312

QPixmap QTableItem::pixmap () const [virtual]

314       Returns the table item's pixmap or a null pixmap if no pixmap has been
315       set.
316
317       See also setPixmap() and text().
318

int QTableItem::row () const

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
323       See also col() and setRow().
324
325       Example: table/bigtable/main.cpp.
326

int QTableItem::rowSpan () const

328       Returns the row span of the table item, usually 1.
329
330       See also setSpan() and colSpan().
331

int QTableItem::rtti () const [virtual]

333       Returns the Run Time Type Identification value for this table item
334       which for QTableItems is 0.
335
336       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
341       See also QCheckTableItem::rtti() and QComboTableItem::rtti().
342
343       Reimplemented in QComboTableItem and QCheckTableItem.
344

void QTableItem::setCol ( int c ) [virtual]

346       Sets column c as the table item's column. Usually you will not need to
347       call this function.
348
349       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
352       See also col(), setRow(), and colSpan().
353

void QTableItem::setContentFromEditor ( QWidget * w ) [virtual]

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
358       If you reimplement createEditor() and return something that is not a
359       QLineEdit you will need to reimplement this function.
360
361           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
370       See also QTable::setCellContentFromEditor().
371
372       Example: table/statistics/statistics.cpp.
373

void QTableItem::setEnabled ( bool b ) [virtual]

375       If b is TRUE, the table item is enabled; if b is FALSE the table item
376       is disabled.
377
378       A disabled item doesn't respond to user interaction.
379
380       See also isEnabled().
381

void QTableItem::setPixmap ( const QPixmap & p ) [virtual]

383       Sets pixmap p to be this item's pixmap.
384
385       Note that setPixmap() does not update the cell the table item belongs
386       to. Use QTable::updateCell() to repaint the cell's contents.
387
388       For QComboTableItems and QCheckTableItems this function has no visible
389       effect.
390
391       See also QTable::setPixmap(), pixmap(), and setText().
392

void QTableItem::setReplaceable ( bool b ) [virtual]

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
400       (This differs from EditType because EditType is concerned with whether
401       the user is able to change the contents of a cell.)
402
403       See also isReplaceable().
404

void QTableItem::setRow ( int r ) [virtual]

406       Sets row r as the table item's row. Usually you do not need to call
407       this function.
408
409       If the cell spans multiple rows, this function sets the top row and
410       retains the height of the multi-cell table item.
411
412       See also row(), setCol(), and rowSpan().
413

void QTableItem::setSpan ( int rs, int cs ) [virtual]

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
419       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
426       See also rowSpan() and colSpan().
427

void QTableItem::setText ( const QString & str ) [virtual]

429       Changes the table item's text to str.
430
431       Note that setText() does not update the cell the table item belongs to.
432       Use QTable::updateCell() to repaint the cell's contents.
433
434       See also QTable::setText(), text(), setPixmap(), and
435       QTable::updateCell().
436
437       Example: table/statistics/statistics.cpp.
438

void QTableItem::setWordWrap ( bool b ) [virtual]

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
444       See also wordWrap(), QTable::adjustColumn(), and
445       QTable::setColumnStretchable().
446

QSize QTableItem::sizeHint () const [virtual]

448       This virtual function returns the size a cell needs to show its entire
449       content.
450
451       If you subclass QTableItem you will often need to reimplement this
452       function.
453

QTable * QTableItem::table () const

455       Returns the QTable the table item belongs to.
456
457       See also QTable::setItem() and QTableItem().
458

QString QTableItem::text () const [virtual]

460       Returns the text of the table item or QString::null if there is no
461       text.
462
463       To ensure that the current value of the editor is returned,
464       setContentFromEditor() is called: <ol type=1>
465
466       if the editMode() is Always, or
467
468       if editMode() is not Always but the editor of the cell is active and
469       the editor is not a QLineEdit.
470
471       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
477       See also setText() and pixmap().
478

bool QTableItem::wordWrap () const

480       Returns TRUE if word wrap is enabled for the cell; otherwise returns
481       FALSE.
482
483       See also setWordWrap().
484
485

SEE ALSO

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

AUTHOR

496       Generated automatically from the source code.
497

BUGS

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
503       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
509       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).
512
513
514
515Trolltech AS                    2 February 2007                QTableItem(3qt)
Impressum