Table Of Contents

Previous topic

QUndoView

Next topic

QToolBar

QListWidget

Synopsis

Functions

Virtual functions

Slots

Signals

Detailed Description

The PySide.QtGui.QListWidget class provides an item-based list widget.

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

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

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

listWidget = QListWidget(self)

The PySide.QtGui.QAbstractItemView.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 PySide.QtGui.QAbstractItemView.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:

QListWidgetItem(tr("Oak"), listWidget)
QListWidgetItem(tr("Fir"), listWidget)
QListWidgetItem(tr("Pine"), listWidget)

If you need to insert a new item into the list at a particular position, then it should be constructed without a parent widget. The PySide.QtGui.QListWidget.insertItem() function should then be used to place it within the list. The list widget will take ownership of the item.

newItem = QListWidgetItem()
newItem.setText(itemText)
listWidget.insertItem(row, newItem)

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

The current item in the list can be found with PySide.QtGui.QListWidget.currentItem() , and changed with PySide.QtGui.QListWidget.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 PySide.QtGui.QListWidget.currentItemChanged() signal is emitted with the new current item and the item that was previously current.

../../_images/windowsxp-listview.png ../../_images/macintosh-listview.png ../../_images/plastique-listview.png
A Windows XP style list widget. A Macintosh style list widget. A Plastique style list widget.

See also

PySide.QtGui.QListWidgetItem PySide.QtGui.QListView PySide.QtGui.QTreeView Model/View Programming Config Dialog Example

class PySide.QtGui.QListWidget([parent=None])
Parameters:parentPySide.QtGui.QWidget

Constructs an empty PySide.QtGui.QListWidget with the given parent .

PySide.QtGui.QListWidget.addItem(label)
Parameters:label – unicode

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

PySide.QtGui.QListWidget.addItem(item)
Parameters:itemPySide.QtGui.QListWidgetItem

Inserts the item at the end of the list widget.

Warning

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

PySide.QtGui.QListWidget.addItems(labels)
Parameters:labels – list of strings

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

PySide.QtGui.QListWidget.clear()

Removes all items and selections in the view.

Warning

All items will be permanently deleted.

PySide.QtGui.QListWidget.closePersistentEditor(item)
Parameters:itemPySide.QtGui.QListWidgetItem

Closes the persistent editor for the given item .

PySide.QtGui.QListWidget.count()
Return type:PySide.QtCore.int

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

PySide.QtGui.QListWidget.currentItem()
Return type:PySide.QtGui.QListWidgetItem

Returns the current item.

PySide.QtGui.QListWidget.currentItemChanged(current, previous)
Parameters:
PySide.QtGui.QListWidget.currentRow()
Return type:PySide.QtCore.int

This property holds the row of the current item..

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

PySide.QtGui.QListWidget.currentRowChanged(currentRow)
Parameters:currentRowPySide.QtCore.int
PySide.QtGui.QListWidget.currentTextChanged(currentText)
Parameters:currentText – unicode
PySide.QtGui.QListWidget.dropMimeData(index, data, action)
Parameters:
Return type:

PySide.QtCore.bool

PySide.QtGui.QListWidget.editItem(item)
Parameters:itemPySide.QtGui.QListWidgetItem

Starts editing the item if it is editable.

PySide.QtGui.QListWidget.findItems(text, flags)
Parameters:
  • text – unicode
  • flagsPySide.QtCore.Qt.MatchFlags
Return type:

PySide.QtGui.QListWidget.indexFromItem(item)
Parameters:itemPySide.QtGui.QListWidgetItem
Return type:PySide.QtCore.QModelIndex

Returns the PySide.QtCore.QModelIndex assocated with the given item .

PySide.QtGui.QListWidget.insertItem(row, label)
Parameters:
  • rowPySide.QtCore.int
  • label – unicode

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

PySide.QtGui.QListWidget.insertItem(row, item)
Parameters:

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

PySide.QtGui.QListWidget.insertItems(row, labels)
Parameters:
  • rowPySide.QtCore.int
  • labels – list of strings

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

PySide.QtGui.QListWidget.isSortingEnabled()
Return type:PySide.QtCore.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.

PySide.QtGui.QListWidget.item(row)
Parameters:rowPySide.QtCore.int
Return type:PySide.QtGui.QListWidgetItem

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

PySide.QtGui.QListWidget.itemActivated(item)
Parameters:itemPySide.QtGui.QListWidgetItem
PySide.QtGui.QListWidget.itemAt(x, y)
Parameters:
  • xPySide.QtCore.int
  • yPySide.QtCore.int
Return type:

PySide.QtGui.QListWidgetItem

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 PySide.QtGui.QAbstractScrollArea.viewport() .

PySide.QtGui.QListWidget.itemAt(p)
Parameters:pPySide.QtCore.QPoint
Return type:PySide.QtGui.QListWidgetItem

Returns a pointer to the item at the coordinates p . The coordinates are relative to the list widget’s PySide.QtGui.QAbstractScrollArea.viewport() .

PySide.QtGui.QListWidget.itemChanged(item)
Parameters:itemPySide.QtGui.QListWidgetItem
PySide.QtGui.QListWidget.itemClicked(item)
Parameters:itemPySide.QtGui.QListWidgetItem
PySide.QtGui.QListWidget.itemDoubleClicked(item)
Parameters:itemPySide.QtGui.QListWidgetItem
PySide.QtGui.QListWidget.itemEntered(item)
Parameters:itemPySide.QtGui.QListWidgetItem
PySide.QtGui.QListWidget.itemFromIndex(index)
Parameters:indexPySide.QtCore.QModelIndex
Return type:PySide.QtGui.QListWidgetItem

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

PySide.QtGui.QListWidget.itemPressed(item)
Parameters:itemPySide.QtGui.QListWidgetItem
PySide.QtGui.QListWidget.itemSelectionChanged()
PySide.QtGui.QListWidget.itemWidget(item)
Parameters:itemPySide.QtGui.QListWidgetItem
Return type:PySide.QtGui.QWidget

Returns the widget displayed in the given item .

PySide.QtGui.QListWidget.items(data)
Parameters:dataPySide.QtCore.QMimeData
Return type:

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

PySide.QtGui.QListWidget.mimeData(items)
Parameters:items
Return type:PySide.QtCore.QMimeData
PySide.QtGui.QListWidget.mimeTypes()
Return type:list of strings

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

PySide.QtGui.QListWidget.openPersistentEditor(item)
Parameters:itemPySide.QtGui.QListWidgetItem

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

PySide.QtGui.QListWidget.removeItemWidget(item)
Parameters:itemPySide.QtGui.QListWidgetItem

Removes the widget set on the given item .

PySide.QtGui.QListWidget.row(item)
Parameters:itemPySide.QtGui.QListWidgetItem
Return type:PySide.QtCore.int

Returns the row containing the given item .

PySide.QtGui.QListWidget.scrollToItem(item[, hint=EnsureVisible])
Parameters:
PySide.QtGui.QListWidget.selectedItems()
Return type:

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

PySide.QtGui.QListWidget.setCurrentItem(item, command)
Parameters:
PySide.QtGui.QListWidget.setCurrentItem(item)
Parameters:itemPySide.QtGui.QListWidgetItem

Sets the current item to item .

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

PySide.QtGui.QListWidget.setCurrentRow(row)
Parameters:rowPySide.QtCore.int

This property holds the row of the current item..

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

PySide.QtGui.QListWidget.setCurrentRow(row, command)
Parameters:
  • rowPySide.QtCore.int
  • commandPySide.QtGui.QItemSelectionModel.SelectionFlags
PySide.QtGui.QListWidget.setItemWidget(item, widget)
Parameters:

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 PySide.QtGui.QListView and subclass PySide.QtGui.QItemDelegate instead.

See also

PySide.QtGui.QListWidget.itemWidget() Delegate Classes

PySide.QtGui.QListWidget.setSortingEnabled(enable)
Parameters:enablePySide.QtCore.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.

PySide.QtGui.QListWidget.sortItems([order=Qt.AscendingOrder])
Parameters:orderPySide.QtCore.Qt.SortOrder
PySide.QtGui.QListWidget.sortOrder()
Return type:PySide.QtCore.Qt.SortOrder
PySide.QtGui.QListWidget.supportedDropActions()
Return type:PySide.QtCore.Qt.DropActions

Returns the drop actions supported by this view.

See also

Qt.DropActions

PySide.QtGui.QListWidget.takeItem(row)
Parameters:rowPySide.QtCore.int
Return type:PySide.QtGui.QListWidgetItem

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.

PySide.QtGui.QListWidget.visualItemRect(item)
Parameters:itemPySide.QtGui.QListWidgetItem
Return type:PySide.QtCore.QRect

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