1QListView(3qt)                                                  QListView(3qt)
2
3
4

NAME

6       QListView - Implements a list/tree view
7

SYNOPSIS

9       #include <qlistview.h>
10
11       Inherits QScrollView.
12
13   Public Members
14       QListView ( QWidget * parent = 0, const char * name = 0, WFlags f = 0 )
15       ~QListView ()
16       int treeStepSize () const
17       virtual void setTreeStepSize ( int )
18       virtual void insertItem ( QListViewItem * i )
19       virtual void takeItem ( QListViewItem * i )
20       virtual void removeItem ( QListViewItem * item )  (obsolete)
21       QHeader * header () const
22       virtual int addColumn ( const QString & label, int width = -1 )
23       virtual int addColumn ( const QIconSet & iconset, const QString &
24           label, int width = -1 )
25       virtual void removeColumn ( int index )
26       virtual void setColumnText ( int column, const QString & label )
27       virtual void setColumnText ( int column, const QIconSet & iconset,
28           const QString & label )
29       QString columnText ( int c ) const
30       virtual void setColumnWidth ( int column, int w )
31       int columnWidth ( int c ) const
32       enum WidthMode { Manual, Maximum }
33       virtual void setColumnWidthMode ( int c, WidthMode mode )
34       WidthMode columnWidthMode ( int c ) const
35       int columns () const
36       virtual void setColumnAlignment ( int column, int align )
37       int columnAlignment ( int column ) const
38       QListViewItem * itemAt ( const QPoint & viewPos ) const
39       QRect itemRect ( const QListViewItem * i ) const
40       int itemPos ( const QListViewItem * item )
41       void ensureItemVisible ( const QListViewItem * i )
42       void repaintItem ( const QListViewItem * item ) const
43       virtual void setMultiSelection ( bool enable )  (obsolete)
44       bool isMultiSelection () const  (obsolete)
45       enum SelectionMode { Single, Multi, Extended, NoSelection }
46       void setSelectionMode ( SelectionMode mode )
47       SelectionMode selectionMode () const
48       virtual void clearSelection ()
49       virtual void setSelected ( QListViewItem * item, bool selected )
50       void setSelectionAnchor ( QListViewItem * item )
51       bool isSelected ( const QListViewItem * i ) const
52       QListViewItem * selectedItem () const
53       virtual void setOpen ( QListViewItem * item, bool open )
54       bool isOpen ( const QListViewItem * item ) const
55       virtual void setCurrentItem ( QListViewItem * i )
56       QListViewItem * currentItem () const
57       QListViewItem * firstChild () const
58       QListViewItem * lastItem () const
59       int childCount () const
60       virtual void setAllColumnsShowFocus ( bool )
61       bool allColumnsShowFocus () const
62       virtual void setItemMargin ( int )
63       int itemMargin () const
64       virtual void setRootIsDecorated ( bool )
65       bool rootIsDecorated () const
66       virtual void setSorting ( int column, bool ascending = TRUE )
67       int sortColumn () const
68       void setSortColumn ( int column )
69       SortOrder sortOrder () const
70       void setSortOrder ( SortOrder order )
71       virtual void sort ()
72       virtual bool eventFilter ( QObject * o, QEvent * e )
73       virtual void setShowSortIndicator ( bool show )
74       bool showSortIndicator () const
75       virtual void setShowToolTips ( bool b )
76       bool showToolTips () const
77       enum ResizeMode { NoColumn, AllColumns, LastColumn }
78       virtual void setResizeMode ( ResizeMode m )
79       ResizeMode resizeMode () const
80       QListViewItem * findItem ( const QString & text, int column,
81           ComparisonFlags compare = ExactMatch | CaseSensitive ) const
82       enum RenameAction { Accept, Reject }
83       virtual void setDefaultRenameAction ( RenameAction a )
84       RenameAction defaultRenameAction () const
85       bool isRenaming () const
86       void hideColumn ( int column )
87
88   Public Slots
89       virtual void clear ()
90       virtual void invertSelection ()
91       virtual void selectAll ( bool select )
92       void triggerUpdate ()
93       void adjustColumn ( int col )
94
95   Signals
96       void selectionChanged ()
97       void selectionChanged ( QListViewItem * )
98       void currentChanged ( QListViewItem * )
99       void clicked ( QListViewItem * item )
100       void clicked ( QListViewItem * item, const QPoint & pnt, int c )
101       void pressed ( QListViewItem * item )
102       void pressed ( QListViewItem * item, const QPoint & pnt, int c )
103       void doubleClicked ( QListViewItem * item )  (obsolete)
104       void doubleClicked ( QListViewItem *, const QPoint &, int )
105       void returnPressed ( QListViewItem * )
106       void spacePressed ( QListViewItem * )
107       void rightButtonClicked ( QListViewItem *, const QPoint &, int )
108       void rightButtonPressed ( QListViewItem *, const QPoint &, int )
109       void mouseButtonPressed ( int button, QListViewItem * item, const
110           QPoint & pos, int c )
111       void mouseButtonClicked ( int button, QListViewItem * item, const
112           QPoint & pos, int c )
113       void contextMenuRequested ( QListViewItem * item, const QPoint & pos,
114           int col )
115       void onItem ( QListViewItem * i )
116       void onViewport ()
117       void expanded ( QListViewItem * item )
118       void collapsed ( QListViewItem * item )
119       void dropped ( QDropEvent * e )
120       void itemRenamed ( QListViewItem * item, int col, const QString & text
121           )
122       void itemRenamed ( QListViewItem * item, int col )
123
124   Properties
125       bool allColumnsShowFocus - whether items should show keyboard focus
126           using all columns
127       int childCount - the number of parentless (top-level) QListViewItem
128           objects in this QListView  (read only)
129       int columns - the number of columns in this list view  (read only)
130       RenameAction defaultRenameAction - what action to perform when the
131           editor loses focus during renaming
132       int itemMargin - the advisory item margin that list items may use
133       bool multiSelection - whether the list view is in multi-selection or
134           extended-selection mode  (obsolete)
135       ResizeMode resizeMode - whether all, none or the only the last column
136           should be resized
137       bool rootIsDecorated - whether the list view shows open/close signs on
138           root items
139       SelectionMode selectionMode - the list view's selection mode
140       bool showSortIndicator - whether the list view header should display a
141           sort indicator
142       bool showToolTips - whether this list view should show tooltips for
143           truncated column texts
144       int treeStepSize - the number of pixels a child is offset from its
145           parent
146
147   Protected Members
148       virtual void contentsMousePressEvent ( QMouseEvent * e )
149       virtual void contentsMouseReleaseEvent ( QMouseEvent * e )
150       virtual void contentsMouseMoveEvent ( QMouseEvent * e )
151       virtual void contentsMouseDoubleClickEvent ( QMouseEvent * e )
152       virtual QDragObject * dragObject ()
153       virtual void startDrag ()
154       virtual void resizeEvent ( QResizeEvent * e )
155       virtual void drawContentsOffset ( QPainter * p, int ox, int oy, int cx,
156           int cy, int cw, int ch )
157       virtual void paintEmptyArea ( QPainter * p, const QRect & rect )
158
159   Protected Slots
160       void updateContents ()
161       void doAutoScroll ()
162

