From db77c5b9c74dc022fc2b37fae73ddbbe89e89c07 Mon Sep 17 00:00:00 2001 From: David Boddie Date: Fri, 9 Oct 2009 15:44:55 +0200 Subject: Doc: Replace QDirModel with QFileSystemModel in examples and overviews. Task-number: QTBUG-4152 Reviewed-by: Trust Me --- .../model-view-programming.qdoc | 51 +++++++++++---------- doc/src/images/shareddirmodel.png | Bin 33024 -> 45891 bytes doc/src/images/standard-views.png | Bin 78278 -> 44495 bytes doc/src/porting/qt4-interview.qdoc | 8 ++-- doc/src/snippets/shareddirmodel/main.cpp | 5 +- doc/src/snippets/simplemodel-use/main.cpp | 2 +- 6 files changed, 35 insertions(+), 31 deletions(-) diff --git a/doc/src/frameworks-technologies/model-view-programming.qdoc b/doc/src/frameworks-technologies/model-view-programming.qdoc index bc884df..f0f20b4 100644 --- a/doc/src/frameworks-technologies/model-view-programming.qdoc +++ b/doc/src/frameworks-technologies/model-view-programming.qdoc @@ -215,8 +215,8 @@ \o QStringListModel is used to store a simple list of QString items. \o QStandardItemModel manages more complex tree structures of items, each of which can contain arbitrary data. - \o QDirModel provides information about files and directories in the local - filing system. + \o QFileSystemModel provides information about files and directories in the + local filing system. \o QSqlQueryModel, QSqlTableModel, and QSqlRelationalTableModel are used to access databases using model/view conventions. \endlist @@ -313,14 +313,14 @@ \section1 Introduction Two of the standard models provided by Qt are QStandardItemModel and - QDirModel. QStandardItemModel is a multi-purpose model that can be used - to represent various different data structures needed by list, table, + QFileSystemModel. QStandardItemModel is a multi-purpose model that can be + used to represent various different data structures needed by list, table, and tree views. This model also holds the items of data. - QDirModel is a model that maintains information about the contents of a - directory. As a result, it does not hold any items of data itself, but + QFileSystemModel is a model that maintains information about the contents + of a directory. As a result, it does not hold any items of data itself, but simply represents files and directories on the local filing system. - QDirModel provides a ready-to-use model to experiment with, and can be + QFileSystemModel provides a ready-to-use model to experiment with, and can be easily configured to use existing data. Using this model, we can show how to set up a model for use with ready-made views, and explore how to manipulate data using model indexes. @@ -328,22 +328,25 @@ \section1 Using Views with an Existing Model The QListView and QTreeView classes are the most suitable views - to use with QDirModel. The example presented below displays the + to use with QFileSystemModel. The example presented below displays the contents of a directory in a tree view next to the same information in a list view. The views share the user's selection so that the selected items are highlighted in both views. \img shareddirmodel.png - We set up a QDirModel so that it is ready for use, and create some + We set up a QFileSystemModel so that it is ready for use, and create some views to display the contents of a directory. This shows the simplest way to use a model. The construction and use of the model is performed from within a single \c main() function: \snippet doc/src/snippets/shareddirmodel/main.cpp 0 - The model is set up to use data from a default directory. We create two - views so that we can examine the items held in the model in two + The model is set up to use data from a certain file system. The call to + \l{QFileSystemModel::}{setRootPath()} tell the model which drive on the + file system to expose to the views. + + We create two views so that we can examine the items held in the model in two different ways: \snippet doc/src/snippets/shareddirmodel/main.cpp 5 @@ -351,13 +354,13 @@ The views are constructed in the same way as other widgets. Setting up a view to display the items in the model is simply a matter of calling its \l{QAbstractItemView::setModel()}{setModel()} function with the directory - model as the argument. The calls to - \l{QAbstractItemView::setRootIndex()}{setRootIndex()} tell the views which - directory to display by supplying a \e{model index} that we obtain from - the directory model. + model as the argument. We filter the data supplied by the model by calling + the \l{QAbstractItemView::}{setRootIndex()} function on each view, passing + a suitable \e{model index} from the file system model for the current + directory. - The \c index() function used in this case is unique to QDirModel; we supply - it with a directory and it returns a model index. Model indexes are + The \c index() function used in this case is unique to QFileSystemModel; we + supply it with a directory and it returns a model index. Model indexes are discussed in the \l{Model Classes} chapter. The rest of the function just displays the views within a splitter @@ -556,19 +559,19 @@ \section2 Using Model Indexes To demonstrate how data can be retrieved from a model, using model - indexes, we set up a QDirModel without a view and display the + indexes, we set up a QFileSystemModel 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. - We construct a directory model in the following way: + We construct a file system model in the following way: \snippet doc/src/snippets/simplemodel-use/main.cpp 0 - In this case, we set up a default QDirModel, obtain a parent index using - a specific implementation of \l{QDirModel::index()}{index()} provided by - that model, and we count the number of rows in the model using the - \l{QDirModel::rowCount()}{rowCount()} function. + In this case, we set up a default QFileSystemModel, obtain a parent index + using a specific implementation of \l{QFileSystemModel::}{index()} + provided by that model, and we count the number of rows in the model using + the \l{QFileSystemModel::}{rowCount()} function. 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 @@ -581,7 +584,7 @@ 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 - \l{QDirModel::data()}{data()} function. We specify the model index and + \l{QFileSystemModel::}{data()} function. We specify the model index and the \l{Qt::ItemDataRole}{DisplayRole} to obtain data for the item in the form of a string. diff --git a/doc/src/images/shareddirmodel.png b/doc/src/images/shareddirmodel.png index 6daa9d3..7b9fded 100644 Binary files a/doc/src/images/shareddirmodel.png and b/doc/src/images/shareddirmodel.png differ diff --git a/doc/src/images/standard-views.png b/doc/src/images/standard-views.png index 836ae36..c804551 100644 Binary files a/doc/src/images/standard-views.png and b/doc/src/images/standard-views.png differ diff --git a/doc/src/porting/qt4-interview.qdoc b/doc/src/porting/qt4-interview.qdoc index 29d9f5c..fd3fb36 100644 --- a/doc/src/porting/qt4-interview.qdoc +++ b/doc/src/porting/qt4-interview.qdoc @@ -109,8 +109,8 @@ \list \o QStandardItemModel is a minimal convenience model that developers can use to manage items of data. - \o QDirModel provides directory information for use with QListView and - QTreeView. + \o QFileSystemModel provides directory information for use with QListView + and QTreeView. \o QStringListModel is a convenience model that can be used to hold strings for views such as QListView and QComboBox. \endlist @@ -153,7 +153,7 @@ In this example, we display the contents of a model using two different views, and share the user's selection between - them. We will use the QDirModel supplied with Qt because it + them. We will use the QFileSystemModel supplied with Qt because it requires very little configuration, and provides existing data to the views. @@ -174,7 +174,7 @@ \image interview-shareddirmodel.png - The model/view architecture allows us to replace the QDirModel in + The model/view architecture allows us to replace the QFileSystemModel in this example with a completely different model, one that will perhaps obtain data from a remote server, or from a database. diff --git a/doc/src/snippets/shareddirmodel/main.cpp b/doc/src/snippets/shareddirmodel/main.cpp index 82034b5..3cb63c9 100644 --- a/doc/src/snippets/shareddirmodel/main.cpp +++ b/doc/src/snippets/shareddirmodel/main.cpp @@ -55,7 +55,8 @@ int main(int argc, char *argv[]) QSplitter *splitter = new QSplitter; //! [2] //! [3] - QDirModel *model = new QDirModel; + QFileSystemModel *model = new QFileSystemModel; + model->setRootPath(QDir::currentPath()); //! [0] //! [2] //! [4] //! [5] QTreeView *tree = new QTreeView(splitter); //! [3] //! [6] @@ -74,7 +75,7 @@ int main(int argc, char *argv[]) list->setSelectionModel(selection); //! [8] - splitter->setWindowTitle("Two views onto the same directory model"); + splitter->setWindowTitle("Two views onto the same file system model"); splitter->show(); return app.exec(); } diff --git a/doc/src/snippets/simplemodel-use/main.cpp b/doc/src/snippets/simplemodel-use/main.cpp index a3bb0e7..d7fc755 100644 --- a/doc/src/snippets/simplemodel-use/main.cpp +++ b/doc/src/snippets/simplemodel-use/main.cpp @@ -69,7 +69,7 @@ int main(int argc, char *argv[]) layout->addWidget(title); //! [0] - QDirModel *model = new QDirModel; + QFileSystemModel *model = new QFileSystemModel; QModelIndex parentIndex = model->index(QDir::currentPath()); int numRows = model->rowCount(parentIndex); //! [0] -- cgit v0.12