/****************************************************************************

**

** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the documentation of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

    \example sql/drilldown

    \title Drill Down Example

    The Drill Down example shows how to read data from a database as

    well as submit changes, using the QSqlRelationalTableModel and

    QDataWidgetMapper classes.

    \image drilldown-example.png Screenshot of the Drill Down Example

    When running the example application, a user can retrieve

    information about each of Nokia's Qt offices by clicking the

    corresponding image. The application pops up an information window

    displaying the data, and allows the users to alter the location

    description as well as the image. The main view will be updated

    when the users submit their changes.

    The example consists of three classes:

    \list

        \o \c ImageItem is a custom graphics item class used to

        display the office images.

        \o \c View is the main application widget allowing the user to

        browse through the various locations.

        \o \c InformationWindow displays the requested information,

        allowing the users to alter it and submit their changes to the

        database.

    \endlist

    We will first take a look at the \c InformationWindow class to see

    how you can read and modify data from a database. Then we will

    review the main application widget, i.e., the \c View class, and

    the associated \c ImageItem class.

    \section1 InformationWindow Class Definition

    The \c InformationWindow class is a custom widget inheriting

    QWidget:

    \snippet examples/sql/drilldown/informationwindow.h 0

    When we create an information window, we pass the associated

    location ID, a parent, and a pointer to the database, to the

    constructor. We will use the database pointer to populate our

    window with data, while passing the parent parameter on to the

    base class. The ID is stored for future reference.

    Once a window is created, we will use the public \c id() function

    to locate it whenever information for the given location is

    requested. We will also use the ID to update the main application

    widget when the users submit their changes to the database, i.e.,

    we will emit a signal carrying the ID and file name as parameters

    whenever the users changes the associated image.

    \snippet examples/sql/drilldown/informationwindow.h 1

    Since we allow the users to alter some of the location data, we

    must provide functionality for reverting and submitting their

    changes. The \c enableButtons() slot is provided for convenience

    to enable and disable the various buttons when required.

    \snippet examples/sql/drilldown/informationwindow.h 2

    The \c createButtons() function is also a convenience function,

    provided to simplify the constructor. As mentioned above we store

    the location ID for future reference. We also store the name of

    the currently displayed image file to be able to determine when to

    emit the \c imageChanged() signal.

    The information window uses the QLabel class to display the office

    location and the country. The associated image file is displayed

    using a QComboBox instance while the description is displayed using

    QTextEdit. In addition, the window has three buttons to control

    the data flow and whether the window is shown or not.

    Finally, we declare a \e mapper. The QDataWidgetMapper class

    provides mapping between a section of a data model to widgets. We

    will use the mapper to extract data from the given database,

    updating the database whenever the user modifies the data.

    \section1 InformationWindow Class Implementation

    The constructor takes three arguments: a location ID, a database

    pointer and a parent widget. The database pointer is actually a

    pointer to a QSqlRelationalTableModel object providing an editable

    data model (with foreign key support) for our database table.

    \snippet examples/sql/drilldown/informationwindow.cpp 0

    \snippet examples/sql/drilldown/informationwindow.cpp 1

    First we create the various widgets required to display the data

    contained in the database. Most of the widgets are created in a

    straight forward manner. But note the combobox displaying the

    name of the image file:

    \snippet examples/sql/drilldown/informationwindow.cpp 2

    In this example, the information about the offices are stored in a

    database table called "offices". When creating the model,

    we will use a foreign key to establish a relation between this

    table and a second data base table, "images", containing the names

    of the available image files. We will get back to how this is done

    when reviewing the \c View class. The rationale for creating such

    a relation though, is that we want to ensure that the user only

    can choose between predefined image files.

    The model corresponding to the "images" database table, is

    available through the QSqlRelationalTableModel's \l

    {QSqlRelationalTableModel::}{relationModel()} function, requiring

    the foreign key (in this case the "imagefile" column number) as

    argument. We use QComboBox's \l {QComboBox::}{setModel()} function

    to make the combobox use the "images" model. And, since this model

    has two columns ("locationid" and "file"), we also specify which

    column we want to be visible using the QComboBox::setModelColumn()

    function.

    \snippet examples/sql/drilldown/informationwindow.cpp 3

    Then we create the mapper. The QDataWidgetMapper class allows us

    to create data-aware widgets by mapping them to sections of an

    item model.

    The \l {QDataWidgetMapper::}{addMapping()} function adds a mapping

    between the given widget and the specified section of the

    model. If the mapper's orientation is horizontal (the default) the

    section is a column in the model, otherwise it is a row. We call

    the \l {QDataWidgetMapper::}{setCurrentIndex()} function to

    initialize the widgets with the data associated with the given

    location ID. Every time the current index changes, all the widgets

    are updated with the contents from the model.

    We also set the mapper's submit policy to

    QDataWidgetMapper::ManualSubmit. This means that no data is

    submitted to the database until the user expliclity requests a

    submit (the alternative is QDataWidgetMapper::AutoSubmit,

    automatically submitting changes when the corresponding widget

    looses focus). Finally, we specify the item delegate the mapper

    view should use for its items. The QSqlRelationalDelegate class

    represents a delegate that unlike the default delegate, enables

    combobox functionality for fields that are foreign keys into other

    tables (like "imagefile" in our "trolltechoffices" table).

    \snippet examples/sql/drilldown/informationwindow.cpp 4

    Finally, we connect the "something's changed" signals in the

    editors to our custom \c enableButtons() slot, enabling the users

    to either submit or revert their changes. We add all the widgets

    into a layout, store the location ID and the name of the displayed

    image file for future reference, and set the window title and

    initial size.

    Note that we also set the Qt::Window window flag to indicate that

    our widget is in fact a window, with a window system frame and a

    title bar.

    \snippet examples/sql/drilldown/informationwindow.cpp 5

    When a window is created, it is not deleted until the main

    application exits (i.e., if the user closes the information

    window, it is only hidden). For this reason we do not want to

    create more than one \c InformationWindow object for each

    location, and we provide the public \c id() function to be able to

    determine whether a window already exists for a given location

    when the user requests information about it.

    \snippet examples/sql/drilldown/informationwindow.cpp 6

    The \c revert() slot is triggered whenever the user hits the \gui

    Revert button.

    Since we set the QDataWidgetMapper::ManualSubmit submit policy,

    none of the user's changes are written back to the model unless

    the user expliclity choose to submit all of them. Nevertheless, we

    can use the QDataWidgetMapper's \l {QDataWidgetMapper::}{revert()}

    slot to reset the editor widgets, repopulating all widgets with

    the current data of the model.

    \snippet examples/sql/drilldown/informationwindow.cpp 7

    Likewise, the \c submit() slot is triggered whenever the users

    decide to submit their changes by pressing the \gui Submit button.

    We use QDataWidgetMapper's \l {QDataWidgetMapper::}{submit()} slot

    to submit all changes from the mapped widgets to the model,

    i.e. to the database. For every mapped section, the item delegate

    will then read the current value from the widget and set it in the

    model. Finally, the \e model's \l {QAbstractItemModel::}{submit()}

    function is invoked to let the model know that it should submit

    whatever it has cached to the permanent storage.

    Note that before any data is submitted, we check if the user has

    chosen another image file using the previously stored \c

    displayedImage variable as reference. If the current and stored

    file names differ, we store the new file name and emit the \c

    imageChanged() signal.

    \snippet examples/sql/drilldown/informationwindow.cpp 8

    The \c createButtons() function is provided for convenience, i.e.,

    to simplify the constructor.

    We make the \gui Close button the default button, i.e., the button

    that is pressed when the user presses \gui Enter, and connect its

    \l {QPushButton::}{clicked()} signal to the widget's \l

    {QWidget::}{close()} slot. As mentioned above closing the window

    only hides the widget; it is not deleted. We also connect the \gui

    Submit and \gui Revert buttons to the corresponding \c submit()

    and \c revert() slots.

    \snippet examples/sql/drilldown/informationwindow.cpp 9

    The QDialogButtonBox class is a widget that presents buttons in a

    layout that is appropriate to the current widget style. Dialogs

    like our information window, typically present buttons in a layout

    that conforms to the interface guidelines for that

    platform. Invariably, different platforms have different layouts

    for their dialogs. QDialogButtonBox allows us to add buttons,

    automatically using the appropriate layout for the user's desktop

    environment.

    Most buttons for a dialog follow certain roles. We give the \gui

    Submit and \gui Revert buttons the \l

    {QDialogButtonBox::ButtonRole}{reset} role, i.e., indicating that

    pressing the button resets the fields to the default values (in

    our case the information contained in the database). The \l

    {QDialogButtonBox::ButtonRole}{reject} role indicates that

    clicking the button causes the dialog to be rejected. On the other

    hand, since we only hide the information window, any changes that

    the user has made wil be preserved until the user expliclity

    revert or submit them.

    \snippet examples/sql/drilldown/informationwindow.cpp 10

    The \c enableButtons() slot is called to enable the buttons

    whenever the user changes the presented data. Likewise, when the

    data the user choose to submit the changes, the buttons are

    disabled to indicate that the current data is stored in the

    database.

    This completes the \c InformationWindow class. Let's take a look

    at how we have used it in our example application.

    \section1 View Class Definition

    The \c View class represents the main application window and

    inherits QGraphicsView:

    \snippet examples/sql/drilldown/view.h 0

    \codeline

    \snippet examples/sql/drilldown/view.h 1

    The QGraphicsView class is part of the \l {The Graphics View

    Framework} which we will use to display the images of Nokia's

    Qt offices. To be able to respond to user interaction;

    i.e., showing the

    appropriate information window whenever the user clicks one of the

    office images, we reimplement QGraphicsView's \l

    {QGraphicsView::}{mouseReleaseEvent()} function.

    Note that the constructor expects the names of two database

    tables: One containing the detailed information about the offices,

    and another containing the names of the available image files.  We

    also provide a private \c updateImage() slot to catch \c

    {InformationWindow}'s \c imageChanged() signal that is emitted

    whenever the user changes a location's image.

    \snippet examples/sql/drilldown/view.h 2

    The \c addItems() function is a convenience function provided to

    simplify the constructor. It is called only once, creating the

    various items and adding them to the view.

    The \c findWindow() function, on the other hand, is frequently

    used. It is called from the \c showInformation() function to

    detemine whether a window is already created for the given

    location (whenever we create an \c InformationWindow object, we

    store a reference to it in the \c informationWindows list). The

    latter function is in turn called from our custom \c

    mouseReleaseEvent() implementation.

    \snippet examples/sql/drilldown/view.h 3

    Finally we declare a QSqlRelationalTableModel pointer. As

    previously mentioned, the QSqlRelationalTableModel class provides

    an editable data model with foreign key support. There are a

    couple of things you should keep in mind when using the

    QSqlRelationalTableModel class: The table must have a primary key

    declared and this key cannot contain a relation to another table,

    i.e., it cannot be a foreign key. Note also that if a relational

    table contains keys that refer to non-existent rows in the

    referenced table, the rows containing the invalid keys will not be

    exposed through the model. It is the user's or the database's

    responsibility to maintain referential integrity.

    \section1 View Class Implementation

    Although the constructor requests the names of both the table

    containing office details as well as the table containing the

    names of the available image files, we only have to create a

    QSqlRelationalTableModel object for the office table:

    \snippet examples/sql/drilldown/view.cpp 0

    The reason is that once we have a model with the office details,

    we can create a relation to the available image files using

    QSqlRelationalTableModel's \l

    {QSqlRelationalTableModel::}{setRelation()} function. This

    function creates a foreign key for the given model column. The key

    is specified by the provided QSqlRelation object constructed by

    the name of the table the key refers to, the field the key is

    mapping to and the field that should be presented to the user.

    Note that setting the table only specifies which table the model

    operates on, i.e., we must explicitly call the model's \l

    {QSqlRelationalTableModel::}{select()} function to populate our

    model.

    \snippet examples/sql/drilldown/view.cpp 1

    Then we create the contents of our view, i.e., the scene and its

    items. The location labels are regular QGraphicsTextItem objects,

    and the "Qt" logo is represented by a QGraphicsPixmapItem

    object. The images, on the other hand, are instances of the \c

    ImageItem class (derived from QGraphicsPixmapItem). We will get

    back to this shortly when reviewing the \c addItems() function.

    Finally, we set the main application widget's size constraints and

    window title.

    \snippet examples/sql/drilldown/view.cpp 3

    The \c addItems() function is called only once, i.e., when

    creating the main application window. For each row in the database

    table, we first extract the corresponding record using the model's

    \l {QSqlRelationalTableModel::}{record()} function. The QSqlRecord

    class encapsulates both the functionality and characteristics of a

    database record, and supports adding and removing fields as well

    as setting and retrieving field values. The QSqlRecord::value()

    function returns the value of the field with the given name or

    index as a QVariant object.

    For each record, we create a label item as well as an image item,

    calculate their position and add them to the scene. The image

    items are represented by instances of the \c ImageItem class. The

    reason we must create a custom item class is that we want to catch

    the item's hover events, animating the item when the mouse cursor

    is hovering over the image (by default, no items accept hover

    events). Please see the \l{The Graphics View Framework}

    documentation and the \l{Graphics View Examples} for more details.

    \snippet examples/sql/drilldown/view.cpp 5

    We reimplement QGraphicsView's \l

    {QGraphicsView::}{mouseReleaseEvent()} event handler to respond to

    user interaction. If the user clicks any of the image items, this

    function calls the private \c showInformation() function to pop up

    the associated information window.

    \l {The Graphics View Framework} provides the qgraphicsitem_cast()

    function to determine whether the given QGraphicsItem instance is

    of a given type. Note that if the event is not related to any of

    our image items, we pass it on to the base class implementation.

    \snippet examples/sql/drilldown/view.cpp 6

    The \c showInformation() function is given an \c ImageItem object

    as argument, and starts off by extracting the item's location

    ID. Then it determines if there already is created an information

    window for this location. If it is, and the window is visible, it

    ensures that the window is raised to the top of the widget stack

    and activated. If the window exists but is hidden, calling its \l

    {QWidget::}{show()} slot gives the same result.

    If no window for the given location exists, we create one by

    passing the location ID, a pointer to the model, and our view as a

    parent, to the \c InformationWindow constructor. Note that we

    connect the information window's \c imageChanged() signal to \e

    this widget's \c updateImage() slot, before we give it a suitable

    position and add it to the list of existing windows.

    \snippet examples/sql/drilldown/view.cpp 7

    The \c updateImage() slot takes a location ID and the name of an

    image files as arguments. It filters out the image items, and

    updates the one that correspond to the given location ID, with the

    provided image file.

    \snippet examples/sql/drilldown/view.cpp 8

    The \c findWindow() function simply searches through the list of

    existing windows, returning a pointer to the window that matches

    the given location ID, or 0 if the window doesn't exists.

    Finally, let's take a quick look at our custom \c ImageItem class:

    \section1 ImageItem Class Definition

    The \c ImageItem class is provided to facilitate animation of the

    image items. It inherits QGraphicsPixmapItem and reimplements its

    hover event handlers:

    \snippet examples/sql/drilldown/imageitem.h 0

    In addition, we implement a public \c id() function to be able to

    identify the associated location and a public \c adjust() function

    that can be called to ensure that the image item is given the

    preferred size regardless of the original image file.

    The animation is implemented using the QTimeLine class together

    with the event handlers and the private \c setFrame() slot: The

    image item will expand when the mouse cursor hovers over it,

    returning back to its orignal size when the cursor leaves its

    borders.

    Finally, we store the location ID that this particular record is

    associated with as well as a z-value. In the \l {The Graphics View

    Framework}, an item's z-value determines its position in the item

    stack. An item of high Z-value will be drawn on top of an item

    with a lower z-value if they share the same parent item. We also

    provide an \c updateItemPosition() function to refresh the view

    when required.

    \section1 ImageItem Class Implementation

    The \c ImageItem class is really only a QGraphicsPixmapItem with

    some additional features, i.e., we can pass most of the

    constructor's arguments (the pixmap, parent and scene) on to the

    base class constructor:

    \snippet examples/sql/drilldown/imageitem.cpp 0

    Then we store the ID for future reference, and ensure that our

    item will accept hover events. Hover events are delivered when

    there is no current mouse grabber item. They are sent when the

    mouse cursor enters an item, when it moves around inside the item,

    and when the cursor leaves an item. As we mentioned earlier, none

    of the \l {The Graphics View Framework}'s items accept hover

    event's by default.

    The QTimeLine class provides a timeline for controlling

    animations. Its \l {QTimeLine::}{duration} property holds the

    total duration of the timeline in milliseconds. By default, the

    time line runs once from the beginning and towards the end. The

    QTimeLine::setFrameRange() function sets the timeline's frame

    counter; when the timeline is running, the \l

    {QTimeLine::}{frameChanged()} signal is emitted each time the

    frame changes. We set the duration and frame range for our

    animation, and connect the time line's \l

    {QTimeLine::}{frameChanged()} and \l {QTimeLine::}{finished()}

    signals to our private \c setFrame() and \c updateItemPosition()

    slots.

    Finally, we call \c adjust() to ensure that the item is given the

    preferred size.

    \snippet examples/sql/drilldown/imageitem.cpp 1

    \codeline

    \snippet examples/sql/drilldown/imageitem.cpp 2

    Whenever the mouse cursor enters or leave the image item, the

    corresponding event handlers are triggered: We first set the time

    line's direction, making the item expand or shrink,

    respectively. Then we alter the item's z-value if it is not already

    set to the expected value.

    In the case of hover \e enter events, we immediately update the

    item's position since we want the item to appear on top of all

    other items as soon as it starts expanding. In the case of hover

    \e leave events, on the other hand, we postpone the actual update

    to achieve the same result. But remember that when we constructed

    our item, we connected the time line's \l

    {QTimeLine::}{finished()} signal to the \c updateItemPosition()

    slot. In this way the item is given the correct position in the

    item stack once the animation is completed. Finally, if the time

    line is not already running, we start it.

    \snippet examples/sql/drilldown/imageitem.cpp 3

    When the time line is running, it triggers the \c setFrame() slot

    whenever the current frame changes due to the connection we

    created in the item constructor. It is this slot that controls the

    animation, expanding or shrinking the image item step by step.

    We first call the \c adjust() function to ensure that we start off

    with the item's original size. Then we scale the item with a

    factor depending on the animation's progress (using the \c frame