QSmoothList Class Reference
[QtBaseModule]

Detailed Description

The QSmoothList class provides a view onto a model using a finger scrollable user interface.

QSmoothList implements the interfaces defined by the QAbstractItemView class to allow it to display data provided by models derived from the QAbstractItemModel class. A QSmoothList presents items stored in a model as a simple non-hierarchical list, or in a single-column hierarchical tree. If QSmoothList is provided with a hierarchical model, it will correctly reflect the hierarchy of model items, but only row zero of each QModelIndex is used to present a view of the items.

QSmoothList is designed to offer a similar interface to QListView; the primary difference is that QSmoothList allows the list position to be manipulated with a finger, facilitating use in touch-screen devices. QSmoothList also offers a subset of the QTreeView interface; items can be programmatically expanded or collapsed. Unlike QTreeView, however, QSmoothList does not support the use of a QHeaderView, and does not support multiple-column presentation.

The location of the QSmoothList can be manipulated by dragging, or by a 'flick' gesture. A flick occurs when a vertical movement is interrupted by a release - a momentum is then imparted to the list which continues to move in the initial direction, subject to a deceleration. The list can also be moved by key events if a suitable input device is available.

A QSmoothList can be used in single-selection mode, or in no-selection mode. Multiple selection is not supported, and must instead be implemented outside the QSmoothList, via a 'checkable' property of the model's items, or similar. Since multiple selection is not supported, QSmoothList does not differentiate between 'selected' and 'current' indices.

QSmoothList supports items of variable heights, as reported by the sizeHint() function of the delegate used to present the list items. However, QSmoothList does not support grid spacing. It is recommended that the delegate used with the QSmoothList should enforce height constraints, to achieve a presentation where items with variable sizes are displayed with uniform space allocations.

Member Type Documentation

enum QSmoothList::ScrollHint

enum QSmoothList::SelectionMode

This enum indicates how the list responds to user selections:

Member Function Documentation

QSmoothList::QSmoothList ( QWidget * parent = 0, Qt::WFlags flags = 0 )

Creates a new QSmoothList with the given parent and flags to view a model. Use setModel() to set the model.

QSmoothList::~QSmoothList ()   [virtual]

Destroys the list.

void QSmoothList::activated ( const QModelIndex & index )   [signal]

This signal is emitted when the item specified by index is activated by the user. How to activate items depends on the platform; e.g., by single- or double-clicking the item, or by pressing the Return or Enter key when the item is current.

See also clicked(), doubleClicked(), and pressed().

void QSmoothList::clearSelection ()   [slot]

Deselects the selected item, if any.

void QSmoothList::clicked ( const QModelIndex & index )   [signal]

This signal is emitted when a mouse button is clicked. The item the mouse was clicked on is specified by index. The signal is only emitted when the index is valid.

See also activated(), doubleClicked(), and pressed().

void QSmoothList::collapse ( const QModelIndex & index )   [slot]

Collapses the model item specified by the index.

See also collapsed().

void QSmoothList::collapseAll ()   [slot]

Collapses all expanded items.

See also expandAll(), expand(), collapse(), and setExpanded().

void QSmoothList::collapsed ( const QModelIndex & index )   [signal]

This signal is emitted when the item specified by index is collapsed.

See also expanded() and setExpanded().

void QSmoothList::currentChanged ( const QModelIndex & current, const QModelIndex & previous )   [signal]

This signal is emitted when a new item becomes the current item. The previous current item is specified by the previous index, and the new item by the current index.

See also currentIndex() and setCurrentIndex().

QModelIndex QSmoothList::currentIndex () const

Returns the model index of the current item, if any.

See also setCurrentIndex().

void QSmoothList::doubleClicked ( const QModelIndex & index )   [signal]

This signal is emitted when a mouse button is double-clicked. The item the mouse was double-clicked on is specified by index. The signal is only emitted when the index is valid.

See also clicked() and activated().

void QSmoothList::expand ( const QModelIndex & index )   [slot]

Expands the model item specified by the index.

See also expanded().

void QSmoothList::expandAll ()   [slot]

Expands all expandable items.

See also collapseAll(), expand(), collapse(), and setExpanded().

