Signals and slots permit objects to communicate through a run-time conduit based on C++ method dispatch (ensuring that it's fast) while permitting the developer to provide the method without needing to subclass or implement an interface (so it's flexible). It's similar in principle to the callback technique used in C and C++, although considerably more flexible.

Any QObject descendant can emit a signal to indicate the occurrence of an event, such as a button being pressed, the movement of a slider, the completion of an HTTP transaction, or other events. Qt permits you to declare what signals a given object can emit, and lets you declare slots in QObject descendants that you can connect to appropriate signals.

Signals and slots are type-safe, helping reduce potential programming errors. The coupling between signals and slots is loose, so that an object is free to emit signals as its state changes, even if no slots are connected to those signals. In the same way, slots need not be connected; they're just method declarations with a bit of extra glue in the class definition to indicate that you may be using the method as a slot, but you can still call them from your source code like any other method.

At runtime, you connect a signal to a slot using QObject's connect method, and disconnect using QObject's disconnect method. These connections are one-way, indicating that a signal should trigger a slot; the mechanism may be one-to-many, in which a single signal is connected to a number of slots, each through an invocation of QObject's connect method. We show you a concrete example of how to do this later in the chapter in the section titled "Using Signals and Slots."

C++, like C before it, relies on you, the developer, to keep track of when your application allocates memory and when it should release it for reuse. In small applications this isn't difficult, but as your application grows in complexity, it gets more difficult. Errors where you allocate memory and don't free it cause memory leaks; on constrained devices such as mobile phones, that can mean the difference between running and crashing as your application runs out of memory. Worse, large programs can see more insidious problems, such as using a region of memory after you've released it to the memory manager, which can cause crashes and other aberrant behavior in your application.

To help your application track when it needs to free allocated memory, Qt provides a hierarchy of memory ownership with most of its classes. When you create an object instance, you can designate another QObject as the owner (called the parent) of the object you're about to create. In turn, when the parent is released, any objects owned by the parent are also released. For example, to create a button to be released when the allocating object is deleted, we'd write:

QPushButton* button = new QPushButton(this);

In practice, it's generally best to use parented objects like this, rather than keeping a bunch of pointers and releasing them in the parent object's destructor.

As in other frameworks, it's common to use a null pointer (with the value 0) to indicate an object that has already been freed. To automate the process of setting a pointer to null when the pointer's memory is released, you can use the QPointer template, like this:

QPointer<QPushButton> button = new QPushButton(this);

For memory allocated in a function's scope, Qt provides the QScopedPointer, which automatically deletes the memory associated with the pointer when the scope ends, like this:

{
    QScopedPointer<QXmlStreamReader> xmlReader = new QXmlStreamReader();
    // ...parse the xml here...
} // xmlReader is deleted by the QScopedPointer

QScopedPointers are handy to have around in large functions with multiple exit points, where it's likely you'll forget to free an object. They're especially useful in doing device programming, where it's best to make light use of stack allocation, because the stack size on mobile devices is much smaller than what you're used to on desktop or server platforms.

As we've already said, Qt object instances are just C++ instances with a bit of extra magic glue provided by Qt for things including the signal/slot mechanism and managing the memory used by parented objects. Another feature of Qt's objects that descend from QObject are properties, name-value pairs for attributes of the objects you define. As with other extensions to C++ that Qt provides, you can define properties in any class that inherits from QObject. Properties are especially important for things like integration with Qt Quick (see Chapter 7) and JavaScript in WebKit (see Chapter 8). To declare a property in an object, use the Q_PROPERTY macro inside the class definition, like this:

Q_PROPERTY(bool focus
           READ hasFocus)
Q_PROPERTY(bool enabled
           READ isEnabled
           WRITE setEnabled)

After specifying the property's type and name you can specify additional information in the form of functions that perform a specific action. All properties must have a READ directive that indicates the function the Qt meta-object system must invoke to obtain the value of the property. It's important to remember that you provide that function; all the Q_PROPERTY does is set things up with the meta-object system, rather than actually implementing functions like setters and getters.

