Merge lp:~gerboland/unity-api/surfaceSizerCallback into lp:unity-api

[Gerry Boland]

AppMan: add surfaceAboutToBeCreatedCallback property to AppMan - allows QML shell override surface creation geometry

AppMan: add surfaceAboutToBeCreatedCallback property to AppMan - allows QML shell override surface creation geometry

 * Are there any related MPs required for this MP to build/function as expected? Please list.
https://code.launchpad.net/~gerboland/unity8/initialSurfaceGeometry/+merge/231726
https://code.launchpad.net/~gerboland/qtmir/initialSurfaceGeometry/+merge/231725
 * Did you perform an exploratory manual test run of your code change and any related functionality?
Y

[Gerry Boland (gerboland)]

<Saviq> greyback, wonder, could this not ba Q_PROPERTY?
Maybe it could, in which case the API would be prettier. I'll see if it works

[Michał Sawicz (saviq)]

review: Needs Fixing

[Michał Sawicz (saviq)]

Oh and document the signature of the callable please. Will it get info about fullscreen, for example?

I wonder if instead we should just pass availableGeometry, with Mir being responsible for policy, should we involve the shell like this?

review: Needs Information

[Gerry Boland (gerboland)]

> Oh and document the signature of the callable please. Will it get info about
> fullscreen, for example?
Sadly not, I need to add a feature request for Mir for that. IMO the surface type and other info that we get from a standard Mir surface would be good info to have, opposed to this limited subset.

> I wonder if instead we should just pass availableGeometry, with Mir being
> responsible for policy, should we involve the shell like this?
I dislike this idea, as effectively we'd need to educate Mir about the entire QML scene: which areas are off-limits for a non-fullscreen surfaces, what to do for surfaces of different types, stages, etc. Defining a vocabulary for that would be a nightmare IMO. And if Mir makes a decision that shell doesn't like, shell will immediately impose its will anyway - so where's the gain?

Policy I hope to define in Mir relate more to clients expectations, I want to ensure that client surfaces behave in a consistent way across mir server implementations. Shells should treat client surfaces in ways that they expect, that parent/child relationship is obeyed, focus handing is correct, input is delivered to the correct surface, siblings can attach to eachother/their parent and stay there, things like that.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:161
http://jenkins.qa.ubuntu.com/job/unity-api-ci/253/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-api-utopic-amd64-ci/88
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-api-utopic-armhf-ci/88
        deb: http://jenkins.qa.ubuntu.com/job/unity-api-utopic-armhf-ci/88/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-api-utopic-i386-ci/88

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/unity-api-ci/253/rebuild

review: Approve (continuous-integration)

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:162
http://jenkins.qa.ubuntu.com/job/unity-api-ci/256/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/unity-api-utopic-amd64-ci/91/console
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-api-utopic-armhf-ci/91
        deb: http://jenkins.qa.ubuntu.com/job/unity-api-utopic-armhf-ci/91/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-api-utopic-i386-ci/91

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/unity-api-ci/256/rebuild

review: Needs Fixing (continuous-integration)

[Michał Sawicz (saviq)]

> > I wonder if instead we should just pass availableGeometry, with Mir being
> > responsible for policy, should we involve the shell like this?
> I dislike this idea, as effectively we'd need to educate Mir about the entire
> QML scene: which areas are off-limits for a non-fullscreen surfaces, what to
> do for surfaces of different types, stages, etc. Defining a vocabulary for
> that would be a nightmare IMO. And if Mir makes a decision that shell doesn't
> like, shell will immediately impose its will anyway - so where's the gain?

I'm thinking about, for example, initial placement based on previous runs and such. Maybe Mir could (optionally?) give up a preferred position and the shell would come back with the same or changed if not possible in current setup or something. Anyway, later. The gain? More logic shared between Mir shells.

> Policy I hope to define in Mir relate more to clients expectations, I want to
> ensure that client surfaces behave in a consistent way across mir server
> implementations. Shells should treat client surfaces in ways that they expect,
> that parent/child relationship is obeyed, focus handing is correct, input is
> delivered to the correct surface, siblings can attach to eachother/their
> parent and stay there, things like that.

What you said above applies here just as well - shell, if not well behaved - can impose its own will.

[Michał Sawicz (saviq)]

review: Needs Information

[Gerry Boland (gerboland)]

