Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.trolltech.qt.gui
Class QStandardItemModel

    java.lang.Object
      com.trolltech.qt.QSignalEmitter
          com.trolltech.qt.QtJambiObject
              com.trolltech.qt.core.QObject
                  com.trolltech.qt.core.QAbstractItemModel
                      com.trolltech.qt.gui.QStandardItemModel

All Implemented Interfaces:
  QtJambiInterface

    public class QStandardItemModel

extends QAbstractItemModel

The `QStandardItemModel` class provides a generic model for storing custom data. `QStandardItemModel` can be used as a repository for standard Qt data types. It is one of the Model/View Classes and is part of Qt's model/view framework.

`QStandardItemModel` provides a classic item-based approach to working with the model. The items in a `QStandardItemModel` are provided by `QStandardItem`.

`QStandardItemModel` implements the `QAbstractItemModel` interface, which means that the model can be used to provide data in any view that supports that interface (such as `QListView`, `QTableView` and `QTreeView`, and your own custom views). For performance and flexibility, you may want to subclass `QAbstractItemModel` to provide support for different kinds of data repositories. For example, the `QDirModel` provides a model interface to the underlying file system.

When you want a list or tree, you typically create an empty `QStandardItemModel` and use `appendRow()` to add items to the model, and `item()` to access an item. If your model represents a table, you typically pass the dimensions of the table to the `QStandardItemModel` constructor and use `setItem()` to position items into the table. You can also use `setRowCount()` and `setColumnCount()` to alter the dimensions of the model. To insert items, use `insertRow()` or `insertColumn()`, and to remove items, use `removeRow()` or `removeColumn()`.

You can set the header labels of your model with `setHorizontalHeaderLabels()` and `setVerticalHeaderLabels()`.

You can search for items in the model with `findItems()`, and sort the model by calling `sort()`.

Call `clear()` to remove all items from the model.

An example usage of `QStandardItemModel` to create a table:

                QStandardItemModel model(4, 4);
                for (int row = 0; row < 4; ++row) {
                    for (int column = 0; column < 4; ++column) {
                        QStandardItem *item = new QStandardItem(QString("row %0, column %1").arg(row).arg(column));
                        model.setItem(row, column, item);
                    }
                }

An example usage of `QStandardItemModel` to create a tree:

                QStandardItemModel model;
                QStandardItem *parentItem = model.invisibleRootItem();
                for (int i = 0; i < 4; ++i) {
                    QStandardItem *item = new QStandardItem(QString("item %0").arg(i));
                    parentItem->appendRow(item);
                    parentItem = item;
                }

After setting the model on a view, you typically want to react to user actions, such as an item being clicked. Since a `QAbstractItemView` provides QModelIndex-based signals and functions, you need a way to obtain the `QStandardItem` that corresponds to a given QModelIndex, and vice versa. `itemFromIndex()` and `indexFromItem()` provide this mapping. Typical usage of `itemFromIndex()` includes obtaining the item at the current index in a view, and obtaining the item that corresponds to an index carried by a `QAbstractItemView` signal, such as `QAbstractItemView::clicked()` . First you connect the view's signal to a slot in your class:

            QTreeView *treeView = new QTreeView(this);
            treeView->setModel(myStandardItemModel);
            connect(treeView, SIGNAL(clicked(QModelIndex)),
                    this, SLOT(clicked(QModelIndex)));

When you receive the signal, you call `itemFromIndex()` on the given model index to get a pointer to the item:

            void MyWidget::clicked(const QModelIndex &index)
            {
                QStandardItem *item = myStandardItemModel->itemFromIndex(index);
                // Do stuff with the item ...
            }

Conversely, you must obtain the QModelIndex of an item when you want to invoke a model/view function that takes an index as argument. You can obtain the index either by using the model's `indexFromItem()` function, or, equivalently, by calling `QStandardItem::index()`:

            treeView->scrollTo(item->index());

You are, of course, not required to use the item-based approach; you could instead rely entirely on the `QAbstractItemModel` interface when working with the model, or use a combination of the two as appropriate.

See also:
  `QStandardItem`, Model/View Programming, `QAbstractItemModel`, Simple Tree Model example, and Item View Convenience Classes.