DESCRIPTION

164       The QListView class implements a list/tree view.
165
166       It can display and control a hierarchy of multi-column items, and
167       provides the ability to add new items at any time. The user may select
168       one or many items (depending on the SelectionMode) and sort the list in
169       increasing or decreasing order by any column.
170
171       The simplest pattern of use is to create a QListView, add some column
172       headers using addColumn() and create one or more QListViewItem or
173       QCheckListItem objects with the QListView as parent:
174
175               QListView * table;
176
177               table->addColumn( "Qualified name" );
178               table->addColumn( "Namespace" );
179
180                   element = new QListViewItem( table, qName, namespaceURI );
181
182       Further nodes can be added to the list view object (the root of the
183       tree) or as child nodes to QListViewItems:
184
185                   for ( int i = 0 ; i < attributes.length(); i++ ) {
186                       new QListViewItem( element, attributes.qName(i), attributes.uri(i) );
187                   }
188
189       (From xml/tagreader-with-features/structureparser.cpp)
190
191       The main setup functions are: <center>.nf
192
193       </center>
194
195       To handle events such as mouse presses on the list view, derived
196       classes can reimplement the QScrollView functions:
197       contentsMousePressEvent, contentsMouseReleaseEvent,
198       contentsMouseDoubleClickEvent, contentsMouseMoveEvent,
199       contentsDragEnterEvent, contentsDragMoveEvent, contentsDragLeaveEvent,
200       contentsDropEvent, and contentsWheelEvent.
201
202       There are also several functions for mapping between items and
203       coordinates. itemAt() returns the item at a position on-screen,
204       itemRect() returns the rectangle an item occupies on the screen, and
205       itemPos() returns the position of any item (whether it is on-screen or
206       not). firstChild() returns the list view's first item (not necessarily
207       visible on-screen).
208
209       You can iterate over visible items using QListViewItem::itemBelow();
210       over a list view's top-level items using QListViewItem::firstChild()
211       and QListViewItem::nextSibling(); or every item using a
212       QListViewItemIterator. See the QListViewItem documentation for examples
213       of traversal.
214
215       An item can be moved amongst its siblings using
216       QListViewItem::moveItem(). To move an item in the hierarchy use
217       takeItem() and insertItem(). Item's (and all their child items) are
218       deleted with delete; to delete all the list view's items use clear().
219
220       There are a variety of selection modes described in the
221       QListView::SelectionMode documentation. The default is Single
222       selection, which you can change using setSelectionMode().
223
224       Because QListView offers multiple selection it must display keyboard
225       focus and selection state separately. Therefore there are functions
226       both to set the selection state of an item (setSelected()) and to set
227       which item displays keyboard focus (setCurrentItem()).
228
229       QListView emits two groups of signals; one group signals changes in
230       selection/focus state and one indicates selection. The first group
231       consists of selectionChanged() (applicable to all list views),
232       selectionChanged(QListViewItem*) (applicable only to a Single selection
233       list view), and currentChanged(QListViewItem*). The second group
234       consists of doubleClicked(QListViewItem*),
235       returnPressed(QListViewItem*), rightButtonClicked(QListViewItem*, const
236       QPoint&, int), etc.
237
238       Note that changing the state of the list view in a slot connected to a
239       list view signal may cause unexpected side effects. If you need to
240       change the list view's state in response to a signal, use a single shot
241       timer with a time out of 0, and connect this timer to a slot that
242       modifies the list view's state.
243
244       In Motif style, QListView deviates fairly strongly from the look and
245       feel of the Motif hierarchical tree view. This is done mostly to
246       provide a usable keyboard interface and to make the list view look
247       better with a white background.
248
249       If selectionMode() is Single (the default) the user can select one item
250       at a time, e.g. by clicking an item with the mouse, see
251       QListView::SelectionMode for details.
252
253       The list view can be navigated either using the mouse or the keyboard.
254       Clicking a - icon closes an item (hides its children) and clicking a +
255       icon opens an item (shows its children). The keyboard controls are
256       these: <center>.nf
257
258       </center>
259
260       If the user starts typing letters with the focus in the list view an
261       incremental search will occur. For example if the user types 'd' the
262       current item will change to the first item that begins with the letter
263       'd'; if they then type 'a', the current item will change to the first
264       item that begins with 'da', and so on. If no item begins with the
265       letters they type the current item doesn't change.
266
267       Warning: The list view assumes ownership of all list view items and
268       will delete them when it does not need them any more.
269
270                                   [Image Omitted]
271
272                                   [Image Omitted]
273
274       See also QListViewItem, QCheckListItem, and Advanced Widgets.
275
276   Member Type Documentation

QListView::RenameAction

278       This enum describes whether a rename operation is accepted if the
279       rename editor loses focus without the user pressing Enter.
280
281       QListView::Accept - Rename if Enter is pressed or focus is lost.
282
283       QListView::Reject - Discard the rename operation if focus is lost (and
284       Enter has not been pressed).
285

QListView::ResizeMode