In addition to READ, you can also provide several other directives defining the property, including:

In practice, when implementing your class, you generally specify the READ and WRITE values; occasionally you may come across a property that includes a RESET value.

You are doubtless already aware of C++'s dynamic_cast, which lets you safely downcast or crosscast a pointer (returning 0 if the cast fails because of a type mismatch). Typically, you can't perform a dynamic cast across a plug-in boundary. Because Qt provides a cross-platform mechanism for managing plug-ins (in fact, Qt's support for different image types uses plug-ins to encapsulate the image format decoders), Qt needs a type-safe way to crosscast and downcast across dynamic library boundaries. To do this, Qt provides qobject_cast, a cast operation that's essentially the same in principle to dynamic_cast. In general when looking at Qt C++ code, you will likely see more use of qobject_cast than dynamic_cast, and it's generally a good idea to prefer it to dynamic_cast as well in your code. Another benefit to using qobject_cast is performance, as it uses the meta-object system rather than the C++ run time type inference.

Most applications—even many that have a minimal GUI—require resources as well as code. Images, sounds, and text—whether programmatic text, such as JavaScript to be used with the QtWebKit port or the text in the interface for windows, buttons, and so forth—must be packaged together with your application. Rather than taking the approach of providing a resource bundle with your executable, Qt takes the approach of statically compiling any resources into your executable. That way, you don't have multiple files to carry around with most applications, nor do you need to depend on a platform-specific mechanism, such as an application bundle.

You begin the process by specifying the resources your application requires in a resource collection file. The resource collection file is just a text file containing XML that describes the name and path to each required resource, like this:

<!DOCTYPE RCC>
    <RCC version="1.0">
    <qresource>
        <file>images/happy.png</file>
        <file>images/sad.png</file
    </qresource>
</RCC>

These files should already reside in your source tree (keeping them in your change control system isn't a bad idea, unless you're using one that doesn't handle binary files well), and the paths you provide to each <file> item are the paths relative to the resource collection definition file, as well as the paths to the resource when you load the resource in your application. You can name the resource file anything you like, as long as the filename ends with ".qrc."

To include the resource file in your application, just add a RESOURCES line to your project file indicating the resource file's location, like this:

RESOURCES += resources.qrc

To use a resource in your application, simply precede the location of the resource with a single colon and a solidus (":/"), like this:

QImage image(":/images/happy.png");

(We go into using Qt resources in more detail in the next chapter, in the section "Using Application Resources.")

Small text resources, like those for labels, application error messages, and so forth, are best carried separately in a translation file created using Qt Linguist and the localization utilities lupdate and lrelease provided by Qt. You begin by ensuring that every string that needs a translation is marked using the function tr, provided by QObject. For example, when creating a button with the label "OK", we might write:

QPointer<QPushButton> button(tr("OK"), this);

The tr function is what will load the appropriate locale-specific string at run time; if a string is unavailable, it will default to the text you invoke it with.

Obviously, the thing you don't want to do is pick through thousands of lines of source code looking for tr invocations, so Qt provides lupdate, a utility to do just that. You must specify only the translation files to create in your project file and run Qt's lupdate command on your project file to create translation files (their names will end in .ts) containing every localizable string in your sources, headers, and Qt Designer files. Thus, the resource and localization parts of my project file might read:

RESOURCES = resources.qrc
TRANSLATIONS = myapp_dk.ts 
               myapp_en.ts 
               myapp_fi.ts

(The translation files include the source language name using the ISO-639-1 defined two-character code for the language.)

Once you create the initial translation files, your translator can use Qt Linguist to add the translated resources. Once that's done, you run lrelease over your project to compile the resulting release files. The resulting files are highly compressed and optimized for rapid access.

Occasionally, you might want to localize other resources, too—say, adding a localized version of a specific icon within your application. You do this using the XML in the resource collection file, by specifying the lang attribute of a specific qresource tag, like this:

<qresource lang="en">
    <file alias="images/flag.png">images/flag_en.png</file>
</qresource>
<qresource lang="fi">
    <file alias="images/flag.png">images/flag_fi.png</file
</qresource>

Like the C++ Standard Template Library (STL), Qt provides a number of type-safe collections through classes. These include sequenced collections through the use of the templates QList, QLinkedList, QVector, QStack, and QQueue, as well as associative containers through the use of QMap and QMultiMap, as well as QHash and QMultiHash. Finally, there is also QPair, which you can use to contain pairs of objects of arbitrary types.

For most applications needing to keep a list of items, QList is the logical choice. It's optimized for fast access, with only moderate penalties for insertion and deletion. If you find you need better performance for an updating list, try QLinkedList, which trades accessibility for performance when inserting or removing items. On the other hand, if QList doesn't meet your needs for access performance, there's also QVector, which stores its items in a contiguous region in memory, providing the fastest access but with considerable cost when inserting or removing items in the middle of the vector. QStack and QQueue provide convenience methods for implementing a stack using QVector and a first-in-first-out (FIFO) store using QList.

Associative maps let you store key-value pairs. Usually, you do this using a hash table; QHash and QMultiHash provide classic hash tables with arbitrary types for keys and values. You can also do the same thing with a binary search across a sorted set using QMap and QMultiMap. The "Multi" in QMultiHash and QMultiMap indicate that these templates can store multiple values for a single key, giving you additional flexibility.

These collections let you access items individually (using a method such as at or value) and iterate across the entire contents of the collection. These collections provide both STL-style iterators and a simpler Qt iterator to permit you to traverse the collection, visiting each item. The example at the end of the chapter shows you how to enumerate through the values in a QMap.

It's worth observing that the QString class, intended to represent strings of characters, isn't actually a collection class, but provides similar methods for inserting and removing characters from a string. The QString class also provides the usual methods you'd expect of a container of characters, including methods to format non-string values such as integers or floats, compare two strings, find and replace contents of a string, and so forth.

Qt provides a class hierarchy for models that are a little different than what you may have encountered on other platforms. While you can use a model with a single flat collection of objects such as a list, the Qt platform itself provides for a tree of two-dimensional tables such as the one you see in Figure 4-2. In the figure, we see a tree with a root that is a 4×4 table of items; the items at (0, 0) and (1, 3) each have child data, and so forth. While dizzying, this general representation provides the ability for a model to represent items in one dimension (lists), two dimensions (tables), and a hierarchy (such as a directory tree).

Figure 4.2. An arbitrary model represented using Qt's abstract model structure

Qt uses the QAbstractItemModel to encapsulate the full flexibility of a tree of tables; normally, a QAbstractListModel or QAbstractTableModel suffices, hiding the complexity of the tree unless you really need it.

In most cases, you don't even need to create your own model; instead you can use a QStringListModel for a one-dimensional list of QStrings, or a QStandardItemModel for one- or two-dimensional array, as well as data structured in a hierarchy.

The two-dimensional nature of the QTableModel is strongly reminiscent of a SQL database's tables, and it almost immediately comes to mind when you have data organized in rows with different facets of the data in each column. It shouldn't, however—in a Qt table model, each cell in the table is independent of every other cell. Think of a Qt table like a financial spreadsheet (not a well-formatted list!). Instead, if you have a list of items with different data per item—say, a list of location names with latitudes and longitudes—each location is a single item in a list.

To provide access to different facets of a single item, Qt provides roles. A role is a constant in an enumeration, and models return different data depending on the role you pass when you interrogate the model. Qt defines several roles by default defined by the Qt::ItemDataRole enumeration, including:

So, for example, the QListView uses the Qt::DisplayRole to indicate to the model what data is requested for display for each item. You can define your own roles, too, if you need to represent different kinds of data and find the Qt roles limiting in the kind of data being represented; just be sure that your first role has a value greater than Qt::UserRole.

When you set or get data from a model, you do so using a QModelIndex that indicates which datum you're interacting with as well as Qt's QVariant class. The QVariant class is a type-safe wrapper for most C++ and all Qt value types, including integers, floating-point numbers, and strings. You access the model's data through the data and setData methods; they use QVariant for encapsulating the actual values.

For example, here's how to access the first datum in a QStringListModel:

QStringListModel model;
...
QModelIndex index = model->createIndex(0);
QString datum = model->data(index, Qt::DisplayRole).toString();

Setting the data is similar:

QStringListModel model;
...
QModelIndex index = model->createIndex(0);
QString anEntry("hello world");
QString datum = model->setData(index,
    QVariant(anEntry),
    Qt::DisplayRole);

In addition to being able to set a datum within the model, you can manipulate the model in various ways. The most common things you're likely to want to use are:

As you manipulate a model with these methods, it emits signals so that the view or other code can be kept abreast of any changes within the model. Typically, when using a model, you don't need to worry about these signals, unless you're implementing your own model.

You needn't implement your own model most of the time. Qt also provides the QStandardItemModel, which provides a concrete implementation of a model you can use within your application for normal purposes. (We show you how to use the QStandardItemModel later in this chapter, in the section "Putting it All Together.")

Qt's view classes provide robust components that rely on a model for their data. QListView, QTableView, and QTreeView provide the fundamental UI classes many applications can use to provide a browsing metaphor for their data. These implement the abstract class QAbstractItemView, which defines the various methods, signals, and slots exposed by all view classes.

In general, you need to know very little about how a Qt view class works; it often suffices to drag one out in the GUI designer (or create one at run time, as you see later in this chapter in the section "Putting it All Together") and set its model, like this:

// In a class declaration inheriting from QMainWindow
QStandardItemModel *mModel;
QListView *mListView;
// Someplace in the GUI code
mListView = new QListView(this);
mStandardItemModel mModel = new QStandardItemModel(this);
mListView->setModel(mModel);
setCentralWidget(mListView);

Qt's design style calls for generally shallow class hierarchies, with a great deal of configurability being embedded in specific implementation classes, rather than dozens of classes providing slightly different behaviors. Thus, the QAbstractItemView has a number of properties affecting how an instance renders data, including:

Unlike the classic implementation of model-view-controller, where the controller is a separate class with its own (usually application-specific) logic, Qt divides the responsibilities of the controller between the view and the application. The view handles the view-specific events, such as responding to events that would cause scrolling or item selection, and issues signals for user interaction that requires application logic, such as item activation and selection. These signals include:

In the next section, you see how wiring a signal from the QListView triggers an action when the user touches an item in the list.

The user interface for our application is admittedly simple, providing a single list of recent seismic events and a region showing the details of the event you select. The class MainForm, which extends QMainWindow supports the user interface. Listing 4-4 shows the MainForm class.

class MainForm : public QMainWindow
{
    Q_OBJECT

public:
    MainForm(QWidget *parent = 0);
    ~MainForm();

public slots:
    void fetch();

private slots:
    void handleRequestFinished();
    void handleError(const QString& message);
    void handleItemClicked(const QModelIndex&);

private:
    WorkerThread* mBgThread;
    QuakeListModel* mEventModel;
    QSortFilterProxyModel* mSortedModel;
    QListView* mListView;
    QWebView* mItemView;
    QWidget* mMainView;
};

The UI itself uses a QListView to show the list of events, and a QWebView to show the results. (We talk more about the QWebView class in the next chapter.) The earthquake data is kept in the QuakeListModel, a simple subclass of QStandardItemModel that has a single helper method to permit easy storage of seismic data through a container class. In turn, the list view obtains the data through a QSortFilterProxyModel, which provides the data sorted so that the resulting list has the most recent item first. All of this is initialized in MainForm's constructor (shown in Listing 4-5).

MainForm::MainForm(QWidget *parent)
    : QMainWindow(parent)
    , mBgThread(0)
    , mEventModel(new QuakeListModel())
    , mSortedModel(new QSortFilterProxyModel(this))
    , mListView(new QListView(this))
    , mItemView(new QWebView(this))
    , mMainView(new QWidget(this))
{
    mItemView->setHtml(tr("<body><p align="center">"
        "Loading data... please wait</p></body>"));

    mSortedModel->setSourceModel(mEventModel);
    mSortedModel->setDynamicSortFilter(false);
    mSortedModel->setSortRole(QuakeListModel::When);
    mListView->setModel(mSortedModel);

    mListView->setSizePolicy(QSizePolicy::Expanding,
        QSizePolicy::Expanding);
    mItemView->setSizePolicy(QSizePolicy::Expanding,
        QSizePolicy::Expanding);

    mListView->setHorizontalScrollBarPolicy(Qt::ScrollBarAlwaysOff);

    QBoxLayout::Direction direction;
    if (height()>=width()) {
        direction = QBoxLayout::LeftToRight;
    } else {
        direction = QBoxLayout::TopToBottom;
    }
    QBoxLayout *layout = new QBoxLayout(direction, mMainView);

    layout->addWidget(mListView, 1);

layout->addWidget(mItemView, 1);
    mMainView->setLayout(layout);

    setCentralWidget(mMainView);

    connect(mListView, SIGNAL(clicked(QModelIndex)),
            this, SLOT(handleItemClicked(QModelIndex)));

    fetch();
}

As you see immediately, we chose to manually create the UI, rather than use Qt Creator within the Nokia Qt SDK. The reason is only to show you that you can; you could easily use the user interface you created from Chapter 4 with Qt Creator. Regardless, the code creates the two visible elements and combines them in a single widget, set to be the main widget of the QMainWindow using QMainWindow's setCentralWidget method.

Perhaps the most interesting code in the constructor is the lines that link the QuakeModel instance with the QSortFilterProxyModel instance. As the name suggests, the QSortFilterProxyModel is a model in the object-oriented sense (it inherits from QAbstractItemModel), but doesn't contain any data. Instead, it provides a view with an ordered or filtered model (hence the "proxy" in its name) created using an indicated role. Here, the code:

In turn, the QListView accesses the data through the proxy model; behind the scenes the proxy model does some magic with its model indexes so that the model data appears to be sorted by time.

Once the user interface component and model is initialized, the constructor invokes fetch to obtain the latest seismic data.

It's worth mentioning that in the user interface, our error handling is admittedly primitive, but demonstrates that something needs to be done in the event of an error. In our case, we simply emit an error message, which the UI will present in a dialog indicating the nature of the error (Listing 4-6).

void MainForm::handleError(const QString& message)
{
    QMessageBox box(QMessageBox::Critical,
                    tr("Error"),
                    message,
                    QMessageBox::Ok,
                    this);
    qDebug() << message;
}

Listing 4-7 shows the fetch method, responsible for starting the thread to fetch the data.

void MainForm::fetch()
{
    if (!mBgThread)
        mBgThread = new WorkerThread(this, *mEventModel);
    connect(mBgThread, SIGNAL(finished()),
            this, SLOT(handleRequestFinished()));
    connect(mBgThread, SIGNAL(error(const QString&)),
            this, SLOT(handleError(const QString&)));
    mBgThread->fetch(
      "http://earthquake.usgs.gov/earthquakes/catalogs/1day-M2.5.xml"
    );
}

This code is quite simple. In addition to creating an instance of our worker thread, the code connects its signals to slots in the main view so that the main view can respond to success or failure in the attempt to obtain data from the network.

The thread itself is responsible for making the HTTP request and parsing the XML results. Construction of the thread (see Listing 4-8) initializes a hash with the XML tags we seek, and does the necessary connecting between signals and slots.

WorkerThread::WorkerThread(QObject* owner,
                           QuakeListModel& eventModel)
    : QThread(owner)
    , mCancelled(false)
    , mNetManager(0)
    , mReply(0)
    , mEventModel(eventModel)
{
    // Initialize the hashtable of tags we seek
    mXmlTags.append("id");
    mXmlTags.append("title");
    mXmlTags.append("updated");
    mXmlTags.append("summary");
    mXmlTags.append("point");
    mXmlTags.append("elev");
    mXmlTags.append("link");

    mNetManager = new QNetworkAccessManager(this);
    connect(mNetManager, SIGNAL(finished(QNetworkReply*)),
            this, SLOT(handleNetFinished(QNetworkReply*)));
}

Performing the HTTP request, done in the fetch method with the URL you pass it, is very easy. Listing 4-9 shows how it's done.

void WorkerThread::fetch(const QString& url)
{
    QNetworkReply *reply = mNetManager->get(QNetworkRequest(QUrl(url)));
    if (!reply) {
        emit error(tr("Could not contact the server"));
    }
}

It's worth noting that the QNetworkAccessManager's get method does not block; control returns to the main thread, and the manager performs the network request asynchronously. In fact, the real reason to encapsulate this part of the application in its own thread is the XML parsing, which can take a bit of time in a large document. When the network operation completes, the manager will emit the finished signal, which we handle in handleNetFinished (Listing 4-10).

void WorkerThread::handleNetFinished(QNetworkReply* reply)
{
    // Start parser by starting.
    if (reply->error() == QNetworkReply::NoError) {
        if (!this->isRunning()) {
            mReply = reply;
            start();
        }
    } else {
        emit error(tr("A network error occurred"));
        qDebug() << QString("net error %1").arg(reply->error());
    }
}

The USGS data provides its data in well-formed XML. A specific seismic event might look like this:

<entry>
    <id>urn:earthquake-usgs-gov:ci:10756957</id>
    <title>M 3.8, Baja California, Mexico</title>
    <updated>2010-07-19T23:06:11Z</updated>
    <link rel="alternate" type="text/html" href="url"/>
    <link rel="related" type="application/cap+xml" href="url" />
    <summary type="html">
        <![CDATA
            html description of event
      ]]></summary>
    <georss:point>32.1465 −115.1627</georss:point>
    <georss:elev>-6300</georss:elev>
    <category label="Age" term="Past hour"/>
</entry>

This is contained within a root-level <feed> block. (For brevity, we've elided the actual URLs and HTML content describing the event.) The only catch in working with the data is that the <id> attribute uniquely identifies an event, but multiple <entry> items may have the same <id>. This can occur when the USGS provides updated information about a seismic event, such as after collecting more data and refining the estimate. Consequently, we must not only parse the XML <entry> items in the document, but also de-duplicate the data by ID, taking the most recent item when multiple items exist. Fortunately, there's an easy way to do this—accumulate the <entry> items in a hash indexed by the <id> field's value. Listing 4-11 shows the parsing and de-duplication that begins when the thread actually runs.

void WorkerThread::run()
{
    QuakeEvent anEvent;
    QXmlStreamReader xml;
    QXmlStreamReader::TokenType type;
    QString fieldName;
    QString value;
    QString tag;
    QMap<QString, QuakeEvent> events;
    bool successful = false;
    bool gotValue = false;
    bool gotEntry = false;

    xml.setDevice(mReply);
    while(!xml.atEnd())
    {
        // If we've been cancelled, stop processing.
        if (mCancelled) break;

        type = xml.readNext();
        QString tag = xml.name().toString().toLower();
        switch( type )
        {
            case QXmlStreamReader::StartElement:
                {
                    gotValue = false;
                    if (tag == "entry") {
                        gotEntry = true;
                    } else if (mXmlTags.contains(tag)) {
                        fieldName = tag;
                    } else {
                        fieldName = QString();
                    }
                }
                break;
            case QXmlStreamReader::Characters:
                // Save aside any text
                if ( gotEntry && !fieldName.isEmpty() && !gotValue)
                {
                    value = xml.text().toString();
                    gotValue = true;
                }
                break;
            case QXmlStreamReader::EndElement:
                // Save aside this value
                if (gotValue && tag != "entry") {

anEvent.set(fieldName, value);
                } else if (tag == "entry"){
                    events.insert(anEvent.id(), anEvent);
                    anEvent.clear();
                    gotEntry = false;
                    gotValue = false;
                }
                break;
            default:
                break;
        }
    }

    successful = xml.hasError() ? false : true;

    if (!mCancelled && successful) {
        mEventModel.removeRows(0, mEventModel.rowCount());
        mEventModel.insertRows(0, events.count(), QModelIndex());
        int row = 0;
        // Convert the hash into a list
        foreach(anEvent, events) {
            mEventModel.setData(row++, anEvent);
        }
        emit finished();
    } else if (!mCancelled) {
        emit error(tr("Could not interpret the server's response"));
    }
}

The QXMLStreamReader takes a QIODevice, so it's easily connected to either a file or a network result like this one. An event-generating stream-based parser, it's far more efficient to use than a DOM parser, although it requires a little more code. (This is a good trade-off, because neither the whole XML document nor the whole DOM must be stored in memory when using a streaming parser like this one.) In brief, we use the reader to walk through the stream a tag at a time, storing the characters bound by the tag. When the tag closes, the code looks to see if the closed tag was an entry tag. The parser accumulates data for the various sub-tags, creating a QuakeEvent in the hash for each <entry> tag indexed by its <id> tag. Once the parser completes scanning all tags, the code converts the hash to a list, enumerating the hash's entries and inserting them into the model. (Because our list view uses a proxy model that performs the sorting, it doesn't matter what order the hash's entries are inserted in the model.) After updating the model, the thread emits a finished signal so the UI knows that the download and parsing work is complete.

The QuakeEvent class is a data container and data helper class; it handles some of the messier bits of parsing the XML, such as converting the USGS time stamps into QDateTime instances that can be used elsewhere in the application. Listing 4-12 shows the class definition for QuakeEvent.

class QuakeEvent {
public:
    QuakeEvent();

    QString id() const;
    QString summary() const;
    QDateTime when() const;
    QString where() const;
    qreal magnitude() const;
    QPair<qreal, qreal> position() const;
    qreal elevation() const;
    QString html() const;

    // Used by the XML parser
    void set(const QString& name, const QString& value);
    QString get(const QString& name) const;

    bool isEmpty() const;
    void clear();

    // For use when sorting by time
    bool operator<(const QuakeEvent& b) const;

private:
    QMap<QString, QString> mData;
    static bool mRegisterMetaType;
};

The class itself stores the various fields of data in a hash table, and the accessor methods do a bit of necessary screen scraping to obtain semantically valid values for each field. For example, Listing 4-13 shows the code necessary to extract a numerical magnitude and QString containing the human-readable location for a single event.

qreal QuakeEvent::magnitude() const
{
    QString title = mData.value("title");
    // Format of title is "M 2.6, Baja California, Mexico"
    QString mag = title.mid(2, 3);
    return mag.toFloat();
}

QString QuakeEvent::where() const
{
    QString title = mData.value("title");
    // Format of title is "M 2.6, Baja California, Mexico"
    QString where = title.mid(title.indexOf(", ")+2);
    return where;
}

Similar—albeit more complex—work is done to render the dates to a format usable by Qt for sorting quake events.

The great thing about working with the MVC paradigm is that nothing special is required to display updated content—stick some data in the model, and poof! The view updates itself. Consequently, there's little need for the handleRequestFinished slot, shown in Listing 4-14.

void MainForm::handleRequestFinished() {
    mSortedModel->sort(0, Qt::DescendingOrder);
    mItemView->setHtml(tr("<body><p align="center">"
        "Select an item for more details.</p></body>"));
}

This method simply performs the deferred sorting of the data by recency, and provides a bit of help text in the QWebView. A more complex application might need to do more here, such as manage a distraction graphic.

In the section "Implementing the Application User Interface," in the MainForm's constructor, we connected a slot to the mListView's clicked method. Listing 4-15 shows this slot.

void MainForm::handleItemClicked(const QModelIndex& which)
{
    QVariant html = mSortedModel->data(which,
                                       QuakeListModel::Description);
    qDebug() << html.value<QString>();
    mItemView->setHtml(html.value<QString>());
}

This method just sets the HTML for the QWebView to the verbose description of the seismic event, letting the user see a small map indicating the event's position and more information about the event.