> I'm thinking about, for example, initial placement based on previous runs and
> such. Maybe Mir could (optionally?) give up a preferred position and the shell
> would come back with the same or changed if not possible in current setup or
> something. Anyway, later. The gain? More logic shared between Mir shells.

Yeah definitely, that's something Mir can give us, including saving the positions on close so it can inform us where it should re-open.

> > Policy I hope to define in Mir relate more to clients expectations, I want
> to
> > ensure that client surfaces behave in a consistent way across mir server
> > implementations. Shells should treat client surfaces in ways that they
> expect,
> > that parent/child relationship is obeyed, focus handing is correct, input is
> > delivered to the correct surface, siblings can attach to eachother/their
> > parent and stay there, things like that.
>
> What you said above applies here just as well - shell, if not well behaved -
> can impose its own will.

Sure. It's a line we have to walk carefully, but I think it's more important to try guarantee behaviour for clients. Mir can define that policy, and look after surface position/size save/restore, but I don't want to go down the road of trying to educate Mir of everything happening in the QML scene.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:163
http://jenkins.qa.ubuntu.com/job/unity-api-ci/257/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-api-utopic-amd64-ci/92
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-api-utopic-armhf-ci/92
        deb: http://jenkins.qa.ubuntu.com/job/unity-api-utopic-armhf-ci/92/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-api-utopic-i386-ci/92

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/unity-api-ci/257/rebuild

review: Approve (continuous-integration)

[Michał Sawicz (saviq)]

> I tried:
>
> Binding {
> target: ApplicationManager
> property: "surfaceAboutToBeCreatedCallback"
> value: function surfaceSizer(surface) { print("Hihi")
> surface.width = 400;
> if (surface.appId && surface.appId == "dialer-app") {
> surface.height = 300;
> }
> return surface;
> }
> }
>
> and got this error:
> file:///usr/share/unity8/Stages/PhoneStage.qml:125:12: Unable to assign a function to a property of any type other than var.

Hah! Interesting. Can't say I understand. If Binding.value is of type
other than var, how can it be flexible enough? Otherwise if
ApplicationManager.surfaceAboutToBeCreatedCallback is not var, how would
your original approach to assign instead of bind work in any case?

I'd say that's worth a QTBUG.

[Gerry Boland (gerboland)]

> > I tried:
> >
> > Binding {
> > target: ApplicationManager
> > property: "surfaceAboutToBeCreatedCallback"
> > value: function surfaceSizer(surface) { print("Hihi")
> > surface.width = 400;
> > if (surface.appId && surface.appId == "dialer-app") {
> > surface.height = 300;
> > }
> > return surface;
> > }
> > }
> >
> > and got this error:
> > file:///usr/share/unity8/Stages/PhoneStage.qml:125:12: Unable to assign a
> function to a property of any type other than var.
>
> Hah! Interesting. Can't say I understand. If Binding.value is of type
> other than var, how can it be flexible enough? Otherwise if
> ApplicationManager.surfaceAboutToBeCreatedCallback is not var, how would
> your original approach to assign instead of bind work in any case?
>
> I'd say that's worth a QTBUG.

My guess is that Binding does some naive type checking, and QJSValue is indeed not a QVariant. qtdeclarative5:/src/qml/qml/qmlproperty.cpp does confirm that idea: http://pastebin.ubuntu.com/8099923/ - I don't understand why exactly..

I don't create a binding with my original approach, it's a simple assignment. I would guess the only way around this error is to replace QJSValue with a QVariant. What say you?

[Michał Sawicz (saviq)]

> My guess is that Binding does some naive type checking, and QJSValue is indeed not a QVariant. qtdeclarative5:/src/qml/qml/qmlproperty.cpp does confirm that idea:http://pastebin.ubuntu.com/8099923/ - I don't understand why exactly..

Yeah.

> I don't create a binding with my original approach, it's a simple assignment. I would guess the only way around this error is to replace QJSValue with a QVariant. What say you?

Doesn't sound like that would help, since you'd still need to go through
a Binding and that would complain that function is not a var.

So it looks like assignment is the only way indeed. Worth a QTBUG IMO.
If you can assign something to a property, you should be able to bind to.

[Michał Sawicz (saviq)]

Please rebase on lp:~dandrader/unity-api/lifecycle, no need to bump versions over that one then.

review: Needs Fixing

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:165
http://jenkins.qa.ubuntu.com/job/unity-api-ci/258/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-api-utopic-amd64-ci/93
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-api-utopic-armhf-ci/93
        deb: http://jenkins.qa.ubuntu.com/job/unity-api-utopic-armhf-ci/93/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-api-utopic-i386-ci/93

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/unity-api-ci/258/rebuild

review: Approve (continuous-integration)

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:166
http://jenkins.qa.ubuntu.com/job/unity-api-ci/259/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-api-utopic-amd64-ci/94
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-api-utopic-armhf-ci/94
        deb: http://jenkins.qa.ubuntu.com/job/unity-api-utopic-armhf-ci/94/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-api-utopic-i386-ci/94

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/unity-api-ci/259/rebuild

review: Approve (continuous-integration)

[Michał Sawicz (saviq)]

Oh yes!

review: Approve

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:170
http://jenkins.qa.ubuntu.com/job/unity-api-ci/283/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-api-vivid-amd64-ci/3
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-api-vivid-armhf-ci/3
        deb: http://jenkins.qa.ubuntu.com/job/unity-api-vivid-armhf-ci/3/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-api-vivid-i386-ci/3

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/unity-api-ci/283/rebuild

review: Approve (continuous-integration)

[Albert Astals Cid (aacid)]

Code looks good, haven't time to test. If nobody beats me to it, i'll do on Monday

review: Approve (code)

[Albert Astals Cid (aacid)]

Let's wait for https://code.launchpad.net/~gerboland/unity8/initialSurfaceGeometry/+merge/231726 to be finished so we can try it all together

[lp:~gerboland/unity-api/surfaceSizerCallback]

171. By Gerry Boland on 2015-03-24

Merge trunk

172. By Gerry Boland on 2015-03-31

Add unity::shell::application::Globals

173. By Gerry Boland on 2015-07-13

Merge trunk

174. By Gerry Boland on 2015-07-13

Merge app-focus-state branch as prereq

175. By Gerry Boland on 2015-07-13

Document the Global class

176. By Gerry Boland on 2015-07-13

Revert 175

177. By Gerry Boland on 2015-07-13

Remove old Globals idea

178. By Gerry Boland on 2015-07-29

Merge trunk

179. By Gerry Boland on 2015-09-03

Merge trunk

180. By Gerry Boland on 2015-09-07

Remove bad merge atrifacts

Unmerged revisions

180. By Gerry Boland on 2015-09-07

Remove bad merge atrifacts

179. By Gerry Boland on 2015-09-03

Merge trunk

178. By Gerry Boland on 2015-07-29

Merge trunk

177. By Gerry Boland on 2015-07-13

Remove old Globals idea

176. By Gerry Boland on 2015-07-13

Revert 175

175. By Gerry Boland on 2015-07-13

Document the Global class

174. By Gerry Boland on 2015-07-13

Merge app-focus-state branch as prereq

173. By Gerry Boland on 2015-07-13

Merge trunk

172. By Gerry Boland on 2015-03-31

Add unity::shell::application::Globals

171. By Gerry Boland on 2015-03-24

Merge trunk

=== modified file 'debian/changelog'
--- debian/changelog	2015-08-26 08:59:22 +0000
+++ debian/changelog	2015-09-07 14:10:05 +0000
@@ -1,3 +1,4 @@
+<<<<<<< TREE
 unity-api (7.99+15.10.20150826-0ubuntu1) wily; urgency=medium
 
   [ Pawel Stolowski ]
@@ -9,6 +10,25 @@
  -- CI Train Bot <[e-mail]>  Wed, 26 Aug 2015 08:59:21 +0000
 
 unity-api (7.99+15.10.20150804-0ubuntu1) wily; urgency=medium
+=======
+unity-api (7.100+15.04.20150827-0ubuntu1) vivid; urgency=medium
+
+  [ Daniel d'Andrada ]
+  * Added MirSurface and MirSurfaceItem interfaces
+
+  [ CI Train Bot ]
+  * No-change rebuild.
+
+ -- CI Train Bot <[e-mail]>  Thu, 27 Aug 2015 08:50:45 +0000
+
+unity-api (7.99+15.04.20150811-0ubuntu1) vivid; urgency=medium
+
+  * New rebuild forced.
+
+ -- CI Train Bot <[e-mail]>  Tue, 11 Aug 2015 14:05:55 +0000
+
+unity-api (7.99+15.04.20150804-0ubuntu1) vivid; urgency=medium
+>>>>>>> MERGE-SOURCE
 
   [ Daniel d'Andrada ]
   * Remove ApplicationManagerInterface.forceDashActive
@@ -18,13 +38,33 @@
 
  -- CI Train Bot <[e-mail]>  Tue, 04 Aug 2015 15:26:16 +0000
 
-unity-api (7.98+15.10.20150724-0ubuntu1) wily; urgency=medium
+unity-api (7.99-0ubuntu1) UNRELEASED; urgency=medium
+
+  * Changes to activate and preview methods of ScopeInterface.
+
+ -- Pawel Stolowski <[e-mail]>  Mon, 03 Aug 2015 14:03:47 +0000
+
+unity-api (7.99) UNRELEASED; urgency=medium
+
+  * Add surface sizer callback property to AppMan API
+
+ -- Gerry Boland <[e-mail]>  Mon, 13 July 2015 13:47:07 +0000
+
+unity-api (7.98+15.04.20150724-0ubuntu1) vivid; urgency=medium
 
   [ Mirco Müller (MacSlow) ]
   * added alerting/setAlerting API to LauncherModel and LauncherItem interfaces
 
  -- CI Train Bot <[e-mail]>  Fri, 24 Jul 2015 09:53:01 +0000
 
+unity-api (7.98) UNRELEASED; urgency=medium
+
+  * Remove ApplicationManagerInterface.forceDashActive
+  * Remove ApplicationManagerInterface.suspended
+  * Add ApplicationInfoInterface.requestedState
+
+ -- Daniel d'Andrada <[e-mail]>  Mon, 15 Jun 2015 13:53:07 -0300
+
 unity-api (7.97+15.10.20150721-0ubuntu1) wily; urgency=medium
 
   [ Michi Henning ]
 
=== modified file 'include/unity/shell/application/ApplicationManagerInterface.h'
--- include/unity/shell/application/ApplicationManagerInterface.h	2015-06-19 12:02:05 +0000
+++ include/unity/shell/application/ApplicationManagerInterface.h	2015-09-07 14:10:05 +0000
@@ -24,6 +24,7 @@
 
 #include <QtCore/QObject>
 #include <QtCore/QAbstractListModel>
+#include <QtQml/QJSValue>
 
 namespace unity
 {
@@ -59,6 +60,36 @@
      */
     Q_PROPERTY(QString focusedApplicationId READ focusedApplicationId NOTIFY focusedApplicationIdChanged)
 
+    /**
+     * @brief Register a Javascript function as a callback for when an application is asking to create a new surface
+     *
+     * Registers a Javascript callback function which ApplicationManager will call when an application is asking
+     * Mir to create a new surface. The function is passed a 'surface' object with properties width, height and
+     * appId. The shell can implement this function to return different width & height to override the geometry
+     * requested by the client.
+     *
+     * Example QML:
+     *
+     * function surfaceSizer(surface) {
+     *     surface.width = 400;
+     *     if (surface.appId && surface.appId == "dialer-app") {
+     *         surface.height = 300;
+     *     }
+     *     return surface;
+     * }
+     *
+     * Component.onCompleted {
+     *     ApplicationManager.surfaceAboutToBeCreatedCallback = surfaceSizer;
+     * }
+     * Component.onDestruction {
+     *     ApplicationManager.surfaceAboutToBeCreatedCallback = null;
+     * }
+     *
+     * Warning: the function must live in the QML context thread!
+     */
+    Q_PROPERTY(QJSValue surfaceAboutToBeCreatedCallback READ surfaceAboutToBeCreatedCallback
+               WRITE setSurfaceAboutToBeCreatedCallback NOTIFY surfaceAboutToBeCreatedCallbackChanged)
+
 protected:
     /// @cond
     ApplicationManagerInterface(QObject* parent = 0): QAbstractListModel(parent)
@@ -108,6 +139,9 @@
 
     virtual QString focusedApplicationId() const = 0;
 
+    virtual QJSValue surfaceAboutToBeCreatedCallback() const = 0;
+    virtual void setSurfaceAboutToBeCreatedCallback(const QJSValue &callback) = 0;
+
     /// @endcond
 
     /**
@@ -177,6 +211,7 @@
 Q_SIGNALS:
     /// @cond
     void countChanged();
+    void surfaceAboutToBeCreatedCallbackChanged();
     /// @endcond
 
     /**
 
=== modified file 'include/unity/shell/application/CMakeLists.txt'
--- include/unity/shell/application/CMakeLists.txt	2015-06-19 12:02:05 +0000
+++ include/unity/shell/application/CMakeLists.txt	2015-09-07 14:10:05 +0000
@@ -7,10 +7,10 @@
 
 set(UNITY_API_LIB_HDRS ${UNITY_API_LIB_HDRS} ${headers} ${internal_headers} PARENT_SCOPE)
 
-set(VERSION 7)
+set(VERSION 8)
 set(PKGCONFIG_NAME "unity-shell-application")
 set(PKGCONFIG_DESCRIPTION "Unity shell Application APIs")
-set(PKGCONFIG_REQUIRES "Qt5Core")
+set(PKGCONFIG_REQUIRES "Qt5Core Qt5Qml")
 set(PKGCONFIG_FILE unity-shell-application.pc)
 
 configure_file(${CMAKE_SOURCE_DIR}/data/unity-shell-api.pc.in
 
=== added file 'include/unity/shell/application/Mir.h'
--- include/unity/shell/application/Mir.h	1970-01-01 00:00:00 +0000
+++ include/unity/shell/application/Mir.h	2015-09-07 14:10:05 +0000
@@ -0,0 +1,76 @@
+/*
+ * Copyright (C) 2015 Canonical, Ltd.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; version 3.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef UNITY_SHELL_APPLICATION_MIR_H
+#define UNITY_SHELL_APPLICATION_MIR_H
+
+#include <QObject>
+
+/**
+    @brief Acting as a namespace to hold enums and such for use in QML
+ */
+class Mir
+{
+    Q_GADGET
+    Q_ENUMS(Type)
+    Q_ENUMS(State)
+    Q_ENUMS(OrientationAngle)
+
+public:
+    /**
+        @brief Surface type
+     */
+    enum Type {
+        UnknownType,
+        NormalType,
+        UtilityType,
+        DialogType,
+        GlossType,
+        FreeStyleType,
+        MenuType,
+        InputMethodType,
+        SatelliteType,
+        TipType,
+    };
+
+    /**
+        @brief Surface state
+     */
+    enum State {
+        UnknownState,
+        RestoredState,
+        MinimizedState,
+        MaximizedState,
+        VertMaximizedState,
+        FullscreenState,
+        HorizMaximizedState,
+        HiddenState,
+    };
+
+    /**
+        @brief Surface orientation angle
+     */
+    enum OrientationAngle {
+        Angle0 = 0,
+        Angle90 = 90,
+        Angle180 = 180,
+        Angle270 = 270
+    };
+};
+
+Q_DECLARE_METATYPE(Mir::OrientationAngle)
+
+#endif // UNITY_SHELL_APPLICATION_MIR_H
 
=== added file 'include/unity/shell/application/MirSurfaceInterface.h'
--- include/unity/shell/application/MirSurfaceInterface.h	1970-01-01 00:00:00 +0000
+++ include/unity/shell/application/MirSurfaceInterface.h	2015-09-07 14:10:05 +0000
@@ -0,0 +1,114 @@
+/*
+ * Copyright (C) 2015 Canonical, Ltd.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; version 3.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef UNITY_SHELL_APPLICATION_MIRSURFACE_H
+#define UNITY_SHELL_APPLICATION_MIRSURFACE_H
+
+#include <QObject>
+#include <QSize>
+
+#include "Mir.h"
+
+namespace unity
+{
+namespace shell
+{
+namespace application
+{
+
+/**
+   @brief Holds a Mir surface. Pretty much an opaque class.
+
+   All surface manipulation is done by giving it to a MirSurfaceItem and then
+   using MirSurfaceItem's properties.
+ */
+class MirSurfaceInterface : public QObject
+{
+    Q_OBJECT
+
+    /**
+     * @brief The surface type
+     */
+    Q_PROPERTY(Mir::Type type READ type NOTIFY typeChanged)
+
+    /**
+     * @brief Name of the surface, given by the client application
+     */
+    Q_PROPERTY(QString name READ name CONSTANT)
+
+    /**
+     * @brief Size of the current surface buffer, in pixels.
+     */
+    Q_PROPERTY(QSize size READ size NOTIFY sizeChanged)
+
+    /**
+     * @brief State of the surface
+     */
+    Q_PROPERTY(Mir::State state READ state WRITE setState NOTIFY stateChanged)
+
+    /**
+     * @brief True if it has a mir client bound to it.
+     * A "zombie" (live == false) surface never becomes alive again.
+     */
+    Q_PROPERTY(bool live READ live NOTIFY liveChanged)
+
+    /**
+     * @brief Orientation angle of the surface
+     *
+     * How many degrees, clockwise, the UI in the surface has to rotate to match shell's UI orientation
+     */
+    Q_PROPERTY(Mir::OrientationAngle orientationAngle READ orientationAngle WRITE setOrientationAngle
+               NOTIFY orientationAngleChanged DESIGNABLE false)
+
+public:
+    /// @cond
+    MirSurfaceInterface(QObject *parent = nullptr) : QObject(parent) {}
+    virtual ~MirSurfaceInterface() {}
+
+    virtual Mir::Type type() const = 0;
+
+    virtual QString name() const = 0;
+
+    virtual QSize size() const = 0;
+    virtual void resize(int width, int height) = 0;
+    virtual void resize(const QSize &size) = 0;
+
+    virtual Mir::State state() const = 0;
+    virtual void setState(Mir::State qmlState) = 0;
+
+    virtual bool live() const = 0;
+
+    virtual Mir::OrientationAngle orientationAngle() const = 0;
+    virtual void setOrientationAngle(Mir::OrientationAngle angle) = 0;
+    /// @endcond
+
+Q_SIGNALS:
+    /// @cond
+    void typeChanged(Mir::Type value);
+    void liveChanged(bool value);
+    void stateChanged(Mir::State value);
+    void orientationAngleChanged(Mir::OrientationAngle value);
+    void sizeChanged(const QSize &value);
+    /// @endcond
+};
+
+} // namespace application
+} // namespace shell
+} // namespace unity
+
+Q_DECLARE_METATYPE(unity::shell::application::MirSurfaceInterface*)
+
+#endif // UNITY_SHELL_APPLICATION_MIRSURFACE_H
 
=== added file 'include/unity/shell/application/MirSurfaceItemInterface.h'
--- include/unity/shell/application/MirSurfaceItemInterface.h	1970-01-01 00:00:00 +0000
+++ include/unity/shell/application/MirSurfaceItemInterface.h	2015-09-07 14:10:05 +0000
@@ -0,0 +1,151 @@
+/*
+ * Copyright (C) 2015 Canonical, Ltd.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; version 3.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef UNITY_SHELL_APPLICATION_MIRSURFACEITEM_H
+#define UNITY_SHELL_APPLICATION_MIRSURFACEITEM_H
+
+#include "Mir.h"
+
+#include <QQuickItem>
+
+namespace unity
+{
+namespace shell
+{
+namespace application
+{
+
+class MirSurfaceInterface;
+
+/**
+   @brief Renders a MirSurface in a QML scene and forwards the input events it receives to it.
+
+   You can have multiple MirSurfaceItems displaying the same MirSurface. But care must
+   be taken that only one of them feeds the MirSurface with input events and also only
+   one resizes it.
+ */
+class MirSurfaceItemInterface : public QQuickItem
+{
+    Q_OBJECT
+
+    /**
+     * @brief The surface to be displayed
+     */
+    Q_PROPERTY(unity::shell::application::MirSurfaceInterface* surface READ surface WRITE setSurface NOTIFY surfaceChanged)
+
+    /**
+     * @brief Type of the given surface or Mir.UnknownType if no surface is set
+     */
+    Q_PROPERTY(Mir::Type type READ type NOTIFY typeChanged)
+
+    /**
+     * @brief State of the given surface or Mir.UnknownState if no surface is set
+     */
+    Q_PROPERTY(Mir::State surfaceState READ surfaceState WRITE setSurfaceState NOTIFY surfaceStateChanged)
+
+    /**
+     * @brief Name of the given surface or an empty string if no surface is set
+     */
+    Q_PROPERTY(QString name READ name CONSTANT)
+
+    /**
+     * @brief True if the item has a surface and that surface has a mir client bound to it.
+     * A "zombie" (live == false) surface never becomes alive again.
+     */
+    Q_PROPERTY(bool live READ live NOTIFY liveChanged)
+
+    /**
+     * @brief  Orientation angle of the given surface
+     *
+     * How many degrees, clockwise, the UI in the surface has to rotate to match shell's UI orientation
+     */
+    Q_PROPERTY(Mir::OrientationAngle orientationAngle READ orientationAngle WRITE setOrientationAngle
+               NOTIFY orientationAngleChanged DESIGNABLE false)
+
+
+    /**
+     * @brief Whether the item will forward activeFocus, touch events, mouse events and key events to its surface.
+     * It's false by default.
+     * Only one item should have this property enabled for a given surface.
+     */
+    Q_PROPERTY(bool consumesInput READ consumesInput
+                                  WRITE setConsumesInput
+                                  NOTIFY consumesInputChanged)
+
+    /**
+     * @brief The desired width for the contained MirSurface.
+     * It's ignored if set to zero or a negative number
+     * The default value is zero
+     */
+    Q_PROPERTY(int surfaceWidth READ surfaceWidth
+                                WRITE setSurfaceWidth
+                                NOTIFY surfaceWidthChanged)
+
+    /**
+     * @brief The desired height for the contained MirSurface.
+     * It's ignored if set to zero or a negative number
+     * The default value is zero
+     */
+    Q_PROPERTY(int surfaceHeight READ surfaceHeight
+                                WRITE setSurfaceHeight
+                                NOTIFY surfaceHeightChanged)
+
+public:
+    /// @cond
+    MirSurfaceItemInterface(QQuickItem *parent = 0) : QQuickItem(parent) {}
+    virtual ~MirSurfaceItemInterface() {}
+
+    virtual Mir::Type type() const = 0;
+    virtual QString name() const = 0;
+    virtual bool live() const = 0;
+
+    virtual Mir::State surfaceState() const = 0;
+    virtual void setSurfaceState(Mir::State) = 0;
+
+    virtual Mir::OrientationAngle orientationAngle() const = 0;
+    virtual void setOrientationAngle(Mir::OrientationAngle angle) = 0;
+
+    virtual MirSurfaceInterface* surface() const = 0;
+    virtual void setSurface(MirSurfaceInterface*) = 0;
+
+    virtual bool consumesInput() const = 0;
+    virtual void setConsumesInput(bool value) = 0;
+
+    virtual int surfaceWidth() const = 0;
+    virtual void setSurfaceWidth(int value) = 0;
+
+    virtual int surfaceHeight() const = 0;
+    virtual void setSurfaceHeight(int value) = 0;
+    /// @endcond
+
+Q_SIGNALS:
+    /// @cond
+    void typeChanged(Mir::Type);
+    void surfaceStateChanged(Mir::State);
+    void liveChanged(bool live);
+    void orientationAngleChanged(Mir::OrientationAngle angle);
+    void surfaceChanged(MirSurfaceInterface*);
+    void consumesInputChanged(bool value);
+    void surfaceWidthChanged(int value);
+    void surfaceHeightChanged(int value);
+    /// @endcond
+};
+
+} // namespace application
+} // namespace shell
+} // namespace unity
+
+#endif // UNITY_SHELL_APPLICATION_MIRSURFACEITEM_H
 
=== modified file 'test/qmltest/mocks/plugins/Unity/Application/CMakeLists.txt'
--- test/qmltest/mocks/plugins/Unity/Application/CMakeLists.txt	2014-09-03 22:59:26 +0000
+++ test/qmltest/mocks/plugins/Unity/Application/CMakeLists.txt	2015-09-07 14:10:05 +0000
@@ -20,7 +20,7 @@
 
 add_library(ApplicationMocks SHARED ${ApplicationMocks_SOURCES})
 
-qt5_use_modules(ApplicationMocks Core Gui)
+qt5_use_modules(ApplicationMocks Core Gui Qml)
 
 set(TestApplicationPlugin_SOURCES
     TestApplicationPlugin.cpp
 
=== modified file 'test/qmltest/mocks/plugins/Unity/Application/Mocks/MockApplicationManager.cpp'
--- test/qmltest/mocks/plugins/Unity/Application/Mocks/MockApplicationManager.cpp	2015-06-19 12:02:05 +0000
+++ test/qmltest/mocks/plugins/Unity/Application/Mocks/MockApplicationManager.cpp	2015-09-07 14:10:05 +0000
@@ -22,7 +22,9 @@
 
 using namespace unity::shell::application;
 
-MockApplicationManager::MockApplicationManager(QObject* parent): ApplicationManagerInterface(parent)
+MockApplicationManager::MockApplicationManager(QObject* parent)
+    : ApplicationManagerInterface(parent)
+    , m_surfaceAboutToBeCreatedCallback(QJSValue::UndefinedValue)
 {
     MockApplicationInfo *item = new MockApplicationInfo("phone-app", "Phone App", "Telephony application", QUrl("/usr/share/pixmaps/some/icon.png"), this);
     m_list.append(item);
@@ -126,3 +128,17 @@
     Q_UNUSED(appId)
     return true;
 }
+
+QJSValue MockApplicationManager::surfaceAboutToBeCreatedCallback() const
+{
+    return m_surfaceAboutToBeCreatedCallback;
+}
+
+void MockApplicationManager::setSurfaceAboutToBeCreatedCallback(const QJSValue &callback)
+{
+    if (m_surfaceAboutToBeCreatedCallback.equals(callback))
+        return;
+
+    m_surfaceAboutToBeCreatedCallback = callback;
+    Q_EMIT surfaceAboutToBeCreatedCallbackChanged();
+}
 
=== modified file 'test/qmltest/mocks/plugins/Unity/Application/Mocks/MockApplicationManager.h'
--- test/qmltest/mocks/plugins/Unity/Application/Mocks/MockApplicationManager.h	2015-06-19 12:02:05 +0000
+++ test/qmltest/mocks/plugins/Unity/Application/Mocks/MockApplicationManager.h	2015-09-07 14:10:05 +0000
@@ -40,6 +40,9 @@
 
     QString focusedApplicationId() const;
 
+    QJSValue surfaceAboutToBeCreatedCallback() const;
+    void setSurfaceAboutToBeCreatedCallback(const QJSValue &callback);
+
     Q_INVOKABLE unity::shell::application::ApplicationInfoInterface *get(const int index) const;
 
     Q_INVOKABLE unity::shell::application::ApplicationInfoInterface *findApplication(const QString &appId) const;
@@ -56,6 +59,7 @@
 
 private:
     QList<MockApplicationInfo*> m_list;
+    QJSValue m_surfaceAboutToBeCreatedCallback;
 };
 
 #endif // MOCKAPPLICATIONMANAGER_H
 
