QListWidget Class Reference

The QListWidget class provides an item-based list widget.

  1. #include <QListWidget>

Inherits: QListView.

Detailed Description

The QListWidget class provides an item-based list widget.

QListWidget is a convenience class that provides a list view similar to the one supplied by QListView, but with a classic item-based interface for adding and removing items. QListWidget uses an internal model to manage each QListWidgetItem in the list.

For a more flexible list view widget, use the QListView class with a standard model.

List widgets are constructed in the same way as other widgets:

  1.     QListWidget *listWidget = new QListWidget(this);

The selectionMode() of a list widget determines how many of the items in the list can be selected at the same time, and whether complex selections of items can be created. This can be set with the setSelectionMode() function.

There are two ways to add items to the list: they can be constructed with the list widget as their parent widget, or they can be constructed with no parent widget and added to the list later. If a list widget already exists when the items are constructed, the first method is easier to use:

  1.     new QListWidgetItem(tr("Oak"), listWidget);
  2.     new QListWidgetItem(tr("Fir"), listWidget);
  3.     new QListWidgetItem(tr("Pine"), listWidget);

If you need to insert a new item into the list at a particular position, it is more required to construct the item without a parent widget and use the insertItem() function to place it within the list. The list widget will take ownership of the item.

  1.     QListWidgetItem *newItem = new QListWidgetItem;
  2.     newItem->setText(itemText);
  3.     listWidget->insertItem(row, newItem);

For multiple items, insertItems() can be used instead. The number of items in the list is found with the count() function. To remove items from the list, use takeItem().

The current item in the list can be found with currentItem(), and changed with setCurrentItem(). The user can also change the current item by navigating with the keyboard or clicking on a different item. When the current item changes, the currentItemChanged() signal is emitted with the new current item and the item that was previously current.

Screenshot of a Windows XP style list widget

Screenshot of a Windows XP style list widget

Screenshot of a Macintosh style table widget

Screenshot of a Macintosh style table widget

Screenshot of a Plastique style table widget

Screenshot of a Plastique style table widget

A Windows XP style list widget.A Macintosh style list widget.A Plastique style list widget.

See also QListWidgetItem, QListView, QTreeView, Model/View Programming, and Config Dialog Example.

Properties

Toggle detailscountcount : const int

This property holds the number of items in the list including any hidden items.