Nested Class Summary

Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter
`QSignalEmitter.Signal0, QSignalEmitter.Signal1, QSignalEmitter.Signal2, QSignalEmitter.Signal3, QSignalEmitter.Signal4, QSignalEmitter.Signal5, QSignalEmitter.Signal6, QSignalEmitter.Signal7, QSignalEmitter.Signal8, QSignalEmitter.Signal9`

Field Summary
`QSignalEmitter.Signal1` | `itemChanged` This signal is emitted whenever the data of `item` has changed.

Fields inherited from class com.trolltech.qt.core.QAbstractItemModel
`dataChanged, headerDataChanged, layoutAboutToBeChanged, layoutChanged`

Constructor Summary
`QStandardItemModel()` Constructs a new item model with the given `parent`.
`QStandardItemModel(int rows, int columns)` Constructs a new item model that initially has `rows` rows and `columns` columns, and that has the given `parent`.
`QStandardItemModel(int rows, int columns, QObject parent)` Constructs a new item model that initially has `rows` rows and `columns` columns, and that has the given `parent`.
`QStandardItemModel(QObject parent)` Constructs a new item model with the given `parent`.

Method Summary
`void` | `appendColumn(java.util.List items)` Appends a column containing `items`.
`void` | `appendRow(java.util.List items)` Appends a row containing `items`.
`void` | `appendRow(QStandardItem item)` When building a list or a tree that has only one column, this function provides a convenient way to append a single new `item`.
`void` | `clear()` Removes all items (including header items) from the model and sets the number of rows and columns to zero.
`java.util.List` | `findItems(java.lang.String text)` Returns a list of items that match the given `text`.
`java.util.List` | `findItems(java.lang.String text, Qt.MatchFlags flags)` Returns a list of items that match the given `text`, using the given `flags`, in the given `column`.
`java.util.List` | `findItems(java.lang.String text, Qt.MatchFlags flags, int column)` Returns a list of items that match the given `text`, using the given `flags`, in the given `column`.
`static QStandardItemModel` | `fromNativePointer(QNativePointer nativePointer)` This method returns the QStandardItemModel instance pointed to by `nativePointer`.
`QStandardItem` | `horizontalHeaderItem(int column)` Returns the horizontal header item for `column` if one has been set; otherwise returns 0.
`QModelIndex` | `indexFromItem(QStandardItem item)` Returns the QModelIndex associated with the given `item`.
`void` | `insertColumn(int column, java.util.List items)` Inserts a column at `column` containing `items`.
`void` | `insertRow(int row, java.util.List items)` Inserts a row at `row` containing `items`.
`void` | `insertRow(int row, QStandardItem item)` Inserts a row at `row` containing `item`.
`QStandardItem` | `invisibleRootItem()` Returns the model's invisible root item.
`QStandardItem` | `item(int row)` Returns the item for the given `row` and `column` if one has been set; otherwise returns 0.
`QStandardItem` | `item(int row, int column)` Returns the item for the given `row` and `column` if one has been set; otherwise returns 0.
`QStandardItem` | `itemFromIndex(QModelIndex index)` Returns a pointer to the `QStandardItem` associated with the given `index`.
`QStandardItem` | `itemPrototype()` Returns the item prototype used by the model.
`void` | `setColumnCount(int columns)` Sets the number of columns in this model to `columns`.
`void` | `setHorizontalHeaderItem(int column, QStandardItem item)` Sets the horizontal header item for `column` to `item`.
`void` | `setHorizontalHeaderLabels(java.util.List labels)` Sets the horizontal header labels using `labels`.
`void` | `setItem(int row, int column, QStandardItem item)` Sets the item for the given `row` and `column` to `item`.
`void` | `setItem(int row, QStandardItem item)` This is an overloaded method provided for convenience.
`void` | `setItemPrototype(QStandardItem item)` Sets the item prototype for the model to the specified `item`.
`void` | `setRowCount(int rows)` Sets the number of rows in this model to `rows`.
`void` | `setSortRole(int role)` This property holds the item role that is used to query the model's data when sorting items.
`void` | `setVerticalHeaderItem(int row, QStandardItem item)` Sets the vertical header item for `row` to `item`.
`void` | `setVerticalHeaderLabels(java.util.List labels)` Sets the vertical header labels using `labels`.
`int` | `sortRole()` This property holds the item role that is used to query the model's data when sorting items.
`java.util.List` | `takeColumn(int column)` Removes the given `column` without deleting the column items, and returns a list of pointers to the removed items.
`QStandardItem` | `takeHorizontalHeaderItem(int column)` Removes the horizontal header item at `column` from the header without deleting it, and returns a pointer to the item.
`QStandardItem` | `takeItem(int row)` Removes the item at (`row`, `column`) without deleting it.
`QStandardItem` | `takeItem(int row, int column)` Removes the item at (`row`, `column`) without deleting it.
`java.util.List` | `takeRow(int row)` Removes the given `row` without deleting the row items, and returns a list of pointers to the removed items.
`QStandardItem` | `takeVerticalHeaderItem(int row)` Removes the vertical header item at `row` from the header without deleting it, and returns a pointer to the item.
`QStandardItem` | `verticalHeaderItem(int row)` Returns the vertical header item for row `row` if one has been set; otherwise returns 0.