void QSmoothList::expanded ( const QModelIndex & index )   [signal]

This signal is emitted when the item specified by index is expanded.

See also collapsed() and setExpanded().

bool QSmoothList::hasOpaqueItemBackground () const

Returns true if the list has been set to paint items with opaque backgrounds.

QSize QSmoothList::iconSize () const

Returns the size at which icons should be drawn when painting list items.

See also setIconSize().

QModelIndex QSmoothList::indexAt ( const QPoint & point ) const

Returns the model index of the item at the viewport coordinates point.

See also visualRect().

bool QSmoothList::isExpanded ( const QModelIndex & index ) const

Returns true if the model item index is expanded; otherwise returns false.

See also expand(), expanded(), and setExpanded().

QAbstractItemDelegate * QSmoothList::itemDelegate () const

Returns the item delegate used by this view and model. This is either one set with setItemDelegate(), or the default one.

See also setItemDelegate().

QAbstractItemModel * QSmoothList::model () const

Returns the model that this list is viewing.

See also setModel().

void QSmoothList::pressed ( const QModelIndex & index )   [signal]

This signal is emitted when a mouse button is pressed. The item the mouse was pressed on is specified by index. The signal is only emitted when the index is valid.

Use the QApplication::mouseButtons() function to get the state of the mouse buttons.

See also activated(), clicked(), and doubleClicked().

void QSmoothList::reset ()   [slot]

Reset the internal state of the list.

void QSmoothList::scrollTo ( const QModelIndex & index, ScrollHint hint = EnsureVisible )

Scrolls the list if necessary to ensure that the item at index is visible. The list will try to position the item according to the given hint.

void QSmoothList::scrollToBottom ()   [slot]

Scrolls the list to the bottom.

See also scrollTo() and scrollToTop().

void QSmoothList::scrollToTop ()   [slot]

Scrolls the list to the top.

See also scrollTo() and scrollToBottom().

SelectionMode QSmoothList::selectionMode () const

Returns the selection mode of the list.

See also setSelectionMode().

void QSmoothList::setCurrentIndex ( const QModelIndex & index, ScrollHint hint = EnsureVisible )   [slot]

Sets the current item to be the item at index, and if necessary scrolls the list to position the item according to hint. The item will be selected unless selectionMode() is NoSelection.

See also currentIndex(), currentChanged(), and selectionMode().

void QSmoothList::setEmptyText ( const QString & text )

Sets the string text to be displayed instead of the list, when no items are present.

void QSmoothList::setExpanded ( const QModelIndex & index, bool set )

Sets the item referred to by index to either collapsed or expanded, depending on the value of set.

See also expanded(), expand(), and isExpanded().

void QSmoothList::setIconSize ( const QSize & size )

Sets the size at which icons should be drawn when painting list items to size.

Setting this property when the view is visible will cause the items to be laid out again.

See also iconSize().

void QSmoothList::setItemDelegate ( QAbstractItemDelegate * delegate )

Sets the item delegate for this list to delegate. This is useful if you want complete control over the editing and display of items.

Setting this property when the view is visible will cause the items to be laid out again.

See also itemDelegate().

void QSmoothList::setModel ( QAbstractItemModel * model )

Sets the model for the list to present.

The current selection index is reset.

See also model().

void QSmoothList::setOpaqueItemBackground ( bool opaque )

Sets the list items to be painted with opaque backgrounds, if opaque is true. Otherwise, the list items will be painted with transparent backgrounds.

See also hasOpaqueItemBackground().

void QSmoothList::setSelectionMode ( SelectionMode mode )

Sets the selection mode of the list to mode. Multiple-item selection modes are not supported by QSmoothList.

See also selectionMode().

void QSmoothList::setTextElideMode ( Qt::TextElideMode mode )

Sets the mode used to elide text when painting list items to mode.

See also textElideMode().

Qt::TextElideMode QSmoothList::textElideMode () const

Returns the mode used to elide text when painting list items.

See also setTextElideMode().

void QSmoothList::update ( const QModelIndex & index )   [slot]

Updates the area occupied by the given index.

QRect QSmoothList::visualRect ( const QModelIndex & index ) const

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

See also indexAt().