287       This enum describes how the list view's header adjusts to resize events
288       which affect the width of the list view.
289
290       QListView::NoColumn - The columns do not get resized in resize events.
291
292       QListView::AllColumns - All columns are resized equally to fit the
293       width of the list view.
294
295       QListView::LastColumn - The last column is resized to fit the width of
296       the list view.
297

QListView::SelectionMode

299       This enumerated type is used by QListView to indicate how it reacts to
300       selection by the user.
301
302       QListView::Single - When the user selects an item, any already-selected
303       item becomes unselected. The user can unselect the selected item by
304       clicking on some empty space within the view.
305
306       QListView::Multi - When the user selects an item in the usual way, the
307       selection status of that item is toggled and the other items are left
308       alone. Also, multiple items can be selected by dragging the mouse while
309       the left mouse button stays pressed.
310
311       QListView::Extended - When the user selects an item in the usual way,
312       the selection is cleared and the new item selected. However, if the
313       user presses the Ctrl key when clicking on an item, the clicked item
314       gets toggled and all other items are left untouched. And if the user
315       presses the Shift key while clicking on an item, all items between the
316       current item and the clicked item get selected or unselected, depending
317       on the state of the clicked item. Also, multiple items can be selected
318       by dragging the mouse over them.
319
320       QListView::NoSelection - Items cannot be selected.
321
322       In other words, Single is a real single-selection list view, Multi a
323       real multi-selection list view, Extended is a list view where users can
324       select multiple items but usually want to select either just one or a
325       range of contiguous items, and NoSelection is a list view where the
326       user can look but not touch.
327

QListView::WidthMode

329       This enum type describes how the width of a column in the view changes.
330
331       QListView::Manual - the column width does not change automatically.
332
333       QListView::Maximum - the column is automatically sized according to the
334       widths of all items in the column. (Note: The column never shrinks in
335       this case.) This means that the column is always resized to the width
336       of the item with the largest width in the column.
337
338       See also setColumnWidth(), setColumnWidthMode(), and columnWidth().
339

MEMBER FUNCTION DOCUMENTATION

QListView::QListView ( QWidget * parent = 0, const char * name = 0, WFlags f =

342       0 )
343       Constructs a new empty list view called name with parent parent.
344
345       Performance is boosted by modifying the widget flags f so that only
346       part of the QListViewItem children is redrawn. This may be unsuitable
347       for custom QListViewItem classes, in which case WStaticContents and
348       WNoAutoErase should be cleared.
349
350       See also QWidget::clearWFlags() and Qt::WidgetFlags.
351

QListView::~QListView ()

353       Destroys the list view, deleting all its items, and frees up all
354       allocated resources.
355

int QListView::addColumn ( const QString & label, int width = -1 ) [virtual]

357       Adds a width pixels wide column with the column header label to the
358       list view, and returns the index of the new column.
359
360       All columns apart from the first one are inserted to the right of the
361       existing ones.
362
363       If width is negative, the new column's WidthMode is set to Maximum
364       instead of Manual.
365
366       See also setColumnText(), setColumnWidth(), and setColumnWidthMode().
367
368       Examples:
369

int QListView::addColumn ( const QIconSet & iconset, const QString & label,

371       int width = -1 ) [virtual]
372       This is an overloaded member function, provided for convenience. It
373       behaves essentially like the above function.
374
375       Adds a width pixels wide new column with the header label and the
376       iconset to the list view, and returns the index of the column.
377
378       If width is negative, the new column's WidthMode is set to Maximum, and
379       to Manual otherwise.
380
381       See also setColumnText(), setColumnWidth(), and setColumnWidthMode().
382

void QListView::adjustColumn ( int col ) [slot]

384       Adjusts the column col to its preferred width
385

bool QListView::allColumnsShowFocus () const

387       Returns TRUE if items should show keyboard focus using all columns;
388       otherwise returns FALSE. See the "allColumnsShowFocus" property for
389       details.
390

int QListView::childCount () const

392       Returns the number of parentless (top-level) QListViewItem objects in
393       this QListView. See the "childCount" property for details.
394

void QListView::clear () [virtual slot]

396       Removes and deletes all the items in this list view and triggers an
397       update.
398
399       Note that the currentChanged() signal is not emitted when this slot is
400       invoked.
401
402       See also triggerUpdate().
403
404       Examples:
405

void QListView::clearSelection () [virtual]

407       Sets all the items to be not selected, updates the list view as
408       necessary, and emits the selectionChanged() signals. Note that for
409       Multi selection list views this function needs to iterate over all
410       items.
411
412       See also setSelected() and multiSelection.
413
414       Example: addressbook/centralwidget.cpp.
415

void QListView::clicked ( QListViewItem * item ) [signal]

417       This signal is emitted whenever the user clicks (mouse pressed and
418       mouse released) in the list view. item is the clicked list view item,
419       or 0 if the user didn't click on an item.
420
421       Warning: Do not delete any QListViewItem objects in slots connected to
422       this signal.
423
424       Example: addressbook/centralwidget.cpp.
425

void QListView::clicked ( QListViewItem * item, const QPoint & pnt, int c )

427       [signal]
428       This is an overloaded member function, provided for convenience. It
429       behaves essentially like the above function.
430
431       This signal is emitted whenever the user clicks (mouse pressed and
432       mouse released) in the list view. item is the clicked list view item,
433       or 0 if the user didn't click on an item. pnt is the position where the
434       user has clicked in global coordinates. If item is not 0, c is the list
435       view column into which the user pressed; if item is 0 c's value is
436       undefined.
437
438       Warning: Do not delete any QListViewItem objects in slots connected to
439       this signal.
440

void QListView::collapsed ( QListViewItem * item ) [signal]

442       This signal is emitted when the item has been collapsed, i.e. when the
443       children of item are hidden.
444
445       See also setOpen() and expanded().
446

int QListView::columnAlignment ( int column ) const

448       Returns the alignment of column column. The default is AlignAuto.
449
450       See also Qt::AlignmentFlags.
451

QString QListView::columnText ( int c ) const

453       Returns the text of column c.
454
455       See also setColumnText().
456

int QListView::columnWidth ( int c ) const

458       Returns the width of column c.
459
460       See also setColumnWidth().
461

WidthMode QListView::columnWidthMode ( int c ) const