Methods inherited from class com.trolltech.qt.core.QAbstractItemModel
`beginInsertColumns, beginInsertRows, beginRemoveColumns, beginRemoveRows, buddy, canFetchMore, changePersistentIndex, changePersistentIndexList, columnCount, columnCount, createIndex, createIndex, createIndex, data, data, data, data, dropMimeData, endInsertColumns, endInsertRows, endRemoveColumns, endRemoveRows, fetchMore, flags, hasChildren, hasChildren, hasIndex, hasIndex, headerData, headerData, index, index, insertColumn, insertColumn, insertColumns, insertColumns, insertRow, insertRow, insertRows, insertRows, itemData, match, match, match, match, mimeData, mimeTypes, parent, persistentIndexList, removeColumn, removeColumn, removeColumns, removeColumns, removeRow, removeRow, removeRows, removeRows, reset, revert, rowCount, rowCount, setData, setData, setData, setData, setHeaderData, setHeaderData, setItemData, setSupportedDragActions, setSupportedDragActions, sibling, sort, sort, span, submit, supportedDragActions, supportedDropActions`

Methods inherited from class com.trolltech.qt.core.QObject
`childEvent, children, connectSlotsByName, customEvent, disposeLater, dumpObjectInfo, dumpObjectTree, dynamicPropertyNames, event, eventFilter, findChild, findChild, findChild, findChildren, findChildren, findChildren, findChildren, indexOfProperty, installEventFilter, isWidgetType, killTimer, moveToThread, objectName, parent, properties, property, removeEventFilter, setObjectName, setParent, setProperty, startTimer, timerEvent, toString, userProperty`

Methods inherited from class com.trolltech.qt.QtJambiObject
`dispose, disposed, equals, finalize, reassignNativeResources, tr, tr, tr`

Methods inherited from class com.trolltech.qt.QSignalEmitter
`blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread`

Methods inherited from class java.lang.Object
`clone, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Methods inherited from interface com.trolltech.qt.QtJambiInterface
`disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership`

Field Detail

### itemChanged

    public final QSignalEmitter.Signal1 itemChanged

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

Constructor Detail

### QStandardItemModel

    public QStandardItemModel()

  Constructs a new item model with the given `parent`.

### QStandardItemModel

    public QStandardItemModel(QObject parent)

  Constructs a new item model with the given `parent`.

### QStandardItemModel

    public QStandardItemModel(int rows,
                              int columns)

  Constructs a new item model that initially has `rows` rows and `columns` columns, and that has the given `parent`.

### QStandardItemModel

    public QStandardItemModel(int rows,
                              int columns,
                              QObject parent)

  Constructs a new item model that initially has `rows` rows and `columns` columns, and that has the given `parent`.

Method Detail

### appendColumn

    public final void appendColumn(java.util.List items)

  Appends a column containing `items`. If necessary, the row count is increased to the size of `items`.

See also:
  `insertColumn()`, and `appendRow()`.

### appendRow

    public final void appendRow(QStandardItem item)

  When building a list or a tree that has only one column, this function provides a convenient way to append a single new `item`.

### appendRow

    public final void appendRow(java.util.List items)

  Appends a row containing `items`. If necessary, the column count is increased to the size of `items`.

See also:
  `insertRow()`, and `appendColumn()`.

### clear

    public final void clear()

  Removes all items (including header items) from the model and sets the number of rows and columns to zero.

See also:
  `removeColumns()`, and `removeRows()`.

### findItems

    public final java.util.List findItems(java.lang.String text,
                                          Qt.MatchFlags flags)

  Returns a list of items that match the given `text`, using the given `flags`, in the given `column`.

### findItems

    public final java.util.List findItems(java.lang.String text)

  Returns a list of items that match the given `text`.

### findItems

    public final java.util.List findItems(java.lang.String text,
                                          Qt.MatchFlags flags,
                                          int column)

  Returns a list of items that match the given `text`, using the given `flags`, in the given `column`.

### horizontalHeaderItem

    public final QStandardItem horizontalHeaderItem(int column)

  Returns the horizontal header item for `column` if one has been set; otherwise returns 0.

See also:
  `setHorizontalHeaderItem()`, and `verticalHeaderItem()`.

### indexFromItem

    public final QModelIndex indexFromItem(QStandardItem item)

  Returns the QModelIndex associated with the given `item`.

  Use this function when you want to perform an operation that requires the QModelIndex of the item, such as `QAbstractItemView::scrollTo()`. `QStandardItem::index()` is provided as convenience; it is equivalent to calling this function.

See also:
  `itemFromIndex()`, and `QStandardItem::index()`.

### insertColumn

    public final void insertColumn(int column,
                                   java.util.List items)

  Inserts a column at `column` containing `items`. If necessary, the row count is increased to the size of `items`.

See also:
  `takeColumn()`, `appendColumn()`, and `insertRow()`.

### insertRow

    public final void insertRow(int row,
                                QStandardItem item)

  Inserts a row at `row` containing `item`.

  When building a list or a tree that has only one column, this function provides a convenient way to append a single new item.

### insertRow

    public final void insertRow(int row,
                                java.util.List items)

  Inserts a row at `row` containing `items`. If necessary, the column count is increased to the size of `items`.

See also:
  `takeRow()`, `appendRow()`, and `insertColumn()`.

### invisibleRootItem

    public final QStandardItem invisibleRootItem()

  Returns the model's invisible root item.

  The invisible root item provides access to the model's top-level items through the `QStandardItem` API, making it possible to write functions that can treat top-level items and their children in a uniform way; for example, recursive functions involving a tree model.

  Note: Calling `index()` on the `QStandardItem` object retrieved from this function is not valid.

### item

    public final QStandardItem item(int row)

  Returns the item for the given `row` and `column` if one has been set; otherwise returns 0.

See also:
  `setItem()`, `takeItem()`, and `itemFromIndex()`.

### item

    public final QStandardItem item(int row,
                                    int column)

  Returns the item for the given `row` and `column` if one has been set; otherwise returns 0.

See also:
  `setItem()`, `takeItem()`, and `itemFromIndex()`.

### itemFromIndex

    public final QStandardItem itemFromIndex(QModelIndex index)

  Returns a pointer to the `QStandardItem` associated with the given `index`.

  Calling this function is typically the initial step when processing QModelIndex-based signals from a view, such as `QAbstractItemView::activated()` . In your slot, you call `itemFromIndex()`, with the QModelIndex carried by the signal as argument, to obtain a pointer to the corresponding `QStandardItem`.

  Note that this function will lazily create an item for the index (using `itemPrototype()`), and set it in the parent item's child table, if no item already exists at that index.

  If `index` is an invalid index, this function returns 0.

See also:
  `indexFromItem()`.

### itemPrototype

    public final QStandardItem itemPrototype()

  Returns the item prototype used by the model. The model uses the item prototype as an item factory when it needs to construct new items on demand (for instance, when a view or item delegate calls `setData()`).

See also:
  `setItemPrototype()`.

### setColumnCount

    public final void setColumnCount(int columns)

  Sets the number of columns in this model to `columns`. If this is less than `columnCount()`, the data in the unwanted columns is discarded.

See also:
  `setRowCount()`.

### setHorizontalHeaderItem

    public final void setHorizontalHeaderItem(int column,
                                              QStandardItem item)

  Sets the horizontal header item for `column` to `item`. The model takes ownership of the item. If necessary, the column count is increased to fit the item. The previous header item (if there was one) is deleted.

See also:
  `horizontalHeaderItem()`, `setHorizontalHeaderLabels()`, and `setVerticalHeaderItem()`.

### setHorizontalHeaderLabels

    public final void setHorizontalHeaderLabels(java.util.List labels)

  Sets the horizontal header labels using `labels`. If necessary, the column count is increased to the size of `labels`.

See also:
  `setHorizontalHeaderItem()`.

### setItem

    public final void setItem(int row,
                              QStandardItem item)

  This is an overloaded method provided for convenience. It is equal to setItem(`row`, 0, `item`).

### setItem

    public final void setItem(int row,
                              int column,
                              QStandardItem item)

  Sets the item for the given `row` and `column` to `item`. The model takes ownership of the item. If necessary, the row count and column count are increased to fit the item. The previous item at the given location (if there was one) is deleted.

See also:
  `item()`.

### setItemPrototype

    public final void setItemPrototype(QStandardItem item)

  Sets the item prototype for the model to the specified `item`. The model takes ownership of the prototype.

  The item prototype acts as a `QStandardItem` factory, by relying on the `QStandardItem::clone()` function. To provide your own prototype, subclass `QStandardItem`, reimplement `QStandardItem::clone()` and set the prototype to be an instance of your custom class. Whenever `QStandardItemModel` needs to create an item on demand (for instance, when a view or item delegate calls `setData()`)), the new items will be instances of your custom class.

See also:
  `itemPrototype()`, and `QStandardItem::clone()`.

### setRowCount

    public final void setRowCount(int rows)

  Sets the number of rows in this model to `rows`. If this is less than `rowCount()`, the data in the unwanted rows is discarded.

See also:
  `setColumnCount()`.

### setSortRole

    public final void setSortRole(int role)

  This property holds the item role that is used to query the model's data when sorting items. The default value is `Qt::DisplayRole` .

See also:
  `sort()`, and `QStandardItem::sortChildren()`.

### setVerticalHeaderItem

    public final void setVerticalHeaderItem(int row,
                                            QStandardItem item)

  Sets the vertical header item for `row` to `item`. The model takes ownership of the item. If necessary, the row count is increased to fit the item. The previous header item (if there was one) is deleted.

See also:
  `verticalHeaderItem()`, `setVerticalHeaderLabels()`, and `setHorizontalHeaderItem()`.

### setVerticalHeaderLabels

    public final void setVerticalHeaderLabels(java.util.List labels)

  Sets the vertical header labels using `labels`. If necessary, the row count is increased to the size of `labels`.

See also:
  `setVerticalHeaderItem()`.

### sortRole

    public final int sortRole()

  This property holds the item role that is used to query the model's data when sorting items. The default value is `Qt::DisplayRole` .

See also:
  `sort()`, and `QStandardItem::sortChildren()`.

### takeColumn

    public final java.util.List takeColumn(int column)

  Removes the given `column` without deleting the column items, and returns a list of pointers to the removed items. The model releases ownership of the items. For items in the column that have not been set, the corresponding pointers in the list will be 0.

See also:
  `takeRow()`.

### takeHorizontalHeaderItem

    public final QStandardItem takeHorizontalHeaderItem(int column)

  Removes the horizontal header item at `column` from the header without deleting it, and returns a pointer to the item. The model releases ownership of the item.

See also:
  `horizontalHeaderItem()`, and `takeVerticalHeaderItem()`.

### takeItem

    public final QStandardItem takeItem(int row)

  Removes the item at (`row`, `column`) without deleting it. The model releases ownership of the item.

See also:
  `item()`, `takeRow()`, and `takeColumn()`.

### takeItem

    public final QStandardItem takeItem(int row,
                                        int column)

  Removes the item at (`row`, `column`) without deleting it. The model releases ownership of the item.

See also:
  `item()`, `takeRow()`, and `takeColumn()`.

### takeRow

    public final java.util.List takeRow(int row)

  Removes the given `row` without deleting the row items, and returns a list of pointers to the removed items. The model releases ownership of the items. For items in the row that have not been set, the corresponding pointers in the list will be 0.

See also:
  `takeColumn()`.

### takeVerticalHeaderItem

    public final QStandardItem takeVerticalHeaderItem(int row)

  Removes the vertical header item at `row` from the header without deleting it, and returns a pointer to the item. The model releases ownership of the item.

See also:
  `verticalHeaderItem()`, and `takeHorizontalHeaderItem()`.

### verticalHeaderItem

    public final QStandardItem verticalHeaderItem(int row)

  Returns the vertical header item for row `row` if one has been set; otherwise returns 0.

See also:
  `setVerticalHeaderItem()`, and `horizontalHeaderItem()`.

### fromNativePointer

    public static QStandardItemModel fromNativePointer(QNativePointer nativePointer)

  This method returns the QStandardItemModel instance pointed to by `nativePointer`.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD