Changes: Improved Tutorial document

RevBy: Sergiy Dubovik
Details: It's mostly done now.

22 files changed, 1020 insertions, 0 deletions

diff --git a/examples/tutorial/tutorial_music_albumpage.cpp b/examples/tutorial/tutorial_music_albumpage.cpp
new file mode 100644
index 00000000..9f9e37bd
--- /dev/null
+++ b/examples/tutorial/tutorial_music_albumpage.cpp
@@ -0,0 +1,33 @@
+// Filename: albumpage.cpp
+#include "albumpage.h"
+
+#include <MLabel>
+#include <MBasicListItem>
+#include <MImageWidget>
+#include <QGraphicsLinearLayout>
+
+AlbumPage::AlbumPage(const Album *album, QGraphicsItem *parent)
+    : MApplicationPage(parent), album(album)
+{
+    setTitle(album->title);
+}
+
+void AlbumPage::createContent()
+{
+    QGraphicsLinearLayout *layout = new QGraphicsLinearLayout(Qt::Vertical);
+    centralWidget()->setLayout(layout);
+
+    MImageWidget *albumCover = new MImageWidget(new QImage(album->coverArtFilename));
+    layout->addItem(albumCover);
+
+    QString byArtist = QString("By: %1").arg(album->artist);
+    layout->addItem(new MLabel(byArtist));
+
+    layout->addItem(new MLabel("Songs:"));
+
+    MLabel *songLabel;
+    for (int i = 0; i < album->songs.count(); i++) {
+        songLabel = new MLabel(album->songs.at(i));
+        layout->addItem(songLabel);
+    }
+}
diff --git a/examples/tutorial/tutorial_music_albumpage.h b/examples/tutorial/tutorial_music_albumpage.h
new file mode 100644
index 00000000..5ac00f5a
--- /dev/null
+++ b/examples/tutorial/tutorial_music_albumpage.h
@@ -0,0 +1,21 @@
+// Filename: albumpage.h
+#ifndef ALBUMPAGE_H
+#define ALBUMPAGE_H
+
+#include <MApplicationPage>
+
+#include "data.h"
+
+class AlbumPage : public MApplicationPage {
+    Q_OBJECT
+public:
+    AlbumPage(const Album *album, QGraphicsItem *parent = 0);
+
+protected:
+    virtual void createContent();
+
+private:
+    const Album *album;
+};
+
+#endif
diff --git a/examples/tutorial/tutorial_music_artistpage.cpp b/examples/tutorial/tutorial_music_artistpage.cpp
new file mode 100644
index 00000000..51af0bd6
--- /dev/null
+++ b/examples/tutorial/tutorial_music_artistpage.cpp
@@ -0,0 +1,49 @@
+// Filename: artistpage.cpp
+#include "artistpage.h"
+
+#include <MButton>
+#include <MButtonGroup>
+#include <MLabel>
+#include <MSceneManager>
+#include <QGraphicsLinearLayout>
+
+#include "albumpage.h"
+
+ArtistPage::ArtistPage(const Artist *artist, QGraphicsItem *parent)
+    : MApplicationPage(parent), artist(artist)
+{
+    setTitle(artist->name);
+}
+
+void ArtistPage::createContent()
+{
+    QGraphicsLinearLayout *layout = new QGraphicsLinearLayout(Qt::Vertical);
+    centralWidget()->setLayout(layout);
+
+    layout->addItem(new MLabel("Albums:"));
+
+    MButtonGroup *buttonGroup = new MButtonGroup(this);
+
+    Album *album;
+    MButton *albumButton;
+    for (int i = 0; i < artist->albums.count(); i++) {
+        album = artist->albums[i];
+
+        albumButton = new MButton;
+        albumButton->setText(album->title);
+
+        layout->addItem(albumButton);
+        buttonGroup->addButton(albumButton, i);
+    }
+
+    connect(buttonGroup, SIGNAL(buttonClicked(int)),
+            this, SLOT(displayAlbum(int)));
+}
+
+void ArtistPage::displayAlbum(int albumIndex)
+{
+    Album *album = artist->albums[albumIndex];
+
+    AlbumPage *albumPage = new AlbumPage(album);
+    sceneManager()->appearSceneWindow(albumPage, MSceneWindow::DestroyWhenDismissed);
+}
diff --git a/examples/tutorial/tutorial_music_artistpage.h b/examples/tutorial/tutorial_music_artistpage.h
new file mode 100644
index 00000000..8ce7c0a1
--- /dev/null
+++ b/examples/tutorial/tutorial_music_artistpage.h
@@ -0,0 +1,24 @@
+// Filename: artistpage.h
+#ifndef ARTISTPAGE_H
+#define ARTISTPAGE_H
+
+#include <MApplicationPage>
+
+#include "data.h"
+
+class ArtistPage : public MApplicationPage {
+    Q_OBJECT
+public:
+    ArtistPage(const Artist *artist, QGraphicsItem *parent = 0);
+
+protected:
+    virtual void createContent();
+
+private slots:
+    void displayAlbum(int albumIndex);
+
+private:
+    const Artist *artist;
+};
+
+#endif
diff --git a/examples/tutorial/tutorial_music_data.h b/examples/tutorial/tutorial_music_data.h
new file mode 100644
index 00000000..09c20062
--- /dev/null
+++ b/examples/tutorial/tutorial_music_data.h
@@ -0,0 +1,24 @@
+// data.h
+#ifndef DATA_H
+#define DATA_H
+
+#include <QString>
+#include <QStringList>
+
+class Album {
+public:
+    QString title;
+    QString artist;
+    QString coverArtFilename;
+    QStringList songs;
+};
+
+class Artist {
+public:
+    virtual ~Artist() { qDeleteAll(albums); }
+
+    QString name;
+    QList<Album *> albums;
+};
+
+#endif
diff --git a/examples/tutorial/tutorial_music_filloutdata.cpp b/examples/tutorial/tutorial_music_filloutdata.cpp
new file mode 100644
index 00000000..88446ddf
--- /dev/null
+++ b/examples/tutorial/tutorial_music_filloutdata.cpp
@@ -0,0 +1,96 @@
+// Enters some hardcoded sample data
+// Make sure you have a "album_cover.jpg" in the directory
+// where you run your sample application.
+void fillOutData(QList<Artist *> &artistList)
+{
+    Artist *artist;
+    Album *album;
+
+    artist = new Artist;
+    artist->name = "The Beatles";
+
+    album = new Album;
+    album->title = "Sgt. Pepper's Lonely Hearts Club Band";
+    album->artist = "The Beatles";
+    album->coverArtFilename = "album_cover.jpg";
+    album->songs << "Sgt. Pepper's Lonely Hearts Club Band";
+    album->songs << "With a Little Help from My Friends";
+    album->songs << "Lucy in the Sky with Diamonds";
+    album->songs << "Getting Better";
+    album->songs << "Fixing a Hole";
+    album->songs << "She's Leaving Home";
+    album->songs << "Being for the Benefit of Mr. Kite!";
+    artist->albums << album;
+
+    album = new Album;
+    album->title = "Yellow Submarine";
+    album->artist = "The Beatles";
+    album->coverArtFilename = "album_cover.jpg";
+    album->songs << "Yellow Submarine";
+    album->songs << "Only a Northern Song";
+    album->songs << "All Together Now";
+    album->songs << "Hey Bulldog";
+    album->songs << "It's All Too Much";
+    album->songs << "All You Need Is Love";
+    artist->albums << album;
+
+    album = new Album;
+    album->title = "Abbey Road";
+    album->artist = "The Beatles";
+    album->coverArtFilename = "album_cover.jpg";
+    album->songs << "Come Together";
+    album->songs << "Something";
+    album->songs << "Maxwell's Silver Hammer";
+    album->songs << "Oh! Darling";
+    album->songs << "Octopus's Garden";
+    album->songs << "I Want You (She's So Heavy)";
+    artist->albums << album;
+
+    artistList << artist;
+
+
+
+    artist = new Artist;
+    artist->name = "Led Zeppelin";
+
+    album = new Album;
+    album->title = "Physical Graffiti";
+    album->artist = "Led Zeppelin";
+    album->coverArtFilename = "album_cover.jpg";
+    album->songs << "Custard Pie";
+    album->songs << "The Rover";
+    album->songs << "In My Time of Dying";
+    album->songs << "Houses of the Holy";
+    album->songs << "Trampled Under Foot";
+    album->songs << "Kashmir";
+    artist->albums << album;
+
+    album = new Album;
+    album->title = "Houses of the Holy";
+    album->artist = "Led Zeppelin";
+    album->coverArtFilename = "album_cover.jpg";
+    album->songs << "The Song Remains the Same";
+    album->songs << "The Rain Song";
+    album->songs << "Over the Hills and Far Away";
+    album->songs << "The Crunge";
+    album->songs << "Dancing Days";
+    album->songs << "D'yer Mak'er";
+    album->songs << "No Quarter";
+    album->songs << "The Ocean";
+    artist->albums << album;
+
+    album = new Album;
+    album->title = "Presence";
+    album->artist = "Led Zeppelin";
+    album->coverArtFilename = "album_cover.jpg";
+    album->songs << "Achilles Last Stand";
+    album->songs << "For Your Life";
+    album->songs << "Royal Orleans";
+    album->songs << "Nobody's Fault but Mine";
+    album->songs << "Candy Store Rock";
+    album->songs << "Hots On for Nowhere";
+    album->songs << "Tea for One";
+    artist->albums << album;
+
+    artistList << artist;
+}
diff --git a/examples/tutorial/tutorial_music_main.cpp b/examples/tutorial/tutorial_music_main.cpp
new file mode 100644
index 00000000..c1434b20
--- /dev/null
+++ b/examples/tutorial/tutorial_music_main.cpp
@@ -0,0 +1,34 @@
+#include <MApplication>
+#include <MApplicationWindow>
+
+// The definition of our data classes
+#include "data.h"
+
+#include "mainpage.h"
+
+void fillOutData(QList<Artist *> &artistList);
+
+int main(int argc, char **argv)
+{
+    MApplication app(argc, argv);
+    MApplicationWindow window;
+    MainPage *mainPage;
+
+    // That's the data that will be displayed by our application.
+    // For the sake of keeping the example as simple as possible we use
+    // a very simplistic data structure.
+    QList<Artist *> artistsList;
+    fillOutData(artistsList);
+
+    mainPage = new MainPage(artistsList);
+
+    mainPage->appear(&window);
+    window.show();
+
+    return app.exec();
+}
+
+void fillOutData(QList<Artist *> &artistList)
+{
+    ...
+}
diff --git a/examples/tutorial/tutorial_music_mainpage.cpp b/examples/tutorial/tutorial_music_mainpage.cpp
new file mode 100644
index 00000000..05826722
--- /dev/null
+++ b/examples/tutorial/tutorial_music_mainpage.cpp
@@ -0,0 +1,75 @@
+// Filename: mainpage.cpp
+#include "mainpage.h"
+
+#include <MButton>
+#include <MButtonGroup>
+#include <MLabel>
+#include <MSceneManager>
+#include <QGraphicsLinearLayout>
+
+#include "artistpage.h"
+
+MainPage::MainPage(QList<Artist *> artistsList, QGraphicsItem *parent)
+    : MApplicationPage(parent), artistsList(artistsList)
+{
+    // OBS: in a real application you shouldn't hardcode strings used
+    // in the GUI like that but use the translation system to fetch
+    // the correct, localised, string instead.
+    setTitle("Music Catalogue");
+}
+
+MainPage::~MainPage()
+{
+    qDeleteAll(artistsList);
+}
+
+// This is a virtual method that gets called only once by the framework,
+// right before your page begins to appear on the scene.
+void MainPage::createContent()
+{
+    // We want to organize our items in a single column. A vertical
+    // layout enables us to easily achieve this arrangement.
+    // Layout classes take care of setting the correct geometry (size and position)
+    // of the items added to it.
+    QGraphicsLinearLayout *layout = new QGraphicsLinearLayout(Qt::Vertical);
+    centralWidget()->setLayout(layout);
+
+    // Items in a vertical layout are arranged from top to bottom.
+    // Thus the label "Artists:" will come first, therefore serving
+    // the title of our list.
+    layout->addItem(new MLabel("Artists:"));
+
+    MButtonGroup *buttonGroup = new MButtonGroup(this);
+
+    Artist *artist;
+    MButton *artistButton;
+    for (int i = 0; i < artistsList.count(); i++) {
+        artist = artistsList[i];
+
+        artistButton = new MButton;
+        artistButton->setText(artist->name);
+
+        layout->addItem(artistButton);
+        buttonGroup->addButton(artistButton, i);
+    }
+
+    // A MButtonGroup is used because it provides a signal that is emitted
+    // whenever any of the buttons added to it gets clicked.
+    // MButtonGroup groups the buttons logically only. Their graphical
+    // positioning is still handled by the layout.
+    connect(buttonGroup, SIGNAL(buttonClicked(int)),
+            this, SLOT(displayArtist(int)));
+}
+
+void MainPage::displayArtist(int artistIndex)
+{
+    Artist *artist = artistsList[artistIndex];
+
+    ArtistPage *artistPage = new ArtistPage(artist);
+
+    // When the back button is pressed, the page gets dismissed.
+    // By setting MSceneWindow::DestroyWhenDismissed we don't have to
+    // keep tabs on this page since it will be automatically destroyed
+    // after the dismissal.
+    sceneManager()->appearSceneWindow(artistPage, MSceneWindow::DestroyWhenDismissed);
+}
diff --git a/examples/tutorial/tutorial_music_mainpage.h b/examples/tutorial/tutorial_music_mainpage.h
new file mode 100644
index 00000000..39fd1c0a
--- /dev/null
+++ b/examples/tutorial/tutorial_music_mainpage.h
@@ -0,0 +1,26 @@
+// Filename: mainpage.h
+#ifndef MAINPAGE_H
+#define MAINPAGE_H
+
+#include <MApplicationPage>
+
+#include "data.h"
+
+class MainPage : public MApplicationPage {
+    Q_OBJECT
+public:
+    MainPage(QList<Artist *> artistsList, QGraphicsItem *parent = 0);
+    virtual ~MainPage();
+
+protected:
+    // From MApplicationPage
+    virtual void createContent();
+
+private slots:
+    void displayArtist(int artistIndex);
+
+private:
+    QList<Artist *> artistsList;
+};
+
+#endif
diff --git a/examples/tutorial/tutorial_orientations_albumpage.cpp b/examples/tutorial/tutorial_orientations_albumpage.cpp
new file mode 100644
index 00000000..a0c8b29d
--- /dev/null
+++ b/examples/tutorial/tutorial_orientations_albumpage.cpp
@@ -0,0 +1,37 @@
+void AlbumPage::createContent()
+{
+    MLayout *layout = new MLayout;
+    centralWidget()->setLayout(layout);
+
+    // Build a vertical layout that holds the cover art and the "By: Artist" label.
+    QGraphicsLinearLayout *coverAndArtistLayout = new QGraphicsLinearLayout(Qt::Vertical);
+
+    MImageWidget *albumCover = new MImageWidget(new QImage(album->coverArtFilename));
+    coverAndArtistLayout->addItem(albumCover);
+
+    QString byArtist = QString("By: %1").arg(album->artist);
+    coverAndArtistLayout->addItem(new MLabel(byArtist));
+
+    // Build a vertical layout that will hold the list of songs.
+    QGraphicsLinearLayout *songsLayout = new QGraphicsLinearLayout(Qt::Vertical);
+    songsLayout->addItem(new MLabel("Songs:"));
+    MLabel *songLabel;
+    for (int i = 0; i < album->songs.count(); i++) {
+        songLabel = new MLabel(album->songs.at(i));
+        songsLayout->addItem(songLabel);
+    }
+
+    // When in landscape orientation, have the cover and the songs list
+    // side-by-side.
+    MLinearLayoutPolicy *landscapePolicy = new MLinearLayoutPolicy(layout, Qt::Horizontal);
+    landscapePolicy->addItem(coverAndArtistLayout);
+    landscapePolicy->addItem(songsLayout);
+    layout->setLandscapePolicy(landscapePolicy);
+
+    // When in portrait orientation, have the cover and the songs list
+    // on top of each other.
+    MLinearLayoutPolicy *portraitPolicy = new MLinearLayoutPolicy(layout, Qt::Vertical);
+    portraitPolicy->addItem(coverAndArtistLayout);
+    portraitPolicy->addItem(songsLayout);
+    layout->setPortraitPolicy(portraitPolicy);
+}
diff --git a/examples/tutorial_music_catalogue/album_cover.jpg b/examples/tutorial_music_catalogue/album_cover.jpg
new file mode 100644
index 00000000..4ac21785
--- /dev/null
+++ b/examples/tutorial_music_catalogue/album_cover.jpg
diff --git a/examples/tutorial_music_catalogue/albumpage.cpp b/examples/tutorial_music_catalogue/albumpage.cpp
new file mode 100644
index 00000000..18facc02
--- /dev/null
+++ b/examples/tutorial_music_catalogue/albumpage.cpp
@@ -0,0 +1,95 @@
+#include "albumpage.h"
+
+#include <MImageWidget>
+#include <MLabel>
+#include <MLayout>
+#include <MLinearLayoutPolicy>
+#include <QGestureEvent>
+#include <QGraphicsLinearLayout>
+#include <QPinchGesture>
+#include <QPropertyAnimation>
+
+AlbumPage::AlbumPage(const Album *album, QGraphicsItem *parent)
+    : MApplicationPage(parent), album(album), albumCover(0)
+{
+    setTitle(album->title);
+    connect(this, SIGNAL(appeared()), SLOT(fadeInAlbumCover()));
+
+    setAcceptTouchEvents(true);
+    grabGesture(Qt::PinchGesture);
+}
+
+void AlbumPage::createContent()
+{
+    MLayout *layout = new MLayout;
+    centralWidget()->setLayout(layout);
+
+    // Build a vertical layout that holds the cover art and the "By: Artist" label.
+    QGraphicsLinearLayout *coverAndArtistLayout = new QGraphicsLinearLayout(Qt::Vertical);
+
+    albumCover = new MImageWidget(new QImage(album->coverArtFilename));
+    albumCover->setOpacity(0.0); // starts completely transparent
+    coverAndArtistLayout->addItem(albumCover);
+
+    QString byArtist = QString("By: %1").arg(album->artist);
+    coverAndArtistLayout->addItem(new MLabel(byArtist));
+
+    // Build a vertical layout that will hold the list of songs.
+    QGraphicsLinearLayout *songsLayout = new QGraphicsLinearLayout(Qt::Vertical);
+    songsLayout->addItem(new MLabel("Songs:"));
+    MLabel *songLabel;
+    for (int i = 0; i < album->songs.count(); i++) {
+        songLabel = new MLabel(album->songs.at(i));
+        songsLayout->addItem(songLabel);
+    }
+
+    // When in landscape orientation, have the cover and the songs list
+    // side-by-side.
+    MLinearLayoutPolicy *landscapePolicy = new MLinearLayoutPolicy(layout, Qt::Horizontal);
+    landscapePolicy->addItem(coverAndArtistLayout);
+    landscapePolicy->addItem(songsLayout);
+    layout->setLandscapePolicy(landscapePolicy);
+
+    // When in portrait orientation, have the cover and the songs list
+    // on top of each other.
+    MLinearLayoutPolicy *portraitPolicy = new MLinearLayoutPolicy(layout, Qt::Vertical);
+    portraitPolicy->addItem(coverAndArtistLayout);
+    portraitPolicy->addItem(songsLayout);
+    layout->setPortraitPolicy(portraitPolicy);
+}
+
+void AlbumPage::fadeInAlbumCover()
+{
+    QPropertyAnimation *fadeInAnimation = new QPropertyAnimation;
+    fadeInAnimation->setTargetObject(albumCover);
+    fadeInAnimation->setPropertyName("opacity");
+    fadeInAnimation->setStartValue(0.0);
+    fadeInAnimation->setEndValue(1.0);
+    fadeInAnimation->setDuration(1000.0);
+    fadeInAnimation->start(QAbstractAnimation::DeleteWhenStopped);
+}
+
+void AlbumPage::pinchGestureEvent(QGestureEvent *event, QPinchGesture *gesture)
+{
+    static QPointF originalZoomFactor;
+
+    if (gesture->state() == Qt::GestureStarted) {
+        albumCover->zoomFactor(&originalZoomFactor.rx(), &originalZoomFactor.ry());
+
+        // Disable panning while we're pinching the image
+        setPannable(false);
+    } else if (gesture->state() == Qt::GestureFinished ||
+            gesture->state() == Qt::GestureCanceled) {
+        // Re-enable panning after the pinching gesture has ended.
+        setPannable(true);
+    }
+
+    albumCover->setZoomFactor(
+            originalZoomFactor.x() * gesture->scaleFactor(),
+            originalZoomFactor.y() * gesture->scaleFactor());
+
+    // Force a repaint of the album cover.
+    albumCover->update();
+
+    event->accept(gesture);
+}
diff --git a/examples/tutorial_music_catalogue/albumpage.h b/examples/tutorial_music_catalogue/albumpage.h
new file mode 100644
index 00000000..cb073840
--- /dev/null
+++ b/examples/tutorial_music_catalogue/albumpage.h
@@ -0,0 +1,31 @@
+#ifndef ALBUMPAGE_H
+#define ALBUMPAGE_H
+
+#include <MApplicationPage>
+
+class MImageWidget;
+class QGestureEvent;
+class QPinchGesture;
+
+#include "data.h"
+
+class AlbumPage : public MApplicationPage {
+    Q_OBJECT
+public:
+    AlbumPage(const Album *album, QGraphicsItem *parent = 0);
+
+protected:
+    virtual void createContent();
+
+    // From MWidget
+    virtual void pinchGestureEvent(QGestureEvent *event, QPinchGesture *gesture);
+
+private slots:
+    void fadeInAlbumCover();
+
+private:
+    const Album *album;
+    MImageWidget *albumCover;
+};
+
+#endif
diff --git a/examples/tutorial_music_catalogue/artistpage.cpp b/examples/tutorial_music_catalogue/artistpage.cpp
new file mode 100644
index 00000000..be4fa0c4
--- /dev/null
+++ b/examples/tutorial_music_catalogue/artistpage.cpp
@@ -0,0 +1,48 @@
+#include "artistpage.h"
+
+#include <MButton>
+#include <MButtonGroup>
+#include <MLabel>
+#include <MSceneManager>
+#include <QGraphicsLinearLayout>
+
+#include "albumpage.h"
+
+ArtistPage::ArtistPage(const Artist *artist, QGraphicsItem *parent)
+    : MApplicationPage(parent), artist(artist)
+{
+    setTitle(artist->name);
+}
+
+void ArtistPage::createContent()
+{
+    QGraphicsLinearLayout *layout = new QGraphicsLinearLayout(Qt::Vertical);
+    centralWidget()->setLayout(layout);
+
+    layout->addItem(new MLabel("Albums:"));
+
+    MButtonGroup *buttonGroup = new MButtonGroup(this);
+
+    Album *album;
+    MButton *albumButton;
+    for (int i = 0; i < artist->albums.count(); i++) {
+        album = artist->albums[i];
+
+        albumButton = new MButton;
+        albumButton->setText(album->title);
+
+        layout->addItem(albumButton);
+        buttonGroup->addButton(albumButton, i);
+    }
+
+    connect(buttonGroup, SIGNAL(buttonClicked(int)),
+            this, SLOT(displayAlbum(int)));
+}
+
+void ArtistPage::displayAlbum(int albumIndex)
+{
+    Album *album = artist->albums[albumIndex];
+
+    AlbumPage *albumPage = new AlbumPage(album);
+    sceneManager()->appearSceneWindow(albumPage, MSceneWindow::DestroyWhenDismissed);
+}
diff --git a/examples/tutorial_music_catalogue/artistpage.h b/examples/tutorial_music_catalogue/artistpage.h
new file mode 100644
index 00000000..68f20614
--- /dev/null
+++ b/examples/tutorial_music_catalogue/artistpage.h
@@ -0,0 +1,23 @@
+#ifndef ARTISTPAGE_H
+#define ARTISTPAGE_H
+
+#include <MApplicationPage>
+
+#include "data.h"
+
+class ArtistPage : public MApplicationPage {
+    Q_OBJECT
+public:
+    ArtistPage(const Artist *artist, QGraphicsItem *parent = 0);
+
+protected:
+    virtual void createContent();
+
+private slots:
+    void displayAlbum(int albumIndex);
+
+private:
+    const Artist *artist;
+};
+
+#endif
diff --git a/examples/tutorial_music_catalogue/data.h b/examples/tutorial_music_catalogue/data.h
new file mode 100644
index 00000000..09c20062
--- /dev/null
+++ b/examples/tutorial_music_catalogue/data.h
@@ -0,0 +1,24 @@
+// data.h
+#ifndef DATA_H
+#define DATA_H
+
+#include <QString>
+#include <QStringList>
+
+class Album {
+public:
+    QString title;
+    QString artist;
+    QString coverArtFilename;
+    QStringList songs;
+};
+
+class Artist {
+public:
+    virtual ~Artist() { qDeleteAll(albums); }
+
+    QString name;
+    QList<Album *> albums;
+};
+
+#endif
diff --git a/examples/tutorial_music_catalogue/main.cpp b/examples/tutorial_music_catalogue/main.cpp
new file mode 100644
index 00000000..5162946f
--- /dev/null
+++ b/examples/tutorial_music_catalogue/main.cpp
@@ -0,0 +1,123 @@
+#include <MApplication>
+#include <MApplicationWindow>
+
+// The definition of our data classes
+#include "data.h"
+
+#include "mainpage.h"
+
+void fillOutData(QList<Artist *> &artistList);
+
+int main(int argc, char **argv)
+{
+    MApplication app(argc, argv);
+    MApplicationWindow window;
+    MainPage *mainPage;
+
+    // That's the data that will be displayed by our application.
+    // For the sake of keeping the example as simple as possible we use
+    // a very simplistic data structure.
+    QList<Artist *> artistsList;
+    fillOutData(artistsList);
+
+    mainPage = new MainPage(artistsList);
+
+    mainPage->appear(&window);
+    window.show();
+
+    return app.exec();
+}
+
+void fillOutData(QList<Artist *> &artistList)
+{
+    Artist *artist;
+    Album *album;
+
+    artist = new Artist;
+    artist->name = "The Beatles";
+
+    album = new Album;
+    album->title = "Sgt. Pepper's Lonely Hearts Club Band";
+    album->artist = "The Beatles";
+    album->coverArtFilename = "album_cover.jpg";
+    album->songs << "Sgt. Pepper's Lonely Hearts Club Band";
+    album->songs << "With a Little Help from My Friends";
+    album->songs << "Lucy in the Sky with Diamonds";
+    album->songs << "Getting Better";
+    album->songs << "Fixing a Hole";
+    album->songs << "She's Leaving Home";
+    album->songs << "Being for the Benefit of Mr. Kite!";
+    artist->albums << album;
+
+    album = new Album;
+    album->title = "Yellow Submarine";
+    album->artist = "The Beatles";
+    album->coverArtFilename = "album_cover.jpg";
+    album->songs << "Yellow Submarine";
+    album->songs << "Only a Northern Song";
+    album->songs << "All Together Now";
+    album->songs << "Hey Bulldog";
+    album->songs << "It's All Too Much";
+    album->songs << "All You Need Is Love";
+    artist->albums << album;
+
+    album = new Album;
+    album->title = "Abbey Road";
+    album->artist = "The Beatles";
+    album->coverArtFilename = "album_cover.jpg";
+    album->songs << "Come Together";
+    album->songs << "Something";
+    album->songs << "Maxwell's Silver Hammer";
+    album->songs << "Oh! Darling";
+    album->songs << "Octopus's Garden";
+    album->songs << "I Want You (She's So Heavy)";
+    artist->albums << album;
+
+    artistList << artist;
+
+
+
+    artist = new Artist;
+    artist->name = "Led Zeppelin";
+
+    album = new Album;
+    album->title = "Physical Graffiti";
+    album->artist = "Led Zeppelin";
+    album->coverArtFilename = "album_cover.jpg";
+    album->songs << "Custard Pie";
+    album->songs << "The Rover";
+    album->songs << "In My Time of Dying";
+    album->songs << "Houses of the Holy";
+    album->songs << "Trampled Under Foot";
+    album->songs << "Kashmir";
+    artist->albums << album;
+
+    album = new Album;
+    album->title = "Houses of the Holy";
+    album->artist = "Led Zeppelin";
+    album->coverArtFilename = "album_cover.jpg";
+    album->songs << "The Song Remains the Same";
+    album->songs << "The Rain Song";
+    album->songs << "Over the Hills and Far Away";
+    album->songs << "The Crunge";
+    album->songs << "Dancing Days";
+    album->songs << "D'yer Mak'er";
+    album->songs << "No Quarter";
+    album->songs << "The Ocean";
+    artist->albums << album;
+
+    album = new Album;
+    album->title = "Presence";
+    album->artist = "Led Zeppelin";
+    album->coverArtFilename = "album_cover.jpg";
+    album->songs << "Achilles Last Stand";
+    album->songs << "For Your Life";
+    album->songs << "Royal Orleans";
+    album->songs << "Nobody's Fault but Mine";
+    album->songs << "Candy Store Rock";
+    album->songs << "Hots On for Nowhere";
+    album->songs << "Tea for One";
+    artist->albums << album;
+
+    artistList << artist;
+}
diff --git a/examples/tutorial_music_catalogue/mainpage.cpp b/examples/tutorial_music_catalogue/mainpage.cpp
new file mode 100644
index 00000000..fbbeed4d
--- /dev/null
+++ b/examples/tutorial_music_catalogue/mainpage.cpp
@@ -0,0 +1,75 @@
+// mainpage.cpp
+#include "mainpage.h"
+
+#include <MButton>
+#include <MButtonGroup>
+#include <MLabel>
+#include <MSceneManager>
+#include <QGraphicsLinearLayout>
+
+#include "artistpage.h"
+
+MainPage::MainPage(QList<Artist *> artistsList, QGraphicsItem *parent)
+    : MApplicationPage(parent), artistsList(artistsList)
+{
+    // OBS: in a real application you shouldn't hardcode strings used
+    // in the GUI like that but use the translation system to fetch
+    // the correct, localised, string instead.
+    setTitle("Music Catalogue");
+}
+
+MainPage::~MainPage()
+{
+    qDeleteAll(artistsList);
+}
+
+// This is a virtual method that gets called only once by the framework,
+// right before your page begins to appear on the scene.
+void MainPage::createContent()
+{
+    // We want to organize our items in a single column. A vertical
+    // layout enables us to easily achieve this arrangement.
+    // Layout classes take care of setting the correct geometry (size and position)
+    // of the items added to it.
+    QGraphicsLinearLayout *layout = new QGraphicsLinearLayout(Qt::Vertical);
+    centralWidget()->setLayout(layout);
+
+    // Items in a vertical layout are arranged from top to bottom.
+    // Thus the label "Artists:" will come first, therefore serving
+    // the title of our list.
+    layout->addItem(new MLabel("Artists:"));
+
+    MButtonGroup *buttonGroup = new MButtonGroup(this);
+
+    Artist *artist;
+    MButton *artistButton;
+    for (int i = 0; i < artistsList.count(); i++) {
+        artist = artistsList[i];
+
+        artistButton = new MButton;
+        artistButton->setText(artist->name);
+
+        layout->addItem(artistButton);
+        buttonGroup->addButton(artistButton, i);
+    }
+
+    // A MButtonGroup is used because it provides a signal that is emitted
+    // whenever any of the buttons added to it gets clicked.
+    // MButtonGroup groups the buttons logically only. Their graphical
+    // positioning is still handled by the layout.
+    connect(buttonGroup, SIGNAL(buttonClicked(int)),
+            this, SLOT(displayArtist(int)));
+}
+
+void MainPage::displayArtist(int artistIndex)
+{
+    Artist *artist = artistsList[artistIndex];
+
+    ArtistPage *artistPage = new ArtistPage(artist);
+
+    // When the back button is pressed, the page gets dismissed.
+    // By setting MSceneWindow::DestroyWhenDismissed we don't have to
+    // keep tabs on this page since it will be automatically destroyed
+    // after the dismissal.
+    sceneManager()->appearSceneWindow(artistPage, MSceneWindow::DestroyWhenDismissed);
+}
diff --git a/examples/tutorial_music_catalogue/mainpage.h b/examples/tutorial_music_catalogue/mainpage.h
new file mode 100644
index 00000000..11a558e0
--- /dev/null
+++ b/examples/tutorial_music_catalogue/mainpage.h
@@ -0,0 +1,24 @@
+#ifndef MAINPAGE_H
+#define MAINPAGE_H
+
+#include <MApplicationPage>
+
+#include "data.h"
+
+class MainPage : public MApplicationPage {
+    Q_OBJECT
+public:
+    MainPage(QList<Artist *> artistsList, QGraphicsItem *parent = 0);
+    virtual ~MainPage();
+
+protected:
+    void createContent();
+
+private slots:
+    void displayArtist(int artistIndex);
+
+private:
+    QList<Artist *> artistsList;
+};
+
+#endif
diff --git a/examples/tutorial_music_catalogue/tutorial_music_catalogue.css b/examples/tutorial_music_catalogue/tutorial_music_catalogue.css
new file mode 100644
index 00000000..2b0a29fd
--- /dev/null
+++ b/examples/tutorial_music_catalogue/tutorial_music_catalogue.css
@@ -0,0 +1,7 @@
+MApplicationPageStyle.Landscape {
+    background-image: "music-catalogue-background-landscape"
+}
+
+MApplicationPageStyle.Portrait {
+    background-image: "music-catalogue-background-portrait"
+}
diff --git a/examples/tutorial_music_catalogue/tutorial_music_catalogue.pro b/examples/tutorial_music_catalogue/tutorial_music_catalogue.pro
new file mode 100644
index 00000000..e504eac1
--- /dev/null
+++ b/examples/tutorial_music_catalogue/tutorial_music_catalogue.pro
@@ -0,0 +1,9 @@
+TEMPLATE = app
+TARGET = 
+DEPENDPATH += .
+INCLUDEPATH += .
+CONFIG += meegotouch
+
+# Input
+HEADERS += albumpage.h data.h mainpage.h artistpage.h
+SOURCES += main.cpp mainpage.cpp artistpage.cpp albumpage.cpp
diff --git a/examples/tutorial_music_catalogue/tutorial_music_catalogue.svg b/examples/tutorial_music_catalogue/tutorial_music_catalogue.svg
new file mode 100644
index 00000000..9b9a5671
--- /dev/null
+++ b/examples/tutorial_music_catalogue/tutorial_music_catalogue.svg
@@ -0,0 +1,142 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="894.28564"
+   height="512.85718"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.47 r22583"
+   sodipodi:docname="tutorial_music_catalogue.svg">
+  <defs
+     id="defs4">
+    <linearGradient
+       id="linearGradient3590">
+      <stop
+         style="stop-color:#cfdaff;stop-opacity:1;"
+         offset="0"
+         id="stop3592" />
+      <stop
+         style="stop-color:#000280;stop-opacity:1;"
+         offset="1"
+         id="stop3594" />
+    </linearGradient>
+    <inkscape:perspective
+       sodipodi:type="inkscape:persp3d"
+       inkscape:vp_x="0 : 526.18109 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_z="744.09448 : 526.18109 : 1"
+       inkscape:persp3d-origin="372.04724 : 350.78739 : 1"
+       id="perspective10" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient3590"
+       id="linearGradient3642"
+       x1="65.714287"
+       y1="486.64789"
+       x2="577.14282"
+       y2="486.64789"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="translate(165.21934,-808.07647)" />
+    <inkscape:perspective
+       id="perspective2825"
+       inkscape:persp3d-origin="0.5 : 0.33333333 : 1"
+       inkscape:vp_z="1 : 0.5 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_x="0 : 0.5 : 1"
+       sodipodi:type="inkscape:persp3d" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient3590-5"
+       id="linearGradient3642-8"
+       x1="65.714287"
+       y1="486.64789"
+       x2="577.14282"
+       y2="486.64789"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="translate(165.21934,-808.07647)" />
+    <linearGradient
+       id="linearGradient3590-5">
+      <stop
+         style="stop-color:#ccffab;stop-opacity:1;"
+         offset="0"
+         id="stop3592-9" />
+      <stop
+         style="stop-color:#1d3900;stop-opacity:1;"
+         offset="1"
+         id="stop3594-7" />
+    </linearGradient>
+    <linearGradient
+       y2="486.64789"
+       x2="577.14282"
+       y1="486.64789"
+       x1="65.714287"
+       gradientTransform="translate(163.79076,-1313.7907)"
+       gradientUnits="userSpaceOnUse"
+       id="linearGradient2834"
+       xlink:href="#linearGradient3590-5"
+       inkscape:collect="always" />
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.35"
+     inkscape:cx="-234.28575"
+     inkscape:cy="210"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     inkscape:window-width="1348"
+     inkscape:window-height="756"
+     inkscape:window-x="104"
+     inkscape:window-y="321"
+     inkscape:window-maximized="0" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-127.14285,-229.50504)">
+    <rect
+       style="fill:url(#linearGradient3642);fill-opacity:1;stroke:none"
+       id="music-catalogue-background-landscape"
+       width="511.42856"
+       height="388.57144"
+       x="230.93362"
+       y="-515.71429"
+       inkscape:label="#rect2816"
+       transform="matrix(0,1,-1,0,0,0)" />
+    <rect
+       style="fill:url(#linearGradient2834);fill-opacity:1;stroke:none"
+       id="music-catalogue-background-portrait"
+       width="511.42856"
+       height="388.57144"
+       x="229.50504"
+       y="-1021.4285"
+       inkscape:label="#rect2816"
+       transform="matrix(0,1,-1,0,0,0)" />
+  </g>
+</svg>