=== modified file 'test/qmltest/mocks/plugins/Unity/Launcher/CMakeLists.txt'
--- test/qmltest/mocks/plugins/Unity/Launcher/CMakeLists.txt	2014-09-03 22:59:26 +0000
+++ test/qmltest/mocks/plugins/Unity/Launcher/CMakeLists.txt	2015-09-07 14:10:05 +0000
@@ -27,7 +27,7 @@
 
 add_library(LauncherMocks SHARED ${LauncherMocks_SOURCES})
 
-qt5_use_modules(LauncherMocks Core Gui)
+qt5_use_modules(LauncherMocks Core Gui Qml)
 
 set(TestLauncherPlugin_SOURCES
     TestLauncherPlugin.cpp
 
=== modified file 'test/qmltest/unity/shell/application/tst_Application.qml'
--- test/qmltest/unity/shell/application/tst_Application.qml	2015-06-19 12:02:05 +0000
+++ test/qmltest/unity/shell/application/tst_Application.qml	2015-09-07 14:10:05 +0000
@@ -59,6 +59,11 @@
             }
         }
 
+        function initTestCase() {
+            function surfaceSizer(surface) { return surface; }
+            ApplicationManager.surfaceAboutToBeCreatedCallback = surfaceSizer;
+        }
+
         /* make sure all the required roles are exposed on ApplicationManager */
         function test_model_roles_enum_data() {
             return [
@@ -124,6 +129,7 @@
             return [
                 { tag: "ApplicationManager.count", property: "count", type: "number" },
                 { tag: "ApplicationManager.focusedApplicationId", property: "focusedApplicationId", type: "string" },
+                { tag: "ApplicationManager.surfaceAboutToBeCreatedCallback", property: "surfaceAboutToBeCreatedCallback", type: "function" },
             ];
         }