Access functions:

    Look up this member in the source code.

    Toggle detailscurrentRowcurrentRow : int

    This property holds the row of the current item.

    Depending on the current selection mode, the row may also be selected.

    Access functions:

    Look up this member in the source code.

    Toggle detailssortingEnabledsortingEnabled : bool

    This property holds whether sorting is enabled

    If this property is true, sorting is enabled for the list; if the property is false, sorting is not enabled.

    The default value is false.

    Access functions:

    Look up this member in the source code.

      Public Functions

      Toggle details QListWidget

      QListWidgetQListWidget ( QWidget *parent=0 ) ( QWidget *parent=0 )

      Constructs an empty QListWidget with the given parent.

      Look up this member in the source code.

      Toggle details QListWidget

      ~QListWidget~QListWidget () ()

      Destroys the list widget and all its items.

      Look up this member in the source code.

      Toggle details void QListWidget

      addItemaddItem ( const QString &label ) ( const QString &label )

      Inserts an item with the text label at the end of the list widget.

      Look up this member in the source code.

      Toggle details void QListWidget

      addItemaddItem ( QListWidgetItem *item ) ( QListWidgetItem *item )

      Inserts the item at the end of the list widget.

      Warning: A QListWidgetItem can only be added to a QListWidget once. Adding the same QListWidgetItem multiple times to a QListWidget will result in undefined behavior.

      See also insertItem().

      Look up this member in the source code.

      Toggle details void QListWidget

      addItemsaddItems ( const QStringList &labels ) ( const QStringList &labels )

      Inserts items with the text labels at the end of the list widget.

      See also insertItems().

      Look up this member in the source code.

      Toggle details void QListWidget

      closePersistentEditorclosePersistentEditor ( QListWidgetItem *item ) ( QListWidgetItem *item )

      Closes the persistent editor for the given item.

      See also openPersistentEditor().

      Look up this member in the source code.

      Toggle details QListWidgetItem * QListWidget

      currentItemcurrentItem () ()const

      Returns the current item.

      See also setCurrentItem().

      Look up this member in the source code.

      Toggle details void QListWidget

      dropEventdropEvent ( QDropEvent *event ) ( QDropEvent *event ) [virtual]

      Reimplemented from QWidget::dropEvent().

      Look up this member in the source code.

      Toggle details bool QListWidget

      dropMimeDatadropMimeData ( int index , const QMimeData *data , Qt::DropAction action ...) ( int index , const QMimeData *data , Qt::DropAction action ) [virtual protected]

      Handles data supplied by an external drag and drop operation that ended with the given action in the given index. Returns true if data and action can be handled by the model; otherwise returns false.

      See also supportedDropActions().

      Look up this member in the source code.

      Toggle details void QListWidget

      editItemeditItem ( QListWidgetItem *item ) ( QListWidgetItem *item )

      Starts editing the item if it is editable.

      Look up this member in the source code.

      Toggle details bool QListWidget

      eventevent ( QEvent *e ) ( QEvent *e ) [virtual protected]

      Reimplemented from QObject::event().

      Look up this member in the source code.

      Toggle details QList <QListWidgetItem *> QListWidget

      findItemsfindItems ( const QString &text , Qt::MatchFlags flags ...) ( const QString &text , Qt::MatchFlags flags )const

      Finds items with the text that matches the string text using the given flags.

      Look up this member in the source code.

      Toggle details QModelIndex QListWidget

      indexFromItemindexFromItem ( QListWidgetItem *item ) ( QListWidgetItem *item )const[protected]

      Returns the QModelIndex assocated with the given item.

      Look up this member in the source code.

      Toggle details void QListWidget

      insertIteminsertItem ( int row , QListWidgetItem *item ) ( int row , QListWidgetItem *item )

      Inserts the item at the position in the list given by row.

      See also addItem().

      Look up this member in the source code.

      Toggle details void QListWidget

      insertIteminsertItem ( int row , const QString &label ) ( int row , const QString &label )

      Inserts an item with the text label in the list widget at the position given by row.

      See also addItem().

      Look up this member in the source code.

      Toggle details void QListWidget

      insertItemsinsertItems ( int row , const QStringList &labels ...) ( int row , const QStringList &labels )

      Inserts items from the list of labels into the list, starting at the given row.

      See also insertItem() and addItem().

      Look up this member in the source code.

      Toggle details QListWidgetItem * QListWidget

      itemitem ( int row ) ( int row )const

      Returns the item that occupies the given row in the list if one has been set; otherwise returns 0.

      See also row().

      Look up this member in the source code.

      Toggle details QListWidgetItem * QListWidget

      itemAtitemAt ( const QPoint &p ) ( const QPoint &p )const

      Returns a pointer to the item at the coordinates p. The coordinates are relative to the list widget's viewport().

      Look up this member in the source code.

      Toggle details QListWidgetItem * QListWidget

      itemAtitemAt ( int x , int y ) ( int x , int y )const

      This is an overloaded function.

      Returns a pointer to the item at the coordinates (x, y). The coordinates are relative to the list widget's viewport().

      Look up this member in the source code.

      Toggle details QListWidgetItem * QListWidget

      itemFromIndexitemFromIndex ( const QModelIndex &index ...) ( const QModelIndex &index )const[protected]

      Returns a pointer to the QListWidgetItem assocated with the given index.

      Look up this member in the source code.

      Toggle details QWidget * QListWidget

      itemWidgetitemWidget ( QListWidgetItem *item ) ( QListWidgetItem *item )const

      Returns the widget displayed in the given item.

      See also setItemWidget().

      Look up this member in the source code.

      Toggle details QList <QListWidgetItem *> QListWidget

      itemsitems ( const QMimeData *data ...) ( const QMimeData *data )const[protected]

      Returns a list of pointers to the items contained in the data object. If the object was not created by a QListWidget in the same process, the list is empty.

      Look up this member in the source code.

      Toggle details QMimeData * QListWidget

      mimeDatamimeData ( const QList <QListWidgetItem *>items ...) ( const QList <QListWidgetItem *>items )const [virtual protected]

      Returns an object that contains a serialized description of the specified items. The format used to describe the items is obtained from the mimeTypes() function.

      If the list of items is empty, 0 is returned instead of a serialized empty list.

      Look up this member in the source code.

      Toggle details QStringList QListWidget

      mimeTypesmimeTypes () ()const [virtual protected]

      Returns a list of MIME types that can be used to describe a list of listwidget items.

      See also mimeData().

      Look up this member in the source code.

      Toggle details void QListWidget

      openPersistentEditoropenPersistentEditor ( QListWidgetItem *item ) ( QListWidgetItem *item )

      Opens an editor for the given item. The editor remains open after editing.

      See also closePersistentEditor().

      Look up this member in the source code.

      Toggle details void QListWidget

      removeItemWidgetremoveItemWidget ( QListWidgetItem *item ) ( QListWidgetItem *item )

      Removes the widget set on the given item.

      Look up this member in the source code.

      Toggle details int QListWidget

      rowrow ( const QListWidgetItem *item ) ( const QListWidgetItem *item )const

      Returns the row containing the given item.

      See also item().

      Look up this member in the source code.

      Toggle details QList <QListWidgetItem *> QListWidget

      selectedItemsselectedItems () ()const

      Returns a list of all selected items in the list widget.

      Look up this member in the source code.

      Toggle details void QListWidget

      setCurrentItemsetCurrentItem ( QListWidgetItem *item ) ( QListWidgetItem *item )

      Sets the current item to item.

      Unless the selection mode is NoSelection, the item is also be selected.

      See also currentItem().

      Look up this member in the source code.

      Toggle details void QListWidget

      setCurrentItemsetCurrentItem ( QListWidgetItem *item , QItemSelectionModel::SelectionFlags command ...) ( QListWidgetItem *item , QItemSelectionModel::SelectionFlags command )

      Set the current item to item, using the given command.

      Look up this member in the source code.

      Toggle details void QListWidget

      setItemWidgetsetItemWidget ( QListWidgetItem *item , QWidget *widget ...) ( QListWidgetItem *item , QWidget *widget )

      Sets the widget to be displayed in the give item.

      This function should only be used to display static content in the place of a list widget item. If you want to display custom dynamic content or implement a custom editor widget, use QListView and subclass QItemDelegate instead.

      See also itemWidget() and Delegate Classes.

      Look up this member in the source code.

      Toggle details void QListWidget

      sortItemssortItems ( Qt::SortOrder order=Qt::AscendingOrder ...) ( Qt::SortOrder order=Qt::AscendingOrder )

      Sorts all the items in the list widget according to the specified order.

      Look up this member in the source code.

      Toggle details Qt::DropActions QListWidget

      supportedDropActionssupportedDropActions () ()const [virtual protected]

      Returns the drop actions supported by this view.

      See also Qt::DropActions.

      Look up this member in the source code.

      Toggle details QListWidgetItem * QListWidget

      takeItemtakeItem ( int row ) ( int row )

      Removes and returns the item from the given row in the list widget; otherwise returns 0.

      Items removed from a list widget will not be managed by Qt, and will need to be deleted manually.

      See also insertItem() and addItem().

      Look up this member in the source code.

      Toggle details QRect QListWidget

      visualItemRectvisualItemRect ( const QListWidgetItem *item ) ( const QListWidgetItem *item )const

      Returns the rectangle on the viewport occupied by the item at item.

      Look up this member in the source code.

      Toggle details bool QListWidget

      isItemHiddenisItemHidden ( const QListWidgetItem *item ) ( const QListWidgetItem *item )const Obsolete function

      Returns true if the item is explicitly hidden; otherwise returns false.

      This function is deprecated. Use QListWidgetItem::isHidden() instead.

      Look up this member in the source code.

      Toggle details bool QListWidget

      isItemSelectedisItemSelected ( const QListWidgetItem *item ) ( const QListWidgetItem *item )const Obsolete function

      Returns true if item is selected; otherwise returns false.

      This function is deprecated. Use QListWidgetItem::isSelected() instead.

      Look up this member in the source code.

      Toggle details void QListWidget

      setItemHiddensetItemHidden ( const QListWidgetItem *item , bool hide ...) ( const QListWidgetItem *item , bool hide ) Obsolete function

      If hide is true, the item will be hidden; otherwise it will be shown.

      This function is deprecated. Use QListWidgetItem::setHidden() instead.

      See also isItemHidden().

      Look up this member in the source code.

      Toggle details void QListWidget

      setItemSelectedsetItemSelected ( const QListWidgetItem *item , bool select ...) ( const QListWidgetItem *item , bool select ) Obsolete function

      Selects or deselects the given item depending on whether select is true of false.

      This function is deprecated. Use QListWidgetItem::setSelected() instead.

      See also isItemSelected().

      Look up this member in the source code.

      Signals

      Toggle details void QListWidget

      currentItemChangedcurrentItemChanged ( QListWidgetItem *current , QListWidgetItem *previous ...) ( QListWidgetItem *current , QListWidgetItem *previous ) [signal]

      This signal is emitted whenever the current item changes.

      previous is the item that previously had the focus; current is the new current item.

      Look up this member in the source code.

      Toggle details void QListWidget

      currentRowChangedcurrentRowChanged ( int currentRow ) ( int currentRow ) [signal]

      This signal is emitted whenever the current item changes.

      currentRow is the row of the current item. If there is no current item, the currentRow is -1.

      Look up this member in the source code.

      Toggle details void QListWidget

      currentTextChangedcurrentTextChanged ( const QString &currentText ...) ( const QString &currentText ) [signal]

      This signal is emitted whenever the current item changes.

      currentText is the text data in the current item. If there is no current item, the currentText is invalid.

      Look up this member in the source code.

      Toggle details void QListWidget

      itemActivateditemActivated ( QListWidgetItem *item ) ( QListWidgetItem *item ) [signal]

      This signal is emitted when the item is activated. The item is activated when the user clicks or double clicks on it, depending on the system configuration. It is also activated when the user presses the activation key (on Windows and X11 this is the Return key, on Mac OS X it is Ctrl+0).

      Look up this member in the source code.

      Toggle details void QListWidget

      itemChangeditemChanged ( QListWidgetItem *item ) ( QListWidgetItem *item ) [signal]

      This signal is emitted whenever the data of item has changed.

      Look up this member in the source code.

      Toggle details void QListWidget

      itemClickeditemClicked ( QListWidgetItem *item ) ( QListWidgetItem *item ) [signal]

      This signal is emitted with the specified item when a mouse button is clicked on an item in the widget.

      See also itemPressed() and itemDoubleClicked().

      Look up this member in the source code.

      Toggle details void QListWidget

      itemDoubleClickeditemDoubleClicked ( QListWidgetItem *item ) ( QListWidgetItem *item ) [signal]

      This signal is emitted with the specified item when a mouse button is double clicked on an item in the widget.

      See also itemClicked() and itemPressed().

      Look up this member in the source code.

      Toggle details void QListWidget

      itemEntereditemEntered ( QListWidgetItem *item ) ( QListWidgetItem *item ) [signal]

      This signal is emitted when the mouse cursor enters an item. The item is the item entered. This signal is only emitted when mouseTracking is turned on, or when a mouse button is pressed while moving into an item.

      See also QWidget::setMouseTracking().

      Look up this member in the source code.

      Toggle details void QListWidget

      itemPresseditemPressed ( QListWidgetItem *item ) ( QListWidgetItem *item ) [signal]

      This signal is emitted with the specified item when a mouse button is pressed on an item in the widget.

      See also itemClicked() and itemDoubleClicked().

      Look up this member in the source code.

      Toggle details void QListWidget

      itemSelectionChangeditemSelectionChanged () () [signal]

      This signal is emitted whenever the selection changes.

      See also selectedItems(), QListWidgetItem::isSelected(), and currentItemChanged().

      Look up this member in the source code.

      Public Slots

      Toggle details void QListWidget

      clearclear () () [slot]

      Removes all items and selections in the view.

      Warning: All items will be permanently deleted.

      Look up this member in the source code.

      Toggle details void QListWidget

      scrollToItemscrollToItem ( const QListWidgetItem *item , QAbstractItemView::ScrollHint hint=EnsureVisible ...) ( const QListWidgetItem *item , QAbstractItemView::ScrollHint hint=EnsureVisible ) [slot]

      Scrolls the view if necessary to ensure that the item is visible.

      hint specifies where the item should be located after the operation.

      Look up this member in the source code.

      Notes provided by the Qt Community

      No notes