~oif-team/ubuntu/natty/qt4-x11/xi2.1

<td width="1">  </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a> · <a href="classes.html"><font color="#004faf">All Classes</font></a> · <a href="mainclasses.html"><font color="#004faf">Main Classes</font></a> · <a href="annotated.html"><font color="#004faf">Annotated</font></a> · <a href="groups.html"><font color="#004faf">Grouped Classes</font></a> · <a href="functions.html"><font color="#004faf">Functions</font></a></td>

[Previous: <a href="model-view-using.html">Using Models and Views</a>]

[<a href="model-view-programming.html">Contents</a>]

[Next: <a href="model-view-creating-models.html">Creating New Models</a>]

</p>

<h1 align="center">Model Classes</h1>

<ul><li><a href="#basic-concepts">Basic Concepts</a></li>

<ul><li><a href="#model-indexes">Model Indexes</a></li>

<li><a href="#rows-and-columns">Rows and Columns</a></li>

<li><a href="#parents-of-items">Parents of Items</a></li>

<li><a href="#item-roles">Item Roles</a></li>

<li><a href="#summary-of-concepts">Summary of Concepts</a></li>

<li><a href="#using-model-indexes">Using Model Indexes</a></li>

</ul>

<li><a href="#further-reading">Further Reading</a></li>

</ul>

<h2>Basic Concepts</h2>

<p>In the model/view architecture, the model provides a standard interface that views and delegates use to access data. In Qt, the standard interface is defined by the <a href="qabstractitemmodel.html">QAbstractItemModel</a> class. No matter how the items of data are stored in any underlying data structure, all subclasses of <a href="qabstractitemmodel.html">QAbstractItemModel</a> represent the data as a hierarchical structure containing tables of items. Views use this <i>convention</i> to access items of data in the model, but they are not restricted in the way that they present this information to the user.</p>

<center><img src="images/modelview-models.png" /></center><p>Models also notify any attached views about changes to data through the signals and slots mechanism.</p>

<p>This chapter describes some basic concepts that are central to the way item of data are accessed by other components via a model class. More advanced concepts are discussed in later chapters.</p>

<h3>Model Indexes</h3>

<p>To ensure that the representation of the data is kept separate from the way it is accessed, the concept of a <i>model index</i> is introduced. Each piece of information that can be obtained via a model is represented by a model index. Views and delegates use these indexes to request items of data to display.</p>

<p>As a result, only the model needs to know how to obtain data, and the type of data managed by the model can be defined fairly generally. Model indexes contain a pointer to the model that created them, and this prevents confusion when working with more than one model.</p>

<pre>  QAbstractItemModel *model = index.model();</pre>

<p>Model indexes provide <i>temporary</i> references to pieces of information, and can be used to retrieve or modify data via the model. Since models may reorganize their internal structures from time to time, model indexes may become invalid, and <i>should not be stored</i>. If a long-term reference to a piece of information is required, a <i>persistent model index</i> must be created. This provides a reference to the information that the model keeps up-to-date. Temporary model indexes are provided by the <a href="qmodelindex.html">QModelIndex</a> class, and persistent model indexes are provided by the <a href="qpersistentmodelindex.html">QPersistentModelIndex</a> class.</p>

<p>To obtain a model index that corresponds to an item of data, three properties must be specified to the model: a row number, a column number, and the model index of a parent item. The following sections describe and explain these properties in detail.</p>

<h3>Rows and Columns</h3>

<p>In its most basic form, a model can be accessed as a simple table in which items are located by their row and column numbers. <i>This does not mean that the underlying pieces of data are stored in an array structure</i>; the use of row and column numbers is only a convention to allow components to communicate with each other. We can retrieve information about any given item by specifying its row and column numbers to the model, and we receive an index that represents the item:</p>

<pre>  QModelIndex index = model->index(row, column, ...);</pre>

<p>Models that provide interfaces to simple, single level data structures like lists and tables do not need any other information to be provided but, as the above code indicates, we need to supply more information when obtaining a model index.</p>

<tr valign="top" bgcolor="#f0f0f0"><td><img src="images/modelview-tablemodel.png" /></td><td><b>Rows and columns</b><p>The diagram shows a representation of a basic table model in which each item is located by a pair of row and column numbers. By passing the relevant row and column numbers to the model we obtain a model index that refers to an item of data.</p>

<pre>  QModelIndex indexA = model->index(0, 0, QModelIndex());

QModelIndex indexB = model->index(1, 1, QModelIndex());

QModelIndex indexC = model->index(2, 1, QModelIndex());</pre>

<p>Top level items in a model are always referenced by specifying <tt>QModelIndex()</tt> as their parent item. This is discussed in the next section.</p>

</td></tr>

</table>

<h3>Parents of Items</h3>

<p>The table-like interface to item data provided by models is ideal when using data in a table or list view; the row and column number system maps exactly to the way the views display items. However, structures such as tree views require the model to expose a more flexible interface to the items within. As a result, each item can also be the parent of another table of items, in much the same way that a top-level item in a tree view can contain another list of items.</p>

<p>When requesting an index for a model item, we must provide some information about the item's parent. Outside the model, the only way to refer to an item is through a model index, so a parent model index must also be given:</p>

<pre>  QModelIndex index = model->index(row, column, parent);</pre>

<tr valign="top" bgcolor="#f0f0f0"><td><img src="images/modelview-treemodel.png" /></td><td><b>Parents, rows, and columns</b><p>The diagram shows a representation of a tree model in which each item is referred to by a parent, a row number, and a column number.</p>

<p>Items "A" and "C" are represented as top-level siblings in the model:</p>

<pre>  QModelIndex indexA = model->index(0, 0, QModelIndex());

QModelIndex indexC = model->index(2, 1, QModelIndex());</pre>

<p>Item "A" has a number of children. A model index for item "B" is obtained with the following code:</p>

<pre>  QModelIndex indexB = model->index(1, 0, indexA);</pre>

</td></tr>

</table>

<h3>Item Roles</h3>

<p>Items in a model can perform various <i>roles</i> for other components, allowing different kinds of data to be supplied for different situations. For example, the <a href="qt.html#ItemDataRole-enum">DisplayRole</a> role is used to access a string that can be displayed as text in a view. Typically, items contain data for a number of different roles.</p>

<p>We can ask the model for the item's data by passing it the model index corresponding to the item, and by specifying a role to obtain the type of data we want:</p>

<pre>  QVariant value = model->data(index, role);</pre>

<tr valign="top" bgcolor="#f0f0f0"><td><img src="images/modelview-roles.png" /></td><td><b>Item roles</b><p>The role indicates to the model which type of data is being referred to. Views can display the roles in different ways, so it is important to supply appropriate information for each role.</p>

<p>We will examine roles in more detail when we <a href="model-view-creating-models.html">create an example model</a>.</p>

</td></tr>

</table>

<p>Many of the most common uses for items of data are represented by standard roles. However, it is also possible to define additional roles for your own purposes.</p>

<h3>Summary of Concepts</h3>

<ul>

<li>Model indexes give views and delegates information about the location of items provided by models in a way that is independent of any underlying data structures.</li>

<li>Items are referred to by their row and column numbers, and by the model index of their parent items.</li>

<li>Model indexes are constructed by models at the request of other components, such as views and delegates.</li>

<li>If a valid model index is specified when an index is requested (using <a href="qabstractitemmodel.html#index">index()</a>, the model understands that it refers to a parent item, and that it must return an index that refers to a child of that item.</li>

<li>If an invalid model index is specified when an index is requested (using <a href="qabstractitemmodel.html#index">index()</a>, the model understands that it must return a model index that refers to a top-level item in the model.</li>

<li>The <a href="qt.html#ItemDataRole-enum">role</a> distinguishes between the different kinds of data associated with an item.</li>

</ul>

100

<h3>Using Model Indexes</h3>

101

<p>To demonstrate how data can be retrieved from a model, using model indexes, we set up a <a href="qdirmodel.html">QDirModel</a> without a view and display the names of files and directories in a widget. Although this does not show a normal way of using a model, it demonstrates the conventions used by models when dealing with model indexes.</p>

102

<p>We construct a directory model in the following way:</p>

103

<pre>  QDirModel *model = new QDirModel;

104

QModelIndex parentIndex = model->index(QDir::currentPath());

105

int numRows = model->rowCount(parentIndex);</pre>

106

<p>In this case, we set up a default <a href="qdirmodel.html">QDirModel</a>, obtain a parent index using a specific implementation of <a href="qdirmodel.html#index">index()</a> provided by that model, and we count the number of rows in the model using the <a href="qdirmodel.html#rowCount">rowCount()</a> function.</p>

107

<p>For simplicity, we are only interested in the items in the first column of the model. We examine each row in turn, obtaining a model index for the first item in each row, and read the data stored for that item in the model.</p>

108

<pre>  for (int row = 0; row < numRows; ++row) {

109

QModelIndex index = model->index(row, 0, parentIndex);</pre>

110

<p>To obtain a model index, we specify the row number, column number (zero for the first column), and the appropriate model index for the parent of all the items that we want. The text stored in each item is retrieved using the model's <a href="qdirmodel.html#data">data()</a> function. We specify the model index and the <a href="qt.html#ItemDataRole-enum">DisplayRole</a> to obtain data for the item in the form of a string.</p>

111

<pre>  QString text = model->data(index, Qt::DisplayRole).toString();

112

// Display the text in a widget.

113

114

}</pre>

115

<p>The above example demonstrates the basic principles used to retrieve data from a model:</p>

116

<ul>

117

<li>The dimensions of a model can be found using <a href="qabstractitemmodel.html#rowCount">rowCount()</a> and <a href="qabstractitemmodel.html#columnCount">columnCount()</a>. These functions generally require a parent model index to be specified.</li>

118

<li>Model indexes are used to access items in the model. The row, column, and parent model index are needed to specify the item.</li>

119

<li>To access top-level items in a model, specify a null model index as the parent index with <tt>QModelIndex()</tt>.</li>

120

<li>Items contain data for different roles. To obtain the data for a particular role, both the model index and the role must be supplied to the model.</li>

121

</ul>

122

123

<h2>Further Reading</h2>

124

<p>New models can be created by implementing the standard interface provided by <a href="qabstractitemmodel.html">QAbstractItemModel</a>. In the <a href="model-view-creating-models.html">next chapter</a>, we will demonstrate this by creating a convenient ready-to-use model for holding lists of strings.</p>

125

<p>

126

[Previous: <a href="model-view-using.html">Using Models and Views</a>]

127

[<a href="model-view-programming.html">Contents</a>]

128

[Next: <a href="model-view-creating-models.html">Creating New Models</a>]

129

</p>

130

131

132

133

<td width="40%" align="center"><a href="trademarks.html">Trademarks</a></td>

134

135

</tr></table></div></address></body>

136

</html>

Older »