Class QtAbstractItemModel

java.lang.Object
org.qtproject.qt.android.QtAbstractItemModel
Direct Known Subclasses:
QtAbstractListModel
public abstract class QtAbstractItemModel extends Object
QtAbstractItemModel is a base class for implementing custom models in Java, similar to the QAbstractItemModel class. The QtAbstractItemModel class defines the standard interface that item models must use to be able to interoperate with other components in the model/view architecture. It is not supposed to be instantiated directly. Instead, you should extend it to create new models. A QtAbstractItemModel can be used as the underlying data model for the item view elements in QML. If you need a model to use with an item view, such as QML's ListView element, you should consider extending QtAbstractListModel instead of this class. The underlying data model is exposed to views and delegates as a hierarchy of tables. If you do not use the hierarchy, the model is a simple table of rows and columns. Each item has a unique index specified by a QtModelIndex. Every item of data that can be accessed via a model has an associated model index. You can obtain this model index using the index(int, int, QtModelIndex) method. Each index may have a sibling(int, int, QtModelIndex) index; child items have a parent(QtModelIndex) index. Each item has data elements associated with it, and they can be retrieved by specifying a role to the model's data(QtModelIndex, int) function. If an item has child objects, hasChildren(QtModelIndex) returns true for the corresponding index. The model has a rowCount(QtModelIndex) and a columnCount(QtModelIndex) for each level of the hierarchy. Extending QtAbstractItemModel: Some general guidelines for sub-classing models are available in the model sub-classing reference. When sub-classing QtAbstractItemModel, at the very least, you must implement index(int, int, QtModelIndex), parent(QtModelIndex), rowCount(QtModelIndex), columnCount(QtModelIndex), and data(QtModelIndex, int). These abstract methods are used in all models. You can also re-implement hasChildren(QtModelIndex) to provide special behavior for models where the implementation of rowCount(QtModelIndex) is expensive. This makes it possible for models to restrict the amount of data requested by views and can be used as a way to implement the population of model data. Custom models need to create model indexes for other components to use. To do this, call createIndex(int, int, long) with suitable row and column numbers for the item, and a long type identifier for it. The combination of these values must be unique for each item. Custom models typically use these unique identifiers in other re-implemented functions to retrieve item data and access information about the item's parents and children. To create models that populate incrementally, you can re-implement fetchMore(QtModelIndex) and canFetchMore(QtModelIndex). If the re-implementation of fetchMore(QtModelIndex) adds rows to the model, beginInsertRows(QtModelIndex, int, int) and endInsertRows() must be called.
Since:
6.8

  • Constructor Details

    • QtAbstractItemModel

      public QtAbstractItemModel()
      Constructs a new QtAbstractItemModel.

  • Method Details

    • columnCount

      public abstract int columnCount(QtModelIndex parent)
      Returns the number of columns for the children of the given parent. In most subclasses, the number of columns is independent of the parent. For example: 
       @Override
 int columnCount(const QtModelIndex parent)
 {
   return 3;
 }
      When implementing a table-based model, columnCount() should return 0, when the parent is valid.
      Parameters:
      parent - The parent index.
      Returns:
      The number of columns.
      See Also:

    • data

      public abstract Object data(QtModelIndex index, int role)
      Returns the data for the given index and role. Types conversions are: Java -> QML Integer -> int String -> string Double -> double Double -> real Boolean -> bool
      Parameters:
      index - The index.
      role - The role.
      Returns:
      The data object.

    • index

      public abstract QtModelIndex index(int row, int column, QtModelIndex parent)
      Returns the index for the specified row and column for the supplied parent index. When re-implementing this function in a subclass, call createIndex() to generate model indexes that other components can use to refer to items in your model.
      Parameters:
      row - The row.
      column - The column.
      parent - The parent index.
      Returns:
      The index.
      See Also:

    • parent

      public abstract QtModelIndex parent(QtModelIndex index)
      Returns the parent of the model item with the given index. If the item has no parent, then an invalid QtModelIndex is returned. A common convention used in models that expose tree data structures is that only items in the first column have children. For that case, when re-implementing this function in a subclass, the column of the returned QtModelIndex would be 0. When re-implementing this function in a subclass, be careful to avoid calling QtModelIndex member functions, such as parent(QtModelIndex), since indexes belonging to your model will call your implementation, leading to infinite recursion.
      Parameters:
      index - The index.
      Returns:
      The parent index.
      See Also:

    • rowCount

      public abstract int rowCount(QtModelIndex parent)
      Returns the number of rows under the given parent. When the parent is valid, it means that rowCount is returning the number of children of the parent. Note: when implementing a table-based model, rowCount() should return 0, when the parent is valid.
      Parameters:
      parent - The parent index.
      Returns:
      The number of rows.
      See Also:

    • canFetchMore

      public boolean canFetchMore(QtModelIndex parent)
      Returns whether more items can be fetched for the given parent index.
      Parameters:
      parent - The parent index.
      Returns:
      True if more items can be fetched, false otherwise.

    • fetchMore

      public void fetchMore(QtModelIndex parent)
      Fetches any available data for the items with the parent specified by the parent index.
      Parameters:
      parent - The parent index.

    • hasChildren

      public boolean hasChildren(QtModelIndex parent)
      Returns true if the parent has any children; otherwise, returns false. Use rowCount() on the parent to get the number of children.
      Parameters:
      parent - The parent index.
      Returns:
      True if the parent has children, false otherwise.
      See Also:

    • hasIndex

      public boolean hasIndex(int row, int column, QtModelIndex parent)
      Returns true if the model returns a valid QModelIndex for row and column with parent, otherwise returns \c{false}.
      Parameters:
      row - The row.
      column - The column.
      parent - The parent index.
      Returns:
      True if the index exists, false otherwise.

    • roleNames

      public HashMap<Integer,String> roleNames()
      Returns a map of role names. You must override this to provide your own role names or the defaults will be used.
      Returns:
      The role names map.

    • sibling

      public QtModelIndex sibling(int row, int column, QtModelIndex parent)
      Returns the sibling at row and column for the item at index or an invalid QModelIndex if there is no sibling at that location. sibling() is just a convenience function that finds the item's parent and uses it to retrieve the index of the child item in the specified row and column. This method can optionally be overridden to optimize a specific implementation.
      Parameters:
      row - The row.
      column - The column.
      parent - The parent index.
      Returns:
      The sibling index.

    • setData

      public boolean setData(QtModelIndex index, Object value, int role)
      Sets the role data for the item at index to value. Returns true if successful; otherwise returns false. The dataChanged(QtModelIndex, QtModelIndex, int[]) method should be called if the data was successfully set. The base class implementation returns false. This method and data(QtModelIndex, int) must be reimplemented for editable models.
      Parameters:
      index - The index of the item
      value - The data value
      role - The role
      Returns:
      True if successful, otherwise return false.

    • dataChanged

      public void dataChanged(QtModelIndex topLeft, QtModelIndex bottomRight, int[] roles)
      This method must be called whenever the data in an existing item changes. If the items have the same parent, the affected ones are inclusively those between topLeft and bottomRight. If the items do not have the same parent, the behavior is undefined. When reimplementing the setData(QtModelIndex, Object, int) method, this method must be called explicitly. The roles argument specifies which data roles have actually been modified. An empty array in the roles argument means that all roles should be considered modified. The order of elements in the roles argument does not have any relevance.
      Parameters:
      topLeft - The top-left index of changed items
      bottomRight - The bottom-right index of changed items
      roles - Changed roles; Empty array indicates all roles
      See Also:

    • setOnDataChangedListener

      public void setOnDataChangedListener(QtAbstractItemModel.OnDataChangedListener listener)
      Register a callback to be invoked when the data in an existing item changes.
      Parameters:
      listener - The data change listener

    • beginInsertColumns

      protected final void beginInsertColumns(QtModelIndex parent, int first, int last)
      Begins a column insertion operation. The parent index corresponds to the parent into which the new columns are inserted; first and last are the column numbers of the new columns will have after they have been inserted.
      See Also:

    • beginInsertRows

      protected final void beginInsertRows(QtModelIndex parent, int first, int last)
      Begins a row insertion operation. Parent index corresponds to the parent into which the new rows are inserted; first and last are the row numbers the new rows will have after they have been inserted.
      See Also:

    • beginMoveColumns

      protected final boolean beginMoveColumns(QtModelIndex sourceParent, int sourceFirst, int sourceLast, QtModelIndex destinationParent, int destinationChild)
      Begins a column move operation. When re-implementing a subclass, this method simplifies moving entities in your model. This method is responsible for moving persistent indexes in the model. The sourceParent index corresponds to the parent from which the columns are moved; sourceFirst and sourceLast are the first and last column numbers of the columns to be moved. The destinationParent index corresponds to the parent into which those columns are moved. The destinationChild is the column to which the columns will be moved. That is, the index at column sourceFirst in sourceParent will become column destinationChild in destinationParent, followed by all other columns up to sourceLast. However, when moving columns down in the same parent (sourceParent and destinationParent are equal), the columns will be placed before the destinationChild index. If you wish to move columns 0 and 1 so they will become columns 1 and 2, destinationChild should be 3. In this case, the new index for the source column i (which is between sourceFirst and sourceLast) is equal to (destinationChild-sourceLast-1+i). Note that if sourceParent and destinationParent are the same, you must ensure that the destinationChild is not within the range of sourceFirst and sourceLast + 1. You must also ensure that you do not attempt to move a column to one of its own children or ancestors. This method returns false if either condition is true, in which case you should abort your move operation.
      See Also:

    • beginMoveRows

      protected final boolean beginMoveRows(QtModelIndex sourceParent, int sourceFirst, int sourceLast, QtModelIndex destinationParent, int destinationChild)
      Begins a row move operation. When re-implementing a subclass, this method simplifies moving entities in your model. The sourceParent index corresponds to the parent from which the rows are moved; sourceFirst and sourceLast are the first and last row numbers of the rows to be moved. The destinationParent index corresponds to the parent into which those rows are moved. The destinationChild is the row to which the rows will be moved. That is, the index at row sourceFirst in sourceParent will become row destinationChild in destinationParent, followed by all other rows up to sourceLast. However, when moving rows down in the same parent (sourceParent and destinationParent are equal), the rows will be placed before the destinationChild index. That is, if you wish to move rows 0 and 1 so they will become rows 1 and 2, destinationChild should be 3. In this case, the new index for the source row i (which is between sourceFirst and sourceLast) is equal to (destinationChild-sourceLast-1+i). Note that if sourceParent and destinationParent are the same, you must ensure that the destinationChild is not within the range of sourceFirst and sourceLast + 1. You must also ensure that you do not attempt to move a row to one of its own children or ancestors. This method returns false if either condition is true, in which case you should abort your move operation.
      See Also:

    • beginRemoveColumns

      protected final void beginRemoveColumns(QtModelIndex parent, int first, int last)
      Begins a column removal operation. When re-implementing removeColumns() in a subclass, you must call this function before removing data from the model's underlying data store. The parent index corresponds to the parent from which the new columns are removed; first and last are the column numbers of the first and last columns to be removed.
      See Also:

    • beginRemoveRows

      protected final void beginRemoveRows(QtModelIndex parent, int first, int last)
      Begins a row removal operation. When re-implementing removeRows() in a subclass, you must call this function before removing data from the model's underlying data store. The parent index corresponds to the parent from which the new rows are removed; first and last are the row numbers of the rows to be.
      See Also:

    • beginResetModel

      protected final void beginResetModel()
      Begins a model reset operation. A reset operation resets the model to its current state in any attached views. Note: any views attached to this model will also be reset. When a model is reset, any previous data reported from the model is now invalid and has to be queried again. This also means that the current and any selected items will become invalid. When a model radically changes its data, it can sometimes be easier to just call this function rather than emit dataChanged() to inform other components when the underlying data source, or its structure, has changed. You must call this function before resetting any internal data structures in your model.
      See Also:

    • createIndex

      protected final QtModelIndex createIndex(int row, int column, long id)
      Creates a model index for the given row and column with the internal identifier id. This function provides a consistent interface, which model sub classes must use to create model indexes.

    • endInsertColumns

      protected final void endInsertColumns()
      Ends a column insertion operation. When re-implementing insertColumns() in a subclass, you must call this function after inserting data into the model's underlying data store.
      See Also:

    • endInsertRows

      protected final void endInsertRows()
      Ends a row insertion operation. When re-implementing insertRows() in a subclass, you must call this function after inserting data into the model's underlying data store.
      See Also:

    • endMoveColumns

      protected final void endMoveColumns()
      Ends a column move operation. When implementing a subclass, you must call this function after moving data within the model's underlying data store.
      See Also:

    • endMoveRows

      protected final void endMoveRows()
      Ends a row move operation. When implementing a subclass, you must call this function after moving data within the model's underlying data store.
      See Also:

    • endRemoveColumns

      protected final void endRemoveColumns()
      Ends a column removal operation. When reimplementing removeColumns() in a subclass, you must call this function after removing data from the model's underlying data store.
      See Also:

    • endRemoveRows

      protected final void endRemoveRows()
      Ends a row move operation. When implementing a subclass, you must call this function after moving data within the model's underlying data store.
      See Also:

    • endResetModel

      protected final void endResetModel()
      Completes a model reset operation. You must call this function after resetting any internal data structure in your model.
      See Also: