New: MSceneWindow::appear(scene, policy);

RevBy: Dominik Kapusta
Details: Added to accompany the existing MSceneWindow::appear(window, policy);

10 files changed, 97 insertions, 18 deletions

diff --git a/doc/src/news.dox b/doc/src/news.dox
index 884ddb82..df1401be 100644
--- a/doc/src/news.dox
+++ b/doc/src/news.dox
@@ -5,6 +5,7 @@
 \subsection New
 
 - Updated \subpage rotation document.
+- MSceneWindow::appear(QGraphicsScene *scene, MSceneWindow::DeletionPolicy policy);
 
 \section v02032 0.20.32
 
diff --git a/examples/pagenavigation_drilldown/samplepage.cpp b/examples/pagenavigation_drilldown/samplepage.cpp
index 3469973d..13557b5f 100644
--- a/examples/pagenavigation_drilldown/samplepage.cpp
+++ b/examples/pagenavigation_drilldown/samplepage.cpp
@@ -25,5 +25,5 @@ SamplePage::SamplePage(int level) : MApplicationPage(0), level(level)
 void SamplePage::openNextPage()
 {
     SamplePage *nextPage = new SamplePage(level + 1);
-    sceneManager()->appearSceneWindow(nextPage, MSceneWindow::DestroyWhenDismissed);
+    nextPage->appear(scene(), MSceneWindow::DestroyWhenDismissed);
 }
diff --git a/examples/tutorial/tutorial_music_artistpage.cpp b/examples/tutorial/tutorial_music_artistpage.cpp
index 51af0bd6..2511838b 100644
--- a/examples/tutorial/tutorial_music_artistpage.cpp
+++ b/examples/tutorial/tutorial_music_artistpage.cpp
@@ -45,5 +45,5 @@ void ArtistPage::displayAlbum(int albumIndex)
     Album *album = artist->albums[albumIndex];
 
     AlbumPage *albumPage = new AlbumPage(album);
-    sceneManager()->appearSceneWindow(albumPage, MSceneWindow::DestroyWhenDismissed);
+    albumPage->appear(scene(), MSceneWindow::DestroyWhenDismissed);
 }
diff --git a/examples/tutorial/tutorial_music_mainpage.cpp b/examples/tutorial/tutorial_music_mainpage.cpp
index 05826722..b56a46c4 100644
--- a/examples/tutorial/tutorial_music_mainpage.cpp
+++ b/examples/tutorial/tutorial_music_mainpage.cpp
@@ -71,5 +71,5 @@ void MainPage::displayArtist(int artistIndex)
     // 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);
+    artistPage->appear(scene(), MSceneWindow::DestroyWhenDismissed);
 }
diff --git a/examples/tutorial_music_catalogue/artistpage.cpp b/examples/tutorial_music_catalogue/artistpage.cpp
index be4fa0c4..51f2cb79 100644
--- a/examples/tutorial_music_catalogue/artistpage.cpp
+++ b/examples/tutorial_music_catalogue/artistpage.cpp
@@ -44,5 +44,5 @@ void ArtistPage::displayAlbum(int albumIndex)
     Album *album = artist->albums[albumIndex];
 
     AlbumPage *albumPage = new AlbumPage(album);
-    sceneManager()->appearSceneWindow(albumPage, MSceneWindow::DestroyWhenDismissed);
+    albumPage->appear(scene(), MSceneWindow::DestroyWhenDismissed);
 }
diff --git a/examples/tutorial_music_catalogue/mainpage.cpp b/examples/tutorial_music_catalogue/mainpage.cpp
index fbbeed4d..a782de19 100644
--- a/examples/tutorial_music_catalogue/mainpage.cpp
+++ b/examples/tutorial_music_catalogue/mainpage.cpp
@@ -71,5 +71,5 @@ void MainPage::displayArtist(int artistIndex)
     // 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);
+    artistPage->appear(scene(), MSceneWindow::DestroyWhenDismissed);
 }
diff --git a/src/corelib/widgets/mscenewindow.cpp b/src/corelib/widgets/mscenewindow.cpp
index 9f52ab4e..c10e5728 100644
--- a/src/corelib/widgets/mscenewindow.cpp
+++ b/src/corelib/widgets/mscenewindow.cpp
@@ -146,30 +146,57 @@ MSceneWindow::SceneWindowState MSceneWindow::sceneWindowState() const
     return d->sceneWindowState;
 }
 
-void MSceneWindow::appear(MWindow *window, MSceneWindow::DeletionPolicy policy)
+void MSceneWindow::appear(QGraphicsScene *scene, MSceneWindow::DeletionPolicy policy)
 {
+    if (!scene) {
+        mWarning("MSceneWindow") << Q_FUNC_INFO << "NULL scene.";
+        return;
+    }
+
+    MScene *mScene = qobject_cast<MScene *>(scene);
+    if (!mScene || !mScene->sceneManager()) {
+        mWarning("MSceneWindow") << Q_FUNC_INFO << "scene has no scene manager.";
+        return;
+    }
+
     if (view()) {
         if (model()->disappearTimeout() != 0) {
             QTimer::singleShot(model()->disappearTimeout(), this, SLOT(disappear()));
         }
     }
 
+    mScene->sceneManager()->appearSceneWindow(this, policy);
+}
+
+void MSceneWindow::appear(MWindow *window, MSceneWindow::DeletionPolicy policy)
+{
     if (!window) {
+        // Remove this behavior along with the deprecated
+        // MSceneWindow::appear(DeletionPolicy);
         window = MApplication::activeWindow();
         if (!window) {
-            // TODO: Create and show() a M[Application]Window on the fly?
             mWarning("MSceneWindow")
                     << "Construct and show MWindow before showing a scene window";
             return;
         }
     }
 
-    window->sceneManager()->appearSceneWindow(this, policy);
+    // Force the creation of a scene manager (and scene) if none was
+    // set to this window yet.
+    //
+    // Therefore:
+    //    sceneWindow->appear(window);
+    // Will yield a different result than:
+    //    sceneWindow->appear(window->scene());
+    // If window didn't have a scene and scene manager.
+    window->sceneManager();
+
+    appear(window->scene(), policy);
 }
 
 void MSceneWindow::appear(MSceneWindow::DeletionPolicy policy)
 {
-    appear(0, policy);
+    appear((MWindow *)0, policy);
 }
 
 void MSceneWindow::disappear()
diff --git a/src/corelib/widgets/mscenewindow.h b/src/corelib/widgets/mscenewindow.h
index dd3b604d..fc07034e 100644
--- a/src/corelib/widgets/mscenewindow.h
+++ b/src/corelib/widgets/mscenewindow.h
@@ -165,17 +165,57 @@ public:
     virtual ~MSceneWindow();
 
 public Q_SLOTS:
+
     /*!
-     * Makes the scene window appear on \a window and registers it with the associated
-     * MSceneManager.
+     * \brief Makes the scene window appear on the given \a scene.
      *
-     * \param window    The window on which the scene window is going to be shown.
-     * \param policy    Deletion policy, defines the ownership for this window
+     * \param scene    The scene on which the scene window is going to appear.
+     * \param policy   Deletion policy. Defines whether this scene window should be
+     *                 automatically deleted when no longer used.
      *
-     * Ownership is transfered to window->scene().
+     * The scene window will be managed by the MSceneManager of the given \a scene.
+     * Since the appearance and disappearance of scene windows is handled by a scene manager,
+     * if \a scene has no scene manager this method won't have any effect.
+     *
+     * Ownership is transfered to \a scene.
+     *
+     * \note This is different from calling <code>scene->addItem(sceneWindow)</code>.
+     *
+     * Usage example:
+     * \code
+     * void AlbumPage::showSong(Song *song)
+     * {
+     *     MSceneWindow *songPage = new SongPage(song);
+     *     songPage->appear(scene(), MSceneWindow::DestroyWhenDismissed);
+     * }
+     * \endcode
      *
      * \sa MSceneManager::appearSceneWindow()
      */
+    void appear(QGraphicsScene *scene, MSceneWindow::DeletionPolicy policy = KeepWhenDone);
+
+    /*!
+     * \brief Makes the scene window appear on \a window.
+     *
+     * \param window    The window whose scene will receive the appearing scene window.
+     * \param policy    Deletion policy. Defines whether this scene window should be
+     *                  automatically deleted when no longer used.
+     *
+     * If \a window doesn't have a scene manager, one will be automatically created
+     * (along with a scene) and assigned to it.
+     *
+     * Ownership is transfered to window->scene().
+     *
+     * Usage example:
+     * \code
+     * MWindow *window = new SomeWindow;
+     * MSceneWindow *sceneWindow = new SomeSceneWindow;
+     * sceneWindow->appear(window);
+     * window->show();
+     * \endcode
+     *
+     * \sa appear(QGraphicsScene *, DeletionPolicy), MSceneManager::appearSceneWindow()
+     */
     virtual void appear(MWindow *window, MSceneWindow::DeletionPolicy policy = KeepWhenDone);
 
     /*!
@@ -188,12 +228,14 @@ public Q_SLOTS:
      * which MWindow happens to be active when this method is called. In such
      * scenarios use either appear(MWindow*) or MSceneManager::appearSceneWindow().
      *
-     * \param policy    Deletion policy, defines the ownership for this window
+     * \param policy    Deletion policy. Defines whether this scene window should be
+     *                  automatically deleted when no longer used.
      *
      * Ownership is transfered to the MScene visualized by the active MWindow
      * (MApplication::activeWindow()->scene()).
      *
-     * \sa MApplication::activeWindow(), MSceneManager::appearSceneWindow()
+     * \sa appear(QGraphicsScene*, DeletionPolicy), appear(MWindow*, DeletionPolicy),
+     *     MApplication::activeWindow(), MSceneManager::appearSceneWindow()
      */
     virtual void appear(MSceneWindow::DeletionPolicy policy = KeepWhenDone);
 
diff --git a/tests/ut_mscenewindow/ut_mscenewindow.cpp b/tests/ut_mscenewindow/ut_mscenewindow.cpp
index ec98481c..b60916a9 100644
--- a/tests/ut_mscenewindow/ut_mscenewindow.cpp
+++ b/tests/ut_mscenewindow/ut_mscenewindow.cpp
@@ -84,7 +84,7 @@ void Ut_MSceneWindow::testAccessors()
     QCOMPARE(m_subject->isManagedManually(), true);
 }
 
-void Ut_MSceneWindow::testAppear()
+void Ut_MSceneWindow::testAppearOnWindow()
 {
     m_subject->appear(window);
 
@@ -92,6 +92,14 @@ void Ut_MSceneWindow::testAppear()
     QVERIFY(m_subject->scene() == static_cast<QGraphicsScene *>(window->scene()));
 }
 
+void Ut_MSceneWindow::testAppearOnScene()
+{
+    m_subject->appear(window->scene());
+
+    QCOMPARE(m_subject->sceneManager(), window->sceneManager());
+    QVERIFY(m_subject->scene() == static_cast<QGraphicsScene *>(window->scene()));
+}
+
 /*
  * Appearing on a MWindow without a scene manager should just work.
  * Scene manager should be created on the fly.
diff --git a/tests/ut_mscenewindow/ut_mscenewindow.h b/tests/ut_mscenewindow/ut_mscenewindow.h
index 2e6408fe..a8d82223 100644
--- a/tests/ut_mscenewindow/ut_mscenewindow.h
+++ b/tests/ut_mscenewindow/ut_mscenewindow.h
@@ -39,7 +39,8 @@ private slots:
 
     void testAccessors();
 
-    void testAppear();
+    void testAppearOnWindow();
+    void testAppearOnScene();
     void testAppearWithoutSceneManager();
 
     void testDismiss();