463       Returns the WidthMode for column c.
464
465       See also setColumnWidthMode().
466

int QListView::columns () const

468       Returns the number of columns in this list view. See the "columns"
469       property for details.
470

void QListView::contentsMouseDoubleClickEvent ( QMouseEvent * e ) [virtual

472       protected]
473       Processes the mouse double-click event e on behalf of the viewed
474       widget.
475
476       Reimplemented from QScrollView.
477

void QListView::contentsMouseMoveEvent ( QMouseEvent * e ) [virtual protected]

479
480       Processes the mouse move event e on behalf of the viewed widget.
481
482       Example: dirview/dirview.cpp.
483
484       Reimplemented from QScrollView.
485

void QListView::contentsMousePressEvent ( QMouseEvent * e ) [virtual

487       protected]
488       Processes the mouse press event e on behalf of the viewed widget.
489
490       Example: dirview/dirview.cpp.
491
492       Reimplemented from QScrollView.
493

void QListView::contentsMouseReleaseEvent ( QMouseEvent * e ) [virtual

495       protected]
496       Processes the mouse release event e on behalf of the viewed widget.
497
498       Example: dirview/dirview.cpp.
499
500       Reimplemented from QScrollView.
501

void QListView::contextMenuRequested ( QListViewItem * item, const QPoint &

503       pos, int col ) [signal]
504       This signal is emitted when the user invokes a context menu with the
505       right mouse button or with special system keys. If the keyboard was
506       used item is the current item; if the mouse was used, item is the item
507       under the mouse pointer or 0 if there is no item under the mouse
508       pointer. If no item is clicked, the column index emitted is -1.
509
510       pos is the position for the context menu in the global coordinate
511       system.
512
513       col is the column on which the user pressed, or -1 if the signal was
514       triggered by a key event.
515
516       Example: listviews/listviews.cpp.
517

void QListView::currentChanged ( QListViewItem * ) [signal]

519       This signal is emitted whenever the current item has changed (normally
520       after the screen update). The current item is the item responsible for
521       indicating keyboard focus.
522
523       The argument is the newly current item, or 0 if the change made no item
524       current. This can happen, for example, if all items in the list view
525       are deleted.
526
527       Warning: Do not delete any QListViewItem objects in slots connected to
528       this signal.
529
530       See also setCurrentItem() and currentItem().
531
532       Example: listviews/listviews.cpp.
533

QListViewItem * QListView::currentItem () const

535       Returns the current item, or 0 if there isn't one.
536
537       See also setCurrentItem().
538
539       Examples:
540

RenameAction QListView::defaultRenameAction () const

542       Returns what action to perform when the editor loses focus during
543       renaming. See the "defaultRenameAction" property for details.
544

void QListView::doAutoScroll () [protected slot]

546       This slot handles auto-scrolling when the mouse button is pressed and
547       the mouse is outside the widget.
548

void QListView::doubleClicked ( QListViewItem *, const QPoint &, int )

550       [signal]
551       This signal is emitted whenever an item is double-clicked. It's emitted
552       on the second button press, not the second button release. The
553       arguments are the relevant QListViewItem (may be 0), the point in
554       global coordinates and the relevant column (or -1 if the click was
555       outside the list).
556
557       Warning: Do not delete any QListViewItem objects in slots connected to
558       this signal.
559

void QListView::doubleClicked ( QListViewItem * item ) [signal]

561       This function is obsolete. It is provided to keep old source working.
562       We strongly advise against using it in new code. (use doubleClicked(
563       QListViewItem *, const QPoint&, int ))
564
565       This signal is emitted whenever an item is double-clicked. It's emitted
566       on the second button press, not the second button release. item is the
567       list view item on which the user did the double-click.
568

QDragObject * QListView::dragObject () [virtual protected]

570       If the user presses the mouse on an item and starts moving the mouse,
571       and the item allow dragging (see QListViewItem::setDragEnabled()), this
572       function is called to get a drag object and a drag is started unless
573       dragObject() returns 0.
574
575       By default this function returns 0. You should reimplement it and
576       create a QDragObject depending on the selected items.
577

void QListView::drawContentsOffset ( QPainter * p, int ox, int oy, int cx, int

579       cy, int cw, int ch ) [virtual protected]
580       Calls QListViewItem::paintCell() and QListViewItem::paintBranches() as
581       necessary for all list view items that require repainting in the cw
582       pixels wide and ch pixels high bounding rectangle starting at position
583       cx, cy with offset ox, oy. Uses the painter p.
584
585       Reimplemented from QScrollView.
586

void QListView::dropped ( QDropEvent * e ) [signal]

588       This signal is emitted, when a drop event occurred on the viewport (not
589       onto an item).
590
591       e provides all the information about the drop.
592

void QListView::ensureItemVisible ( const QListViewItem * i )

594       Ensures that item i is visible, scrolling the list view vertically if
595       necessary and opening (expanding) any parent items if this is required
596       to show the item.
597
598       See also itemRect() and QScrollView::ensureVisible().
599

bool QListView::eventFilter ( QObject * o, QEvent * e ) [virtual]

601       Redirects the event e relating to object o, for the viewport to
602       mousePressEvent(), keyPressEvent() and friends.
603
604       Reimplemented from QScrollView.
605

void QListView::expanded ( QListViewItem * item ) [signal]

607       This signal is emitted when item has been expanded, i.e. when the
608       children of item are shown.
609
610       See also setOpen() and collapsed().
611

QListViewItem * QListView::findItem ( const QString & text, int column,

613       ComparisonFlags compare = ExactMatch | CaseSensitive ) const
614       Finds the first list view item in column column, that matches text and
615       returns the item, or returns 0 of no such item could be found. The
616       search starts from the current item if the current item exists,
617       otherwise it starts from the first list view item. After reaching the
618       last item the search continues from the first item. Pass OR-ed together
619       Qt::StringComparisonMode values in the compare flag, to control how the
620       matching is performed. The default comparison mode is case-sensitive,
621       exact match.
622

QListViewItem * QListView::firstChild () const

624       Returns the first item in this QListView. Returns 0 if there is no
625       first item.
626
627       A list view's items can be traversed using firstChild() and
628       nextSibling() or using a QListViewItemIterator.
629
630       See also itemAt(), QListViewItem::itemBelow(), and
631       QListViewItem::itemAbove().
632
633       Examples:
634

QHeader * QListView::header () const

636       Returns the QHeader object that manages this list view's columns.
637       Please don't modify the header behind the list view's back.
638
639       You may safely call QHeader::setClickEnabled(),
640       QHeader::setResizeEnabled(), QHeader::setMovingEnabled(),
641       QHeader::hide() and all the const QHeader functions.
642
643       Examples:
644

void QListView::hideColumn ( int column )

646       Hides the column specified at column. This is a convenience function
647       that calls setColumnWidth( column, 0 ).
648
649       Note: The user may still be able to resize the hidden column using the
650       header handles. To prevent this, call setResizeEnabled(FALSE, column)
651       on the list views header.
652
653       See also setColumnWidth().
654

void QListView::insertItem ( QListViewItem * i ) [virtual]

656       Inserts item i into the list view as a top-level item. You do not need
657       to call this unless you've called takeItem(i) or
658       QListViewItem::takeItem(i) and need to reinsert i elsewhere.
659
660       See also QListViewItem::takeItem() and takeItem().
661

void QListView::invertSelection () [virtual slot]

663       Inverts the selection. Only works in Multi and Extended selection
664       modes.
665

bool QListView::isMultiSelection () const

667       Returns TRUE if the list view is in multi-selection or extended-
668       selection mode; otherwise returns FALSE. See the "multiSelection"
669       property for details.
670

bool QListView::isOpen ( const QListViewItem * item ) const

672       Identical to item->isOpen(). Provided for completeness.
673
674       See also setOpen().
675

bool QListView::isRenaming () const

677       Returns TRUE if an item is being renamed; otherwise returns FALSE.
678

bool QListView::isSelected ( const QListViewItem * i ) const

680       Returns TRUE if the list view item i is selected; otherwise returns
681       FALSE.
682
683       See also QListViewItem::isSelected().
684

QListViewItem * QListView::itemAt ( const QPoint & viewPos ) const

686       Returns the list view item at viewPos. Note that viewPos is in the
687       viewport()'s coordinate system, not in the list view's own, much
688       larger, coordinate system.
689
690       itemAt() returns 0 if there is no such item.
691
692       Note that you also get the pointer to the item if viewPos points to the
693       root decoration (see setRootIsDecorated()) of the item. To check
694       whether or not viewPos is on the root decoration of the item, you can
695       do something like this:
696
697           QListViewItem *i = itemAt( p );
698           if ( i ) {
699               if ( p.x() > header()->sectionPos( header()->mapToIndex( 0 ) ) +
700                       treeStepSize() * ( i->depth() + ( rootIsDecorated() ? 1 : 0) ) + itemMargin() ||
701                       p.x() < header()->sectionPos( header()->mapToIndex( 0 ) ) ) {
702                   ; // p is not on root decoration
703               else
704                   ; // p is on the root decoration
705           }
706
707       This might be interesting if you use this function to find out where
708       the user clicked and if you want to start a drag (which you do not want
709       to do if the user clicked onto the root decoration of an item).
710
711       See also itemPos(), itemRect(), and viewportToContents().
712

int QListView::itemMargin () const

714       Returns the advisory item margin that list items may use. See the
715       "itemMargin" property for details.
716

int QListView::itemPos ( const QListViewItem * item )

718       Returns the y-coordinate of item in the list view's coordinate system.
719       This function is normally much slower than itemAt() but it works for
720       all items, whereas itemAt() normally works only for items on the
721       screen.
722
723       This is a thin wrapper around QListViewItem::itemPos().
724
725       See also itemAt() and itemRect().
726

QRect QListView::itemRect ( const QListViewItem * i ) const

728       Returns the rectangle on the screen that item i occupies in
729       viewport()'s coordinates, or an invalid rectangle if i is 0 or is not
730       currently visible.
731
732       The rectangle returned does not include any children of the rectangle
733       (i.e. it uses QListViewItem::height(), rather than
734       QListViewItem::totalHeight()). If you want the rectangle to include
735       children you can use something like this:
736
737           QRect r( listView->itemRect( item ) );
738           r.setHeight( (QCOORD)(QMIN( item->totalHeight(),
739                                       listView->viewport->height() - r.y() ) ) )
740
741       Note the way it avoids too-high rectangles. totalHeight() can be much
742       larger than the window system's coordinate system allows.
743
744       itemRect() is comparatively slow. It's best to call it only for items
745       that are probably on-screen.
746

void QListView::itemRenamed ( QListViewItem * item, int col, const QString &

748       text ) [signal]
749       This signal is emitted when item has been renamed to text, e.g. by in
750       in-place renaming, in column col.
751
752       See also QListViewItem::setRenameEnabled().
753

void QListView::itemRenamed ( QListViewItem * item, int col ) [signal]

755       This is an overloaded member function, provided for convenience. It
756       behaves essentially like the above function.
757
758       This signal is emitted when item has been renamed, e.g. by in-place
759       renaming, in column col.
760
761       See also QListViewItem::setRenameEnabled().
762

QListViewItem * QListView::lastItem () const

764       Returns the last item in the list view tree. Returns 0 if there are no
765       items in the QListView.
766
767       This function is slow because it traverses the entire tree to find the
768       last item.
769

void QListView::mouseButtonClicked ( int button, QListViewItem * item, const

771       QPoint & pos, int c ) [signal]
772       This signal is emitted whenever the user clicks (mouse pressed and
773       mouse released) in the list view at position pos. button is the mouse
774       button that the user pressed, item is the clicked list view item or 0
775       if the user didn't click on an item. If item is not 0, c is the list
776       view column into which the user pressed; if item is 0 c's value is
777       undefined.
778
779       Warning: Do not delete any QListViewItem objects in slots connected to
780       this signal.
781

void QListView::mouseButtonPressed ( int button, QListViewItem * item, const

783       QPoint & pos, int c ) [signal]
784       This signal is emitted whenever the user pressed the mouse button in
785       the list view at position pos. button is the mouse button which the
786       user pressed, item is the pressed list view item or 0 if the user
787       didn't press on an item. If item is not 0, c is the list view column
788       into which the user pressed; if item is 0 c's value is undefined.
789
790       Warning: Do not delete any QListViewItem objects in slots connected to
791       this signal.
792

void QListView::onItem ( QListViewItem * i ) [signal]

794       This signal is emitted when the user moves the mouse cursor onto item
795       i, similar to the QWidget::enterEvent() function.
796

void QListView::onViewport () [signal]

798       This signal is emitted when the user moves the mouse cursor from an
799       item to an empty part of the list view.
800

void QListView::paintEmptyArea ( QPainter * p, const QRect & rect ) [virtual

802       protected]
803       Paints rect so that it looks like empty background using painter p.
804       rect is in widget coordinates, ready to be fed to p.
805
806       The default function fills rect with the viewport()->backgroundBrush().
807

void QListView::pressed ( QListViewItem * item ) [signal]

809       This signal is emitted whenever the user presses the mouse button in a
810       list view. item is the list view item on which the user pressed the
811       mouse button, or 0 if the user didn't press the mouse on an item.
812
813       Warning: Do not delete any QListViewItem objects in slots connected to
814       this signal.
815

void QListView::pressed ( QListViewItem * item, const QPoint & pnt, int c )

817       [signal]
818       This is an overloaded member function, provided for convenience. It
819       behaves essentially like the above function.
820
821       This signal is emitted whenever the user presses the mouse button in a
822       list view. item is the list view item on which the user pressed the
823       mouse button, or 0 if the user didn't press the mouse on an item. pnt
824       is the position of the mouse cursor in global coordinates, and c is the
825       column where the mouse cursor was when the user pressed the mouse
826       button.
827
828       Warning: Do not delete any QListViewItem objects in slots connected to
829       this signal.
830

void QListView::removeColumn ( int index ) [virtual]

832       Removes the column at position index.
833
834       If no columns remain after the column is removed, the list view will be
835       cleared.
836
837       See also clear().
838

void QListView::removeItem ( QListViewItem * item ) [virtual]

840       This function is obsolete. It is provided to keep old source working.
841       We strongly advise against using it in new code.
842
843       This function has been renamed takeItem().
844

void QListView::repaintItem ( const QListViewItem * item ) const

846       Repaints item on the screen if item is currently visible. Takes care to
847       avoid multiple repaints.
848

void QListView::resizeEvent ( QResizeEvent * e ) [virtual protected]

850       Ensures that the header is correctly sized and positioned when the
851       resize event e occurs.
852

ResizeMode QListView::resizeMode () const

854       Returns TRUE if all, none or the only the last column should be
855       resized; otherwise returns FALSE. See the "resizeMode" property for
856       details.
857

void QListView::returnPressed ( QListViewItem * ) [signal]

859       This signal is emitted when Enter or Return is pressed. The argument is
860       the currentItem().
861

void QListView::rightButtonClicked ( QListViewItem *, const QPoint &, int )

863       [signal]
864       This signal is emitted when the right button is clicked (i.e. when it's
865       released). The arguments are the relevant QListViewItem (may be 0), the
866       point in global coordinates and the relevant column (or -1 if the click
867       was outside the list).
868

void QListView::rightButtonPressed ( QListViewItem *, const QPoint &, int )

870       [signal]
871       This signal is emitted when the right button is pressed. The arguments
872       are the relevant QListViewItem (may be 0), the point in global
873       coordinates and the relevant column (or -1 if the click was outside the
874       list).
875

bool QListView::rootIsDecorated () const

877       Returns TRUE if the list view shows open/close signs on root items;
878       otherwise returns FALSE. See the "rootIsDecorated" property for
879       details.
880

void QListView::selectAll ( bool select ) [virtual slot]

882       If select is TRUE, all the items get selected; otherwise all the items
883       get unselected. This only works in the selection modes Multi and
884       Extended. In Single and NoSelection mode the selection of the current
885       item is just set to select.
886

QListViewItem * QListView::selectedItem () const

888       Returns the selected item if the list view is in Single selection mode
889       and an item is selected.
890
891       If no items are selected or the list view is not in Single selection
892       mode this function returns 0.
893
894       See also setSelected() and multiSelection.
895

void QListView::selectionChanged () [signal]

897       This signal is emitted whenever the set of selected items has changed
898       (normally before the screen update). It is available in Single, Multi,
899       and Extended selection modes, but is most useful in Multi selection
900       mode.
901
902       Warning: Do not delete any QListViewItem objects in slots connected to
903       this signal.
904
905       See also setSelected() and QListViewItem::setSelected().
906
907       Example: listviews/listviews.cpp.
908

void QListView::selectionChanged ( QListViewItem * ) [signal]

910       This is an overloaded member function, provided for convenience. It
911       behaves essentially like the above function.
912
913       This signal is emitted whenever the selected item has changed in Single
914       selection mode (normally after the screen update). The argument is the
915       newly selected item. If the selection is cleared (when, for example,
916       the user clicks in the unused area of the list view) then this signal
917       will not be emitted.
918
919       In Multi selection mode, use the no argument overload of this signal.
920
921       Warning: Do not delete any QListViewItem objects in slots connected to
922       this signal.
923
924       See also setSelected(), QListViewItem::setSelected(), and
925       currentChanged().
926

SelectionMode QListView::selectionMode () const

928       Returns the list view's selection mode. See the "selectionMode"
929       property for details.
930

void QListView::setAllColumnsShowFocus ( bool ) [virtual]

932       Sets whether items should show keyboard focus using all columns. See
933       the "allColumnsShowFocus" property for details.
934

void QListView::setColumnAlignment ( int column, int align ) [virtual]

936       Sets column column's alignment to align. The alignment is ultimately
937       passed to QListViewItem::paintCell() for each item in the list view.
938       For horizontally aligned text with Qt::AlignLeft or Qt::AlignHCenter
939       the ellipsis (...) will be to the right, for Qt::AlignRight the
940       ellipsis will be to the left.
941
942       See also Qt::AlignmentFlags.
943
944       Example: listviews/listviews.cpp.
945

void QListView::setColumnText ( int column, const QString & label ) [virtual]

947       Sets the heading of column column to label.
948
949       See also columnText().
950

void QListView::setColumnText ( int column, const QIconSet & iconset, const

952       QString & label ) [virtual]
953       This is an overloaded member function, provided for convenience. It
954       behaves essentially like the above function.
955
956       Sets the heading of column column to iconset and label.
957
958       See also columnText().
959

void QListView::setColumnWidth ( int column, int w ) [virtual]

961       Sets the width of column column to w pixels. Note that if the column
962       has a WidthMode other than Manual, this width setting may be
963       subsequently overridden.
964
965       See also columnWidth().
966

void QListView::setColumnWidthMode ( int c, WidthMode mode ) [virtual]

968       Sets column c's width mode to mode. The default depends on the original
969       width argument to addColumn().
970
971       See also QListViewItem::width().
972

void QListView::setCurrentItem ( QListViewItem * i ) [virtual]

974       Sets item i to be the current item and repaints appropriately (i.e.
975       highlights the item). The current item is used for keyboard navigation
976       and focus indication; it is independent of any selected items, although
977       a selected item can also be the current item.
978
979       This function does not set the selection anchor. Use
980       setSelectionAnchor() instead.
981
982       See also currentItem() and setSelected().
983
984       Example: listviews/listviews.cpp.
985

void QListView::setDefaultRenameAction ( RenameAction a ) [virtual]

987       Sets what action to perform when the editor loses focus during renaming
988       to a. See the "defaultRenameAction" property for details.
989

void QListView::setItemMargin ( int ) [virtual]

991       Sets the advisory item margin that list items may use. See the
992       "itemMargin" property for details.
993

void QListView::setMultiSelection ( bool enable ) [virtual]

995       Sets whether the list view is in multi-selection or extended-selection
996       mode to enable. See the "multiSelection" property for details.
997

void QListView::setOpen ( QListViewItem * item, bool open ) [virtual]

999       Sets item to be open if open is TRUE and item is expandable, and to be
1000       closed if open is FALSE. Repaints accordingly.
1001
1002       See also QListViewItem::setOpen() and QListViewItem::setExpandable().
1003

void QListView::setResizeMode ( ResizeMode m ) [virtual]

1005       Sets whether all, none or the only the last column should be resized to
1006       m. See the "resizeMode" property for details.
1007

void QListView::setRootIsDecorated ( bool ) [virtual]

1009       Sets whether the list view shows open/close signs on root items. See
1010       the "rootIsDecorated" property for details.
1011

void QListView::setSelected ( QListViewItem * item, bool selected ) [virtual]

1013       If selected is TRUE the item is selected; otherwise it is unselected.
1014
1015       If the list view is in Single selection mode and selected is TRUE, the
1016       currently selected item is unselected and item is made current. Unlike
1017       QListViewItem::setSelected(), this function updates the list view as
1018       necessary and emits the selectionChanged() signals.
1019
1020       See also isSelected(), multiSelection, multiSelection,
1021       setCurrentItem(), and setSelectionAnchor().
1022
1023       Example: listviews/listviews.cpp.
1024

void QListView::setSelectionAnchor ( QListViewItem * item )

1026       Sets the selection anchor to item, if item is selectable.
1027
1028       The selection anchor is the item that remains selected when Shift-
1029       selecting with either mouse or keyboard in Extended selection mode.
1030
1031       See also setSelected().
1032

void QListView::setSelectionMode ( SelectionMode mode )

1034       Sets the list view's selection mode to mode. See the "selectionMode"
1035       property for details.
1036

void QListView::setShowSortIndicator ( bool show ) [virtual]

1038       Sets whether the list view header should display a sort indicator to
1039       show. See the "showSortIndicator" property for details.
1040

void QListView::setShowToolTips ( bool b ) [virtual]

1042       Sets whether this list view should show tooltips for truncated column
1043       texts to b. See the "showToolTips" property for details.
1044

void QListView::setSortColumn ( int column )

1046       Sets the sorting column for the list view.
1047
1048       If column is -1, sorting is disabled and the user cannot sort columns
1049       by clicking on the column headers. If column is larger than the number
1050       of columns the user must click on a column header to sort the list
1051       view.
1052
1053       See also setSorting().
1054

void QListView::setSortOrder ( SortOrder order )

1056       Sets the sort order for the items in the list view to order.
1057
1058       See also setSorting().
1059

void QListView::setSorting ( int column, bool ascending = TRUE ) [virtual]

1061       Sets the list view to be sorted by column column in ascending order if
1062       ascending is TRUE or descending order if it is FALSE.
1063
1064       If column is -1, sorting is disabled and the user cannot sort columns
1065       by clicking on the column headers. If column is larger than the number
1066       of columns the user must click on a column header to sort the list
1067       view.
1068

void QListView::setTreeStepSize ( int ) [virtual]

1070       Sets the number of pixels a child is offset from its parent. See the
1071       "treeStepSize" property for details.
1072

bool QListView::showSortIndicator () const

1074       Returns TRUE if the list view header should display a sort indicator;
1075       otherwise returns FALSE. See the "showSortIndicator" property for
1076       details.
1077

bool QListView::showToolTips () const

1079       Returns TRUE if this list view should show tooltips for truncated
1080       column texts; otherwise returns FALSE. See the "showToolTips" property
1081       for details.
1082

void QListView::sort () [virtual]

1084       Sorts the list view using the last sorting configuration (sort column
1085       and ascending/descending).
1086

int QListView::sortColumn () const

1088       Returns the column by which the list view is sorted, or -1 if sorting
1089       is disabled.
1090
1091       See also sortOrder().
1092

SortOrder QListView::sortOrder () const

1094       Returns the sorting order of the list view items.
1095
1096       See also sortColumn().
1097

void QListView::spacePressed ( QListViewItem * ) [signal]

1099       This signal is emitted when Space is pressed. The argument is the
1100       currentItem().
1101

void QListView::startDrag () [virtual protected]

1103       Starts a drag.
1104

void QListView::takeItem ( QListViewItem * i ) [virtual]

1106       Removes item i from the list view; i must be a top-level item. The
1107       warnings regarding QListViewItem::takeItem() apply to this function,
1108       too.
1109
1110       See also insertItem().
1111

int QListView::treeStepSize () const

1113       Returns the number of pixels a child is offset from its parent. See the
1114       "treeStepSize" property for details.
1115

void QListView::triggerUpdate () [slot]

1117       Triggers a size, geometry and content update during the next iteration
1118       of the event loop. Ensures that there'll be just one update to avoid
1119       flicker.
1120

void QListView::updateContents () [protected slot]

1122       Updates the sizes of the viewport, header, scroll bars and so on.
1123
1124       Warning: Don't call this directly; call triggerUpdate() instead.
1125
1126   Property Documentation

bool allColumnsShowFocus

1128       This property holds whether items should show keyboard focus using all
1129       columns.
1130
1131       If this property is TRUE all columns will show focus and selection
1132       states, otherwise only column 0 will show focus.
1133
1134       The default is FALSE.
1135
1136       Setting this to TRUE if it's not necessary may cause noticeable
1137       flicker.
1138
1139       Set this property's value with setAllColumnsShowFocus() and get this
1140       property's value with allColumnsShowFocus().
1141

int childCount

1143       This property holds the number of parentless (top-level) QListViewItem
1144       objects in this QListView.
1145
1146       Holds the current number of parentless (top-level) QListViewItem
1147       objects in this QListView.
1148
1149       See also QListViewItem::childCount().
1150
1151       Get this property's value with childCount().
1152

int columns

1154       This property holds the number of columns in this list view.
1155
1156       Get this property's value with columns().
1157
1158       See also addColumn() and removeColumn().
1159

RenameAction defaultRenameAction

1161       This property holds what action to perform when the editor loses focus
1162       during renaming.
1163
1164       If this property is Accept, and the user renames an item and the editor
1165       loses focus (without the user pressing Enter), the item will still be
1166       renamed. If the property's value is Reject, the item will not be
1167       renamed unless the user presses Enter. The default is Reject.
1168
1169       Set this property's value with setDefaultRenameAction() and get this
1170       property's value with defaultRenameAction().
1171

int itemMargin

1173       This property holds the advisory item margin that list items may use.
1174
1175       The item margin defaults to one pixel and is the margin between the
1176       item's edges and the area where it draws its contents.
1177       QListViewItem::paintFocus() draws in the margin.
1178
1179       See also QListViewItem::paintCell().
1180
1181       Set this property's value with setItemMargin() and get this property's
1182       value with itemMargin().
1183

bool multiSelection

1185       This function is obsolete. It is provided to keep old source working.
1186       We strongly advise against using it in new code.
1187
1188       This property holds whether the list view is in multi-selection or
1189       extended-selection mode.
1190
1191       If you enable multi-selection, Multi, mode, it is possible to specify
1192       whether or not this mode should be extended. Extended means that the
1193       user can select multiple items only when pressing the Shift or Ctrl key
1194       at the same time.
1195
1196       The default selection mode is Single.
1197
1198       See also selectionMode.
1199
1200       Set this property's value with setMultiSelection() and get this
1201       property's value with isMultiSelection().
1202

ResizeMode resizeMode

1204       This property holds whether all, none or the only the last column
1205       should be resized.
1206
1207       Specifies whether all, none or only the last column should be resized
1208       to fit the full width of the list view. The values for this property
1209       can be one of: NoColumn (the default), AllColumns or LastColumn.
1210
1211       Warning: Setting the resize mode should be done after all necessary
1212       columns have been added to the list view, otherwise the behavior is
1213       undefined.
1214
1215       See also QHeader and header().
1216
1217       Set this property's value with setResizeMode() and get this property's
1218       value with resizeMode().
1219

bool rootIsDecorated

1221       This property holds whether the list view shows open/close signs on
1222       root items.
1223
1224       Open/close signs are small + or - symbols in windows style, or arrows
1225       in Motif style. The default is FALSE.
1226
1227       Set this property's value with setRootIsDecorated() and get this
1228       property's value with rootIsDecorated().
1229

SelectionMode selectionMode

1231       This property holds the list view's selection mode.
1232
1233       The mode can be Single (the default), Extended, Multi or NoSelection.
1234
1235       See also multiSelection.
1236
1237       Set this property's value with setSelectionMode() and get this
1238       property's value with selectionMode().
1239

bool showSortIndicator

1241       This property holds whether the list view header should display a sort
1242       indicator.
1243
1244       If this property is TRUE, an arrow is drawn in the header of the list
1245       view to indicate the sort order of the list view contents. The arrow
1246       will be drawn in the correct column and will point up or down,
1247       depending on the current sort direction. The default is FALSE (don't
1248       show an indicator).
1249
1250       See also QHeader::setSortIndicator().
1251
1252       Set this property's value with setShowSortIndicator() and get this
1253       property's value with showSortIndicator().
1254

bool showToolTips

1256       This property holds whether this list view should show tooltips for
1257       truncated column texts.
1258
1259       The default is TRUE.
1260
1261       Set this property's value with setShowToolTips() and get this
1262       property's value with showToolTips().
1263

int treeStepSize

1265       This property holds the number of pixels a child is offset from its
1266       parent.
1267
1268       The default is 20 pixels.
1269
1270       Of course, this property is only meaningful for hierarchical list
1271       views.
1272
1273       Set this property's value with setTreeStepSize() and get this
1274       property's value with treeStepSize().
1275
1276

SEE ALSO

1278       http://doc.trolltech.com/qlistview.html
1279       http://www.trolltech.com/faq/tech.html
1280
1282       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
1283       license file included in the distribution for a complete license
1284       statement.
1285

AUTHOR

1287       Generated automatically from the source code.
1288

BUGS

1290       If you find a bug in Qt, please report it as described in
1291       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
1292       help you. Thank you.
1293
1294       The definitive Qt documentation is provided in HTML format; it is
1295       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
1296       web browser. This man page is provided as a convenience for those users
1297       who prefer man pages, although this format is not officially supported
1298       by Trolltech.
1299
1300       If you find errors in this manual page, please report them to qt-
1301       bugs@trolltech.com.  Please include the name of the manual page
1302       (qlistview.3qt) and the Qt version (3.3.8).
1303
1304
1305
1306Trolltech AS                    2 February 2007                 QListView(3qt)
Impressum