Merge lp:~alan-griffiths/miral/workspaces into lp:miral

[Alan Griffiths]

[libmiral] Support for shells implementing workspaces

[lp:~alan-griffiths/miral/workspaces]

536. By Alan Griffiths on 2017-02-13

merge :parent

537. By Alan Griffiths on 2017-02-14

merge :parent

538. By Alan Griffiths on 2017-02-14

Tidy up code

539. By Alan Griffiths on 2017-02-15

Backport fixes from workspaces-example branch

540. By Alan Griffiths on 2017-02-15

merge lp:miral

541. By Alan Griffiths on 2017-02-15

merge lp:~alan-griffiths/miral/1.2

542. By Alan Griffiths on 2017-02-15

Housekeeping for 1.3 release

Unmerged revisions

=== modified file 'CMakeLists.txt'
--- CMakeLists.txt	2017-02-02 17:30:41 +0000
+++ CMakeLists.txt	2017-02-15 17:24:17 +0000
@@ -41,7 +41,7 @@
 include_directories(include SYSTEM ${MIRCLIENT_INCLUDE_DIRS})
 
 set(MIRAL_VERSION_MAJOR 1)
-set(MIRAL_VERSION_MINOR 2)
+set(MIRAL_VERSION_MINOR 3)
 set(MIRAL_VERSION_PATCH 0)
 
 set(MIRAL_VERSION ${MIRAL_VERSION_MAJOR}.${MIRAL_VERSION_MINOR}.${MIRAL_VERSION_PATCH})

=== modified file 'debian/changelog'
--- debian/changelog	2017-02-14 14:04:39 +0000
+++ debian/changelog	2017-02-15 17:24:17 +0000
@@ -1,6 +1,36 @@
+miral (1.3.0) UNRELEASED; urgency=medium
+
+  * New upstream release 1.3.0 (https://launchpad.net/miral/+milestone/1.3)
+
+    - ABI summary:
+      . miral ABI unchanged at 2
+    - Enhancements:
+      . Support for workspaces
+    - Bugs fixed:
+
+ -- Alan Griffiths <[e-mail]>  Thu, 02 Feb 2017 17:26:54 +0000
+
 miral (1.2.0) UNRELEASED; urgency=medium
 
-  * 
+  * New upstream release 1.2.0 (https://launchpad.net/miral/+milestone/1.2)
+
+    - ABI summary:
+      . miral ABI unchanged at 2
+    - Enhancements:
+      . New libmirclientcpp-dev package "C++ wrapper for libmirclient". (Split
+        from libmiral-dev)
+      . Give miral-app and miral-desktop a good default for -bindir
+      . More surface to window renaming to reflect Mir name changes
+      . Refresh the "Building and Using MirAL" doc
+    - Bugs fixed:
+      . Chrome-less shell hint does not work any more (LP: #1658117)
+      . WindowSpec::set_state() wrapper for mir_window_spec_set_state()
+        (LP: #1661256)
+      . "$ miral-app -kiosk" fails with "Unknown command line options: 
+        --desktop_file_hint=miral-shell.desktop" (LP: #1660933)
+      . libmiral] Fix focus and movement rules for Input Method and Satellite
+         windows. (LP: #1660691)
+      
 
  -- Alan Griffiths <[e-mail]>  Thu, 02 Feb 2017 17:26:54 +0000
 
@@ -15,13 +45,10 @@
         enums.
       . Logging of exceptions added to --window-management-trace
       . Rename WindowManagementPolicy::place_new_surface => place_new_window"
-      . New libmirclientcpp-dev package "C++ wrapper for libmirclient". (Split
-        from libmiral-dev)
     - Bugs fixed:
       . top-level window is not raised along with its child (LP: #1658085)
       . miral-shell depends on default cursor theme being installed
         (LP: #1658159)
-      . Chrome-less shell hint does not work any more (LP: #1658117)
 
  -- Cemil Azizoglu <[e-mail]>  Fri, 27 Jan 2017 03:02:28 +0000
 

=== modified file 'debian/libmiral2.symbols'
--- debian/libmiral2.symbols	2017-02-14 11:49:59 +0000
+++ debian/libmiral2.symbols	2017-02-15 17:24:17 +0000
@@ -1,7 +1,5 @@
 libmiral.so.2 libmiral2 #MINVER#
  MIRAL_1.0@MIRAL_1.0 1.0.0
- (c++)"miral::WindowInfo::shell_chrome(MirShellChrome)@MIRAL_1.2" 1.2.0
- (c++)"miral::WindowInfo::shell_chrome() const@MIRAL_1.2" 1.2.0
  (c++)"miral::WindowInfo::height_inc(mir::geometry::detail::IntWrapper<mir::geometry::DeltaYTag>)@MIRAL_1.0" 1.0.0
  (c++)"miral::WindowInfo::max_aspect(miral::WindowSpecification::AspectRatio)@MIRAL_1.0" 1.0.0
  (c++)"miral::WindowInfo::max_height(mir::geometry::detail::IntWrapper<mir::geometry::HeightTag>)@MIRAL_1.0" 1.0.0
@@ -365,8 +363,21 @@
  (c++)"miral::WindowInfo::can_morph_to(MirWindowType) const@MIRAL_1.1" 1.1.0
  (c++)"miral::CanonicalWindowManagerPolicy::place_new_window(miral::ApplicationInfo const&, miral::WindowSpecification const&)@MIRAL_1.1" 1.1.0
  MIRAL_1.2@MIRAL_1.2 1.2.0
+ (c++)"miral::InternalClientLauncher::launch(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, std::function<void (mir::client::Connection)> const&, std::function<void (std::weak_ptr<mir::scene::Session>)> const&) const@MIRAL_1.2" 1.2.0
  (c++)"miral::StartupInternalClient::StartupInternalClient(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >, std::function<void (mir::client::Connection)>, std::function<void (std::weak_ptr<mir::scene::Session>)>)@MIRAL_1.2" 1.2.0
- (c++)"miral::InternalClientLauncher::launch(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, std::function<void (mir::client::Connection)> const&, std::function<void (std::weak_ptr<mir::scene::Session>)> const&) const@MIRAL_1.2" 1.2.0
+ (c++)"miral::WindowInfo::shell_chrome(MirShellChrome)@MIRAL_1.2" 1.2.0
+ (c++)"miral::WindowInfo::shell_chrome() const@MIRAL_1.2" 1.2.0
  (c++)"miral::WindowManagerTools::drag_window(miral::Window const&, mir::geometry::Displacement)@MIRAL_1.2" 1.2.0
+ (c++)"miral::WindowManagerTools::create_workspace()@MIRAL_1.2" 1.2.0
+ (c++)"miral::WindowManagerTools::add_tree_to_workspace(miral::Window const&, std::shared_ptr<miral::Workspace> const&)@MIRAL_1.2" 1.2.0
+ (c++)"miral::WindowManagerTools::remove_tree_from_workspace(miral::Window const&, std::shared_ptr<miral::Workspace> const&)@MIRAL_1.2" 1.2.0
+ (c++)"miral::operator<(miral::Window const&, miral::Window const&)@MIRAL_1.0" 1.2.0
  (c++)"typeinfo for miral::ApplicationAuthorizer@MIRAL_1.0" 1.2.0
  (c++)"typeinfo for miral::ApplicationAuthorizer1@MIRAL_1.2" 1.2.0
+ MIRAL_1.3@MIRAL_1.3 1.3.0
+ (c++)"miral::WorkspacePolicy::advise_adding_to_workspace(std::shared_ptr<miral::Workspace> const&, std::vector<miral::Window, std::allocator<miral::Window> > const&)@MIRAL_1.3" 1.2.0
+ (c++)"miral::WorkspacePolicy::advise_removing_from_workspace(std::shared_ptr<miral::Workspace> const&, std::vector<miral::Window, std::allocator<miral::Window> > const&)@MIRAL_1.3" 1.2.0
+ (c++)"miral::WindowManagerTools::for_each_window_in_workspace(std::shared_ptr<miral::Workspace> const&, std::function<void (miral::Window const&)> const&)@MIRAL_1.3" 1.2.0
+ (c++)"miral::WindowManagerTools::for_each_workspace_containing(miral::Window const&, std::function<void (std::shared_ptr<miral::Workspace> const&)> const&)@MIRAL_1.3" 1.2.0
+ (c++)"typeinfo for miral::WorkspacePolicy@MIRAL_1.3" 1.2.0
+ (c++)"vtable for miral::WorkspacePolicy@MIRAL_1.3" 1.2.0
\ No newline at end of file

=== modified file 'include/mir/client/window_id.h'
--- include/mir/client/window_id.h	2017-02-14 13:50:07 +0000
+++ include/mir/client/window_id.h	2017-02-15 17:24:17 +0000
@@ -27,7 +27,7 @@
 #include <mir_toolkit/mir_persistent_id.h>
 #endif
 
-#if MIR_CLIENT_API_VERSION < MIR_VERSION_NUMBER(0, 27, 0)
+#if MIR_CLIENT_API_VERSION < MIR_VERSION_NUMBER(0, 26, 1)
 #if MIR_CLIENT_VERSION < MIR_VERSION_NUMBER(3, 5, 0)
 auto const mir_window_request_window_id_sync = mir_surface_request_persistent_id_sync;
 #else

=== modified file 'include/miral/window.h'
--- include/miral/window.h	2016-08-05 08:59:05 +0000
+++ include/miral/window.h	2017-02-15 17:24:17 +0000
@@ -63,15 +63,20 @@
     friend bool operator==(Window const& lhs, Window const& rhs);
     friend bool operator==(std::shared_ptr<mir::scene::Surface> const& lhs, Window const& rhs);
     friend bool operator==(Window const& lhs, std::shared_ptr<mir::scene::Surface> const& rhs);
+    friend bool operator<(Window const& lhs, Window const& rhs);
 };
 
 bool operator==(Window const& lhs, Window const& rhs);
 bool operator==(std::shared_ptr<mir::scene::Surface> const& lhs, Window const& rhs);
 bool operator==(Window const& lhs, std::shared_ptr<mir::scene::Surface> const& rhs);
+bool operator<(Window const& lhs, Window const& rhs);
 
 inline bool operator!=(Window const& lhs, Window const& rhs) { return !(lhs == rhs); }
 inline bool operator!=(std::shared_ptr<mir::scene::Surface> const& lhs, Window const& rhs) { return !(lhs == rhs); }
 inline bool operator!=(Window const& lhs, std::shared_ptr<mir::scene::Surface> const& rhs) { return !(lhs == rhs); }
+inline bool operator>(Window const& lhs, Window const& rhs) { return rhs < lhs; }
+inline bool operator<=(Window const& lhs, Window const& rhs) { return !(lhs > rhs); }
+inline bool operator>=(Window const& lhs, Window const& rhs) { return !(lhs < rhs); }
 }
 
 #endif //MIRAL_WINDOW_H

=== modified file 'include/miral/window_manager_tools.h'
--- include/miral/window_manager_tools.h	2017-02-10 10:44:12 +0000
+++ include/miral/window_manager_tools.h	2017-02-15 17:24:17 +0000
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2016 Canonical Ltd.
+ * Copyright © 2016-2017 Canonical Ltd.
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 3,
@@ -39,6 +39,19 @@
 struct ApplicationInfo;
 class WindowSpecification;
 
+/**
+ * Workspace is intentionally opaque in the miral API. Its only purpose is to
+ * provide a shared_ptr which is used as an identifier.
+ *
+ * The MirAL implementation of workspaces only prescribes the following:
+ *  o When child windows are created they are added to all(any) workspaces of parent
+ *  o Focus changes will first try windows with a common workspace
+ *  o Adding/removing windows to a workspace affects the whole ancestor/decendent tree
+ *
+ * The presentation of workspaces is left entirely to the policy
+ */
+class Workspace;
+
 class WindowManagerToolsImplementation;
 
 /// Window management functions for querying and updating MirAL's model
@@ -158,6 +171,47 @@
 
     /// Set a default size and position to reflect state change
     void place_and_size_for_state(WindowSpecification& modifications, WindowInfo const& window_info) const;
+
+    /** Create a workspace.
+     * \remark the tools hold only a weak_ptr<> to the workspace - there is no need for an explicit "destroy".
+     * @return a shared_ptr owning the workspace
+     */
+    auto create_workspace() -> std::shared_ptr<Workspace>;
+
+    /**
+     * Add the tree containing window to a workspace
+     * @param window    the window
+     * @param workspace the workspace;
+     */
+    void add_tree_to_workspace(Window const& window, std::shared_ptr<Workspace> const& workspace);
+
+    /**
+     * Remove the tree containing window from a workspace
+     * @param window    the window
+     * @param workspace the workspace;
+     */
+    void remove_tree_from_workspace(Window const& window, std::shared_ptr<Workspace> const& workspace);
+
+    /**
+     * invoke callback with each workspace containing window
+     * \warning it is unsafe to add or remove windows from workspaces from the callback during enumeration
+     * @param window
+     * @param callback
+     */
+    void for_each_workspace_containing(
+        Window const& window,
+        std::function<void(std::shared_ptr<Workspace> const& workspace)> const& callback);
+
+    /**
+     * invoke callback with each window contained in workspace
+     * \warning it is unsafe to add or remove windows from workspaces from the callback during enumeration
+     * @param workspace
+     * @param callback
+     */
+    void for_each_window_in_workspace(
+        std::shared_ptr<Workspace> const& workspace,
+        std::function<void(Window const& window)> const& callback);
+
 /** @} */
 
     /** Multi-thread support

=== added file 'include/miral/workspace_policy.h'
--- include/miral/workspace_policy.h	1970-01-01 00:00:00 +0000
+++ include/miral/workspace_policy.h	2017-02-15 17:24:17 +0000
@@ -0,0 +1,88 @@
+/*
+ * Copyright © 2017 Canonical Ltd.
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 3,
+ * as published by the Free Software Foundation.
+ *
+ * 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/>.
+ *
+ * Authored by: Alan Griffiths <[e-mail]>
+ */
+
+#ifndef MIRAL_WORKSPACE_POLICY_H
+#define MIRAL_WORKSPACE_POLICY_H
+
+#include "miral/version.h"
+
+#include <memory>
+#include <vector>
+
+namespace miral
+{
+class Window;
+
+/**
+ * Workspace is intentionally opaque in the miral API. Its only purpose is to
+ * provide a shared_ptr which is used as an identifier.
+ */
+class Workspace;
+
+/**
+ *  Advise changes to workspaces.
+ *
+ *  \note This interface is intended to be implemented by a WindowManagementPolicy
+ *  implementation, we can't add these functions directly to that interface without
+ *  breaking ABI (the vtab could be incompatible).
+ *  When initializing the window manager this interface will be detected by
+ *  dynamic_cast and registered accordingly.
+ */
+class WorkspacePolicy
+{
+public:
+/** @name notification of WM events that the policy may need to track.
+ * These calls happen "under lock" and are wrapped by the usual
+ * WindowManagementPolicy::advise_begin(), advise_end() calls.
+ * They should not call WindowManagerTools::invoke_under_lock()
+ *  @{ */
+
+    /** Notification that windows are being added to a workspace.
+     *  These windows are ordered with parents before children,
+     *  and form a single tree rooted at the first element.
+     *
+     * @param workspace   the workspace
+     * @param windows   the windows
+     */
+    virtual void advise_adding_to_workspace(
+        std::shared_ptr<Workspace> const& workspace,
+        std::vector<Window> const& windows);
+
+    /** Notification that windows are being removed from a workspace.
+     *  These windows are ordered with parents before children,
+     *  and form a single tree rooted at the first element.
+     *
+     * @param workspace   the workspace
+     * @param windows   the windows
+     */
+    virtual void advise_removing_from_workspace(
+        std::shared_ptr<Workspace> const& workspace,
+        std::vector<Window> const& windows);
+
+/** @} */
+
+    virtual ~WorkspacePolicy() = default;
+    WorkspacePolicy() = default;
+    WorkspacePolicy(WorkspacePolicy const&) = delete;
+    WorkspacePolicy& operator=(WorkspacePolicy const&) = delete;
+};
+#if MIRAL_VERSION >= MIR_VERSION_NUMBER(2, 0, 0)
+#error "We've presumably broken ABI - please roll this interface into WindowManagementPolicy"
+#endif
+}
+#endif //MIRAL_WORKSPACE_POLICY_H

=== modified file 'miral/CMakeLists.txt'
--- miral/CMakeLists.txt	2017-02-14 15:46:32 +0000
+++ miral/CMakeLists.txt	2017-02-15 17:24:17 +0000
@@ -49,6 +49,7 @@
     set_command_line_hander.cpp         ${CMAKE_SOURCE_DIR}/include/miral/set_command_line_hander.h
     set_terminator.cpp                  ${CMAKE_SOURCE_DIR}/include/miral/set_terminator.h
     set_window_managment_policy.cpp     ${CMAKE_SOURCE_DIR}/include/miral/set_window_managment_policy.h
+    workspace_policy.cpp                ${CMAKE_SOURCE_DIR}/include/miral/workspace_policy.h
     window_management_policy.cpp        ${CMAKE_SOURCE_DIR}/include/miral/window_management_policy.h
     window_manager_tools.cpp            ${CMAKE_SOURCE_DIR}/include/miral/window_manager_tools.h
                                         ${CMAKE_SOURCE_DIR}/include/mir/client/window_spec.h

=== modified file 'miral/basic_window_manager.cpp'
--- miral/basic_window_manager.cpp	2017-02-08 17:17:41 +0000
+++ miral/basic_window_manager.cpp	2017-02-15 17:24:17 +0000
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2015-2016 Canonical Ltd.
+ * Copyright © 2015-2017 Canonical Ltd.
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 3,
@@ -18,6 +18,7 @@
 
 #include "basic_window_manager.h"
 #include "miral/window_manager_tools.h"
+#include "miral/workspace_policy.h"
 
 #include <mir/scene/session.h>
 #include <mir/scene/surface.h>
@@ -37,15 +38,11 @@
 namespace
 {
 int const title_bar_height = 12;
+}
 
-struct Locker
+struct miral::BasicWindowManager::Locker
 {
-    Locker(std::mutex& mutex, std::unique_ptr<miral::WindowManagementPolicy> const& policy) :
-        lock{mutex},
-        policy{policy.get()}
-    {
-        policy->advise_begin();
-    }
+    explicit Locker(miral::BasicWindowManager* self);
 
     ~Locker()
     {
@@ -53,9 +50,53 @@
     }
 
     std::lock_guard<std::mutex> const lock;
-    miral::WindowManagementPolicy* const policy;
+    WindowManagementPolicy* const policy;
 };
-}
+
+miral::BasicWindowManager::Locker::Locker(BasicWindowManager* self) :
+    lock{self->mutex},
+    policy{self->policy.get()}
+{
+    policy->advise_begin();
+    std::vector<std::weak_ptr<Workspace>> workspaces;
+    {
+        std::lock_guard<std::mutex> const lock{self->dead_workspaces.dead_workspaces_mutex};
+        workspaces.swap(self->dead_workspaces.workspaces);
+    }
+
+    for (auto const& workspace : workspaces)
+        self->workspaces_to_windows.left.erase(workspace);
+}
+
+namespace
+{
+
+auto find_workspace_policy(std::unique_ptr<miral::WindowManagementPolicy> const& policy) -> miral::WorkspacePolicy*
+{
+    miral::WorkspacePolicy* result = dynamic_cast<miral::WorkspacePolicy*>(policy.get());
+
+    if (result)
+        return result;
+
+    struct NullWorkspacePolicy : miral::WorkspacePolicy
+    {
+        void advise_adding_to_workspace(
+            std::shared_ptr<miral::Workspace> const&, std::vector<miral::Window> const&) override
+        {
+        }
+
+        void advise_removing_from_workspace(
+            std::shared_ptr<miral::Workspace> const&, std::vector<miral::Window> const&) override
+        {
+        }
+    };
+
+    static NullWorkspacePolicy null_workspace_policy;
+
+    return &null_workspace_policy;
+}
+}
+
 
 miral::BasicWindowManager::BasicWindowManager(
     shell::FocusController* focus_controller,
@@ -65,19 +106,20 @@
     focus_controller(focus_controller),
     display_layout(display_layout),
     persistent_surface_store{persistent_surface_store},
-    policy(build(WindowManagerTools{this}))
+    policy(build(WindowManagerTools{this})),
+    workspace_policy{find_workspace_policy(policy)}
 {
 }
 
 void miral::BasicWindowManager::add_session(std::shared_ptr<scene::Session> const& session)
 {
-    Locker lock{mutex, policy};
+    Locker lock{this};
     policy->advise_new_app(app_info[session] = ApplicationInfo(session));
 }
 
 void miral::BasicWindowManager::remove_session(std::shared_ptr<scene::Session> const& session)
 {
-    Locker lock{mutex, policy};
+    Locker lock{this};
     policy->advise_delete_app(app_info[session]);
     app_info.erase(session);
 }
@@ -88,7 +130,7 @@
     std::function<frontend::SurfaceId(std::shared_ptr<scene::Session> const& session, scene::SurfaceCreationParameters const& params)> const& build)
 -> frontend::SurfaceId
 {
-    Locker lock{mutex, policy};
+    Locker lock{this};
 
     auto& session_info = info_for(session);
 
@@ -112,6 +154,9 @@
     if (parent)
         info_for(parent).add_child(window);
 
+    for_each_workspace_containing(parent,
+        [&](std::shared_ptr<miral::Workspace> const& workspace) { add_tree_to_workspace(window, workspace); });
+
     if (window_info.state() == mir_window_state_fullscreen)
         fullscreen_surfaces.insert(window_info.window());
 
@@ -120,7 +165,7 @@
     std::shared_ptr<scene::Surface> const scene_surface = window_info.window();
     scene_surface->add_observer(std::make_shared<shell::SurfaceReadyObserver>(
         [this, &window_info](std::shared_ptr<scene::Session> const&, std::shared_ptr<scene::Surface> const&)
-            { Locker lock{mutex, policy}; policy->handle_window_ready(window_info); },
+            { Locker lock{this}; policy->handle_window_ready(window_info); },
         session,
         scene_surface));
 
@@ -141,7 +186,7 @@
     std::shared_ptr<scene::Surface> const& surface,
     shell::SurfaceSpecification const& modifications)
 {
-    Locker lock{mutex, policy};
+    Locker lock{this};
     auto& info = info_for(surface);
     WindowSpecification mods{modifications};
     validate_modification_request(mods, info);
@@ -153,16 +198,28 @@
     std::shared_ptr<scene::Session> const& session,
     std::weak_ptr<scene::Surface> const& surface)
 {
-    Locker lock{mutex, policy};
+    Locker lock{this};
     remove_window(session, info_for(surface));
 }
 
 void miral::BasicWindowManager::remove_window(Application const& application, miral::WindowInfo const& info)
 {
+    bool const is_active_window{mru_active_windows.top() == info.window()};
+    auto const workspaces_containing_window = workspaces_containing(info.window());
+
+    {
+        std::vector<Window> const windows_removed{info.window()};
+
+        for (auto const& workspace : workspaces_containing_window)
+        {
+            workspace_policy->advise_removing_from_workspace(workspace, windows_removed);
+        }
+
+        workspaces_to_windows.right.erase(info.window());
+    }
+
     policy->advise_delete_window(info);
 
-    bool const is_active_window{mru_active_windows.top() == info.window()};
-
     info_for(application).remove_window(info.window());
     mru_active_windows.erase(info.window());
     fullscreen_surfaces.erase(info.window());
@@ -175,30 +232,66 @@
 
     if (is_active_window)
     {
-        // Try to make the parent active
-        if (parent && select_active_window(parent))
-            return;
-
-        if (can_activate_window_for_session(application))
-            return;
-
-        // Try to activate to recently active window of any application
-        {
-            miral::Window new_focus;
-
-            mru_active_windows.enumerate([&](miral::Window& window)
+        refocus(application, parent, workspaces_containing_window);
+    }
+}
+
+void miral::BasicWindowManager::refocus(
+    miral::Application const& application, miral::Window const& parent,
+    std::vector<std::shared_ptr<Workspace>> const& workspaces_containing_window)
+{
+    // Try to make the parent active
+    if (parent && select_active_window(parent))
+        return;
+
+    if (can_activate_window_for_session_in_workspace(application, workspaces_containing_window))
+        return;
+
+    // Try to activate to recently active window of any application in a shared workspace
+    {
+        miral::Window new_focus;
+
+        mru_active_windows.enumerate([&](miral::Window& window)
+            {
+                // select_active_window() calls set_focus_to() which updates mru_active_windows and changes window
+                auto const w = window;
+
+                for (auto const& workspace : workspaces_containing(w))
                 {
-                    // select_active_window() calls set_focus_to() which updates mru_active_windows and changes window
-                    auto const w = window;
-                    return !(new_focus = select_active_window(w));
-                });
-
-            if (new_focus) return;
-        }
-
-        // Fallback to cycling through applications
-        focus_next_application();
-    }
+                    for (auto const& ww : workspaces_containing_window)
+                    {
+                        if (ww == workspace)
+                        {
+                            return !(new_focus = select_active_window(w));
+                        }
+                    }
+                }
+
+                return true;
+            });
+
+        if (new_focus) return;
+    }
+
+    if (can_activate_window_for_session(application))
+        return;
+
+    // Try to activate to recently active window of any application
+    {
+        miral::Window new_focus;
+
+        mru_active_windows.enumerate([&](miral::Window& window)
+            {
+                // select_active_window() calls set_focus_to() which updates mru_active_windows and changes window
+                auto const w = window;
+                return !(new_focus = select_active_window(w));
+            });
+
+        if (new_focus) return;
+    }
+
+    // Fallback to cycling through applications
+    focus_next_application();
 }
 
 void miral::BasicWindowManager::erase(miral::WindowInfo const& info)
@@ -214,7 +307,7 @@
 
 void miral::BasicWindowManager::add_display(geometry::Rectangle const& area)
 {
-    Locker lock{mutex, policy};
+    Locker lock{this};
     displays.add(area);
 
     for (auto window : fullscreen_surfaces)
@@ -230,7 +323,7 @@
 
 void miral::BasicWindowManager::remove_display(geometry::Rectangle const& area)
 {
-    Locker lock{mutex, policy};
+    Locker lock{this};
     displays.remove(area);
     for (auto window : fullscreen_surfaces)
     {
@@ -245,21 +338,21 @@
 
 bool miral::BasicWindowManager::handle_keyboard_event(MirKeyboardEvent const* event)
 {
-    Locker lock{mutex, policy};
+    Locker lock{this};
     update_event_timestamp(event);
     return policy->handle_keyboard_event(event);
 }
 
 bool miral::BasicWindowManager::handle_touch_event(MirTouchEvent const* event)
 {
-    Locker lock{mutex, policy};
+    Locker lock{this};
     update_event_timestamp(event);
     return policy->handle_touch_event(event);
 }
 
 bool miral::BasicWindowManager::handle_pointer_event(MirPointerEvent const* event)
 {
-    Locker lock{mutex, policy};
+    Locker lock{this};
     update_event_timestamp(event);
 
     cursor = {
@@ -274,7 +367,7 @@
     std::shared_ptr<scene::Surface> const& surface,
     uint64_t timestamp)
 {
-    Locker lock{mutex, policy};
+    Locker lock{this};
     if (timestamp >= last_input_event_timestamp)
         policy->handle_raise_window(info_for(surface));
 }
@@ -315,7 +408,7 @@
         return surface->configure(attrib, value);
     }
 
-    Locker lock{mutex, policy};
+    Locker lock{this};
     auto& info = info_for(surface);
 
     validate_modification_request(modification, info);
@@ -407,6 +500,28 @@
 
 void miral::BasicWindowManager::focus_next_application()
 {
+    if (auto const prev = active_window())
+    {
+        auto const workspaces_containing_window = workspaces_containing(prev);
+
+        if (!workspaces_containing_window.empty())
+        {
+            do
+            {
+                focus_controller->focus_next_session();
+
+                if (can_activate_window_for_session_in_workspace(
+                    focus_controller->focused_session(),
+                    workspaces_containing_window))
+                {
+                    return;
+                }
+            }
+            while (focus_controller->focused_session() != prev.application());
+        }
+
+    }
+
     focus_controller->focus_next_session();
 
     if (can_activate_window_for_session(focus_controller->focused_session()))
@@ -417,15 +532,67 @@
     select_active_window(focussed_surface ? info_for(focussed_surface).window() : Window{});
 }
 
+auto miral::BasicWindowManager::workspaces_containing(Window const& window) const
+-> std::vector<std::shared_ptr<Workspace>>
+{
+    auto const iter_pair = workspaces_to_windows.right.equal_range(window);
+
+    std::vector<std::shared_ptr<Workspace>> workspaces_containing_window;
+    for (auto kv = iter_pair.first; kv != iter_pair.second; ++kv)
+    {
+        if (auto const workspace = kv->second.lock())
+        {
+            workspaces_containing_window.push_back(workspace);
+        }
+    }
+
+    return workspaces_containing_window;
+}
+
 void miral::BasicWindowManager::focus_next_within_application()
 {
     if (auto const prev = active_window())
     {
+        auto const workspaces_containing_window = workspaces_containing(prev);
         auto const& siblings = info_for(prev.application()).windows();
         auto current = find(begin(siblings), end(siblings), prev);
 
         if (current != end(siblings))
         {
+            while (++current != end(siblings))
+            {
+                for (auto const& workspace : workspaces_containing(*current))
+                {
+                    for (auto const& ww : workspaces_containing_window)
+                    {
+                        if (ww == workspace)
+                        {
+                            if (prev != select_active_window(*current))
+                                return;
+                        }
+                    }
+                }
+            }
+        }
+
+        for (current = begin(siblings); *current != prev; ++current)
+        {
+            for (auto const& workspace : workspaces_containing(*current))
+            {
+                for (auto const& ww : workspaces_containing_window)
+                {
+                    if (ww == workspace)
+                    {
+                        if (prev != select_active_window(*current))
+                            return;
+                    }
+                }
+            }
+        }
+
+        current = find(begin(siblings), end(siblings), prev);
+        if (current != end(siblings))
+        {
             while (++current != end(siblings) && prev == select_active_window(*current))
                 ;
         }
@@ -886,12 +1053,35 @@
 
         if (window == active_window())
         {
+            auto const workspaces_containing_window = workspaces_containing(window);
+
             // Try to activate to recently active window of any application
             mru_active_windows.enumerate([&](Window& candidate)
                 {
                     if (candidate == window)
                         return true;
                     auto const w = candidate;
+                    for (auto const& workspace : workspaces_containing(w))
+                    {
+                        for (auto const& ww : workspaces_containing_window)
+                        {
+                            if (ww == workspace)
+                            {
+                                return !(select_active_window(w));
+                            }
+                        }
+                    }
+
+                    return true;
+                });
+
+            // Try to activate to recently active window of any application
+            if (window == active_window() || !active_window())
+                mru_active_windows.enumerate([&](Window& candidate)
+                {
+                    if (candidate == window)
+                        return true;
+                    auto const w = candidate;
                     return !(select_active_window(w));
                 });
 
@@ -945,7 +1135,7 @@
 
 void miral::BasicWindowManager::invoke_under_lock(std::function<void()> const& callback)
 {
-    Locker lock{mutex, policy};
+    Locker lock{this};
     callback();
 }
 
@@ -1076,6 +1266,35 @@
     return new_focus;
 }
 
+auto miral::BasicWindowManager::can_activate_window_for_session_in_workspace(
+    Application const& session,
+    std::vector<std::shared_ptr<Workspace>> const& workspaces) -> bool
+{
+    miral::Window new_focus;
+
+    mru_active_windows.enumerate([&](miral::Window& window)
+        {
+            // select_active_window() calls set_focus_to() which updates mru_active_windows and changes window
+            auto const w = window;
+
+            if (w.application() != session)
+                return true;
+
+            for (auto const& workspace : workspaces_containing(w))
+            {
+                for (auto const& ww : workspaces)
+                {
+                    if (ww == workspace)
+                        return !(new_focus = select_active_window(w));
+                }
+            }
+
+            return true;
+        });
+
+    return new_focus;
+}
+
 auto miral::BasicWindowManager::place_new_surface(ApplicationInfo const& app_info, WindowSpecification parameters)
 -> WindowSpecification
 {
@@ -1610,3 +1829,139 @@
             BOOST_THROW_EXCEPTION(std::runtime_error("height must be positive"));
     }
 }
+
+class miral::Workspace
+{
+public:
+    explicit Workspace(miral::BasicWindowManager::DeadWorkspaces& dead_workspaces) :
+        dead_workspaces{dead_workspaces} {}
+
+    std::weak_ptr<Workspace> self;
+
+    ~Workspace()
+    {
+        std::lock_guard<std::mutex> lock {dead_workspaces.dead_workspaces_mutex};
+        dead_workspaces.workspaces.push_back(self);
+    }
+
+private:
+    miral::BasicWindowManager::DeadWorkspaces& dead_workspaces;
+};
+
+auto miral::BasicWindowManager::create_workspace() -> std::shared_ptr<Workspace>
+{
+    auto const result = std::make_shared<Workspace>(dead_workspaces);
+    result->self = result;
+    return result;
+}
+
+void miral::BasicWindowManager::add_tree_to_workspace(
+    miral::Window const& window, std::shared_ptr<miral::Workspace> const& workspace)
+{
+    if (!window) return;
+
+    auto root = window;
+    auto const* info = &info_for(root);
+
+    while (auto const& parent = info->parent())
+    {
+        root = parent;
+        info = &info_for(root);
+    }
+
+    std::vector<Window> windows;
+
+    std::function<void(WindowInfo const& info)> const add_children =
+        [&,this](WindowInfo const& info)
+        {
+            for (auto const& child : info.children())
+            {
+                windows.push_back(child);
+                add_children(info_for(child));
+            }
+        };
+
+    windows.push_back(root);
+    add_children(*info);
+
+    auto const iter_pair = workspaces_to_windows.left.equal_range(workspace);
+
+    std::vector<Window> windows_added;
+
+    for (auto& w : windows)
+    {
+        if (!std::count_if(iter_pair.first, iter_pair.second,
+                           [&w](wwbimap_t::left_value_type const& kv) { return kv.second == w; }))
+        {
+            workspaces_to_windows.left.insert(wwbimap_t::left_value_type{workspace, w});
+            windows_added.push_back(w);
+        }
+    }
+
+    if (!windows_added.empty())
+        workspace_policy->advise_adding_to_workspace(workspace, windows_added);
+}
+
+void miral::BasicWindowManager::remove_tree_from_workspace(
+    miral::Window const& window, std::shared_ptr<miral::Workspace> const& workspace)
+{
+    if (!window) return;
+
+    auto root = window;
+    auto const* info = &info_for(root);
+
+    while (auto const& parent = info->parent())
+    {
+        root = parent;
+        info = &info_for(root);
+    }
+
+    std::vector<Window> windows;
+
+    std::function<void(WindowInfo const& info)> const add_children =
+        [&,this](WindowInfo const& info)
+            {
+                for (auto const& child : info.children())
+                {
+                    windows.push_back(child);
+                    add_children(info_for(child));
+                }
+            };
+
+    windows.push_back(root);
+    add_children(*info);
+
+    std::vector<Window> windows_removed;
+
+    auto const iter_pair = workspaces_to_windows.left.equal_range(workspace);
+    for (auto kv = iter_pair.first; kv != iter_pair.second; ++kv)
+    {
+        if (std::count(begin(windows), end(windows), kv->second))
+        {
+            workspaces_to_windows.left.erase(kv);
+            windows_removed.push_back(kv->second);
+        }
+    }
+
+    if (!windows_removed.empty())
+        workspace_policy->advise_removing_from_workspace(workspace, windows_removed);
+}
+
+void miral::BasicWindowManager::for_each_workspace_containing(
+    miral::Window const& window, std::function<void(std::shared_ptr<miral::Workspace> const&)> const& callback)
+{
+    auto const iter_pair = workspaces_to_windows.right.equal_range(window);
+    for (auto kv = iter_pair.first; kv != iter_pair.second; ++kv)
+    {
+        if (auto const workspace = kv->second.lock())
+            callback(workspace);
+    }
+}
+
+void miral::BasicWindowManager::for_each_window_in_workspace(
+    std::shared_ptr<miral::Workspace> const& workspace, std::function<void(miral::Window const&)> const& callback)
+{
+    auto const iter_pair = workspaces_to_windows.left.equal_range(workspace);
+    for (auto kv = iter_pair.first; kv != iter_pair.second; ++kv)
+        callback(kv->second);
+}

=== modified file 'miral/basic_window_manager.h'
--- miral/basic_window_manager.h	2017-02-02 17:18:42 +0000
+++ miral/basic_window_manager.h	2017-02-15 17:24:17 +0000
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2015-2016 Canonical Ltd.
+ * Copyright © 2015-2017 Canonical Ltd.
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 3,
@@ -31,6 +31,9 @@
 #include <mir/shell/abstract_shell.h>
 #include <mir/shell/window_manager.h>
 
+#include <boost/bimap.hpp>
+#include <boost/bimap/multiset_of.hpp>
+
 #include <map>
 #include <mutex>
 
@@ -41,6 +44,7 @@
 
 namespace miral
 {
+class WorkspacePolicy;
 using mir::shell::SurfaceSet;
 using WindowManagementPolicyBuilder =
     std::function<std::unique_ptr<miral::WindowManagementPolicy>(miral::WindowManagerTools const& tools)>;
@@ -97,6 +101,19 @@
         MirWindowAttrib attrib,
         int value) override;
 
+    auto create_workspace() -> std::shared_ptr<Workspace> override;
+
+    void add_tree_to_workspace(Window const& window, std::shared_ptr<Workspace> const& workspace) override;
+
+    void remove_tree_from_workspace(Window const& window, std::shared_ptr<Workspace> const& workspace) override;
+
+    void for_each_workspace_containing(
+        Window const& window,
+        std::function<void(std::shared_ptr<Workspace> const& workspace)> const& callback) override;
+
+    void for_each_window_in_workspace(
+        std::shared_ptr<Workspace> const& workspace, std::function<void(Window const&)> const& callback) override;
+
     auto count_applications() const -> unsigned int override;
 
     void for_each_application(std::function<void(ApplicationInfo& info)> const& functor) override;
@@ -149,6 +166,7 @@
     std::shared_ptr<mir::shell::DisplayLayout> const display_layout;
     std::shared_ptr<mir::shell::PersistentSurfaceStore> const persistent_surface_store;
     std::unique_ptr<WindowManagementPolicy> const policy;
+    WorkspacePolicy* const workspace_policy;
 
     std::mutex mutex;
     SessionInfoMap app_info;
@@ -160,11 +178,30 @@
     using FullscreenSurfaces = std::set<Window>;
     FullscreenSurfaces fullscreen_surfaces;
 
+    friend class Workspace;
+    using wwbimap_t = boost::bimap<
+        boost::bimaps::multiset_of<std::weak_ptr<Workspace>, std::owner_less<std::weak_ptr<Workspace>>>,
+        boost::bimaps::multiset_of<Window>>;
+
+    wwbimap_t workspaces_to_windows;
+
+    // Workspaces may die without any sync with the BWM mutex
+    struct DeadWorkspaces
+    {
+        std::mutex mutable dead_workspaces_mutex;
+        std::vector<std::weak_ptr<Workspace>> workspaces;
+    } dead_workspaces;
+
+    struct Locker;
+
     void update_event_timestamp(MirKeyboardEvent const* kev);
     void update_event_timestamp(MirPointerEvent const* pev);
     void update_event_timestamp(MirTouchEvent const* tev);
 
     auto can_activate_window_for_session(miral::Application const& session) -> bool;
+    auto can_activate_window_for_session_in_workspace(
+        miral::Application const& session,
+        std::vector<std::shared_ptr<Workspace>> const& workspaces) -> bool;
 
     auto place_new_surface(ApplicationInfo const& app_info, WindowSpecification parameters) -> WindowSpecification;
     auto place_relative(mir::geometry::Rectangle const& parent, miral::WindowSpecification const& parameters, Size size)
@@ -177,6 +214,9 @@
     void set_state(miral::WindowInfo& window_info, MirWindowState value);
     auto fullscreen_rect_for(WindowInfo const& window_info) const -> Rectangle;
     void remove_window(Application const& application, miral::WindowInfo const& info);
+    void refocus(Application const& application, Window const& parent,
+                 std::vector<std::shared_ptr<Workspace>> const& workspaces_containing_window);
+    auto workspaces_containing(Window const& window) const -> std::vector<std::shared_ptr<Workspace>>;
 };
 }
 

=== modified file 'miral/symbols.map'
--- miral/symbols.map	2017-02-15 12:06:25 +0000
+++ miral/symbols.map	2017-02-15 17:24:17 +0000
@@ -362,8 +362,36 @@
   _ZN5miral21StartupInternalClientC?ENSt7__cxx1112basic_stringIcSt11char_traitsIcESaIcEEESt8functionIFvN3mir6client10ConnectionEEES7_IFvSt8weak_ptrINS8_5scene7SessionEEEE;
   extern "C++" {
     miral::WindowInfo::shell_chrome*;
+    miral::WindowManagerTools::add_tree_to_workspace*;
+    miral::WindowManagerTools::create_workspace*;
     miral::WindowManagerTools::drag_window*;
+    miral::WindowManagerTools::remove_tree_from_workspace*;
     typeinfo?for?miral::ApplicationAuthorizer1;
     vtable?for?miral::ApplicationAuthorizer1;
   };
 } MIRAL_1.1;
+
+MIRAL_1.3 {
+global:
+  extern "C++" {
+    miral::WindowManagerTools::for_each_window_in_workspace*;
+    miral::WindowManagerTools::for_each_workspace_containing*;
+    miral::WorkspacePolicy::?WorkspacePolicy*;
+    miral::WorkspacePolicy::WorkspacePolicy*;
+    miral::WorkspacePolicy::advise_adding_to_workspace*;
+    miral::WorkspacePolicy::advise_removing_from_workspace*;
+    miral::WorkspacePolicy::operator*;
+    miral::toolkit::Window::Window*;
+    non-virtual?thunk?to?miral::WorkspacePolicy::?WorkspacePolicy*;
+    non-virtual?thunk?to?miral::WorkspacePolicy::advise_adding_to_workspace*;
+    non-virtual?thunk?to?miral::WorkspacePolicy::advise_removing_from_workspace*;
+    typeinfo?for?miral::WorkspacePolicy;
+    typeinfo?for?miral::toolkit::Window;
+    typeinfo?for?miral::toolkit::WindowId;
+    typeinfo?for?miral::toolkit::WindowSpec;
+    vtable?for?miral::WorkspacePolicy;
+    vtable?for?miral::toolkit::Window;
+    vtable?for?miral::toolkit::WindowId;
+    vtable?for?miral::toolkit::WindowSpec;
+  };
+} MIRAL_1.2;

=== modified file 'miral/window.cpp'
--- miral/window.cpp	2016-08-05 08:53:45 +0000
+++ miral/window.cpp	2017-02-15 17:24:17 +0000
@@ -120,3 +120,8 @@
 {
     return rhs == lhs;
 }
+
+bool miral::operator<(Window const& lhs, Window const& rhs)
+{
+    return lhs.self.owner_before(rhs.self);
+}

=== modified file 'miral/window_management_trace.cpp'
--- miral/window_management_trace.cpp	2017-02-02 17:18:42 +0000
+++ miral/window_management_trace.cpp	2017-02-15 17:24:17 +0000
@@ -532,6 +532,45 @@
 }
 MIRAL_TRACE_EXCEPTION
 
+auto miral::WindowManagementTrace::create_workspace() -> std::shared_ptr<Workspace>
+try {
+    mir::log_info("%s", __func__);
+    return wrapped.create_workspace();
+}
+MIRAL_TRACE_EXCEPTION
+
+void miral::WindowManagementTrace::add_tree_to_workspace(
+    miral::Window const& window, std::shared_ptr<miral::Workspace> const& workspace)
+try {
+    mir::log_info("%s window=%s, workspace =%p", __func__, dump_of(window).c_str(), workspace.get());
+    wrapped.add_tree_to_workspace(window, workspace);
+}
+MIRAL_TRACE_EXCEPTION
+
+void miral::WindowManagementTrace::remove_tree_from_workspace(
+    miral::Window const& window, std::shared_ptr<miral::Workspace> const& workspace)
+try {
+    mir::log_info("%s window=%s, workspace =%p", __func__, dump_of(window).c_str(), workspace.get());
+    wrapped.remove_tree_from_workspace(window, workspace);
+}
+MIRAL_TRACE_EXCEPTION
+
+void miral::WindowManagementTrace::for_each_workspace_containing(
+    miral::Window const& window, std::function<void(std::shared_ptr<miral::Workspace> const&)> const& callback)
+try {
+    mir::log_info("%s window=%s", __func__, dump_of(window));
+    wrapped.for_each_workspace_containing(window, callback);
+}
+MIRAL_TRACE_EXCEPTION
+
+void miral::WindowManagementTrace::for_each_window_in_workspace(
+    std::shared_ptr<miral::Workspace> const& workspace, std::function<void(miral::Window const&)> const& callback)
+try {
+    mir::log_info("%s workspace =%p", __func__, workspace.get());
+    wrapped.for_each_window_in_workspace(workspace, callback);
+}
+MIRAL_TRACE_EXCEPTION
+
 auto miral::WindowManagementTrace::place_new_window(
     ApplicationInfo const& app_info,
     WindowSpecification const& requested_specification) -> WindowSpecification

=== modified file 'miral/window_management_trace.h'
--- miral/window_management_trace.h	2017-02-02 17:18:42 +0000
+++ miral/window_management_trace.h	2017-02-15 17:24:17 +0000
@@ -90,6 +90,19 @@
 
     auto confirm_inherited_move(WindowInfo const& window_info, Displacement movement) -> Rectangle override;
 
+    auto create_workspace() -> std::shared_ptr<Workspace> override;
+
+    void add_tree_to_workspace(Window const& window, std::shared_ptr<Workspace> const& workspace) override;
+
+    void remove_tree_from_workspace(Window const& window, std::shared_ptr<Workspace> const& workspace) override;
+
+    void for_each_workspace_containing(
+        Window const& window,
+        std::function<void(std::shared_ptr<Workspace> const& workspace)> const& callback) override;
+
+    void for_each_window_in_workspace(
+        std::shared_ptr<Workspace> const& workspace, std::function<void(Window const&)> const& callback) override;
+
 public:
     virtual void advise_begin() override;
 

=== modified file 'miral/window_manager_tools.cpp'
--- miral/window_manager_tools.cpp	2017-02-02 17:18:42 +0000
+++ miral/window_manager_tools.cpp	2017-02-15 17:24:17 +0000
@@ -98,3 +98,26 @@
 void miral::WindowManagerTools::place_and_size_for_state(
     WindowSpecification& modifications, WindowInfo const& window_info) const
 { tools->place_and_size_for_state(modifications, window_info); }
+
+auto miral::WindowManagerTools::create_workspace() -> std::shared_ptr<miral::Workspace>
+{ return tools->create_workspace(); }
+
+void miral::WindowManagerTools::add_tree_to_workspace(
+    miral::Window const& window,
+    std::shared_ptr<miral::Workspace> const& workspace)
+{ tools->add_tree_to_workspace(window, workspace); }
+
+void miral::WindowManagerTools::remove_tree_from_workspace(
+    miral::Window const& window,
+    std::shared_ptr<miral::Workspace> const& workspace)
+{ tools->remove_tree_from_workspace(window, workspace); }
+
+void miral::WindowManagerTools::for_each_workspace_containing(
+    miral::Window const& window,
+    std::function<void(std::shared_ptr<miral::Workspace> const&)> const& callback)
+{ tools->for_each_workspace_containing(window, callback); }
+
+void miral::WindowManagerTools::for_each_window_in_workspace(
+    std::shared_ptr<miral::Workspace> const& workspace,
+    std::function<void(miral::Window const&)> const& callback)
+{ tools->for_each_window_in_workspace(workspace, callback); }

=== modified file 'miral/window_manager_tools_implementation.h'
--- miral/window_manager_tools_implementation.h	2017-02-02 17:18:42 +0000
+++ miral/window_manager_tools_implementation.h	2017-02-15 17:24:17 +0000
@@ -35,6 +35,7 @@
 struct WindowInfo;
 struct ApplicationInfo;
 class WindowSpecification;
+class Workspace;
 
 // The interface through which the policy instructs the controller.
 class WindowManagerToolsImplementation
@@ -69,6 +70,16 @@
     virtual auto id_for_window(Window const& window) const -> std::string = 0;
     virtual void place_and_size_for_state(WindowSpecification& modifications, WindowInfo const& window_info) const= 0;
 
+    virtual auto create_workspace() -> std::shared_ptr<Workspace> = 0;
+    virtual void add_tree_to_workspace(Window const& window, std::shared_ptr<Workspace> const& workspace) = 0;
+    virtual void remove_tree_from_workspace(Window const& window, std::shared_ptr<Workspace> const& workspace) = 0;
+    virtual void for_each_workspace_containing(
+        Window const& window,
+        std::function<void(std::shared_ptr<Workspace> const& workspace)> const& callback) = 0;
+    virtual void for_each_window_in_workspace(
+        std::shared_ptr<Workspace> const& workspace,
+        std::function<void(Window const& window)> const& callback) = 0;
+
 /** @} */
 
 /** @name Multi-thread support

=== added file 'miral/workspace_policy.cpp'
--- miral/workspace_policy.cpp	1970-01-01 00:00:00 +0000
+++ miral/workspace_policy.cpp	2017-02-15 17:24:17 +0000
@@ -0,0 +1,29 @@
+/*
+ * Copyright © 2017 Canonical Ltd.
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 3,
+ * as published by the Free Software Foundation.
+ *
+ * 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/>.
+ *
+ * Authored by: Alan Griffiths <[e-mail]>
+ */
+
+#include <miral/workspace_policy.h>
+
+void miral::WorkspacePolicy::advise_adding_to_workspace(
+    std::shared_ptr<Workspace> const& , std::vector<Window> const&)
+{
+}
+
+void miral::WorkspacePolicy::advise_removing_from_workspace(
+    std::shared_ptr<Workspace> const&, std::vector<Window> const&)
+{
+}

=== modified file 'scripts/process_doxygen_xml.py'
--- scripts/process_doxygen_xml.py	2017-02-15 12:06:25 +0000
+++ scripts/process_doxygen_xml.py	2017-02-15 17:24:17 +0000
@@ -443,10 +443,23 @@
 
 #    miral::StartupInternalClient::StartupInternalClient*;
   _ZN5miral21StartupInternalClientC?ENSt7__cxx1112basic_stringIcSt11char_traitsIcESaIcEEESt8functionIFvN3mir6client10ConnectionEEES7_IFvSt8weak_ptrINS8_5scene7SessionEEEE;
+  extern "C++" {
+    miral::WindowInfo::shell_chrome*;
+    miral::WindowManagerTools::add_tree_to_workspace*;
+    miral::WindowManagerTools::create_workspace*;
+    miral::WindowManagerTools::drag_window*;
+    miral::WindowManagerTools::remove_tree_from_workspace*;
+    typeinfo?for?miral::ApplicationAuthorizer1;
+    vtable?for?miral::ApplicationAuthorizer1;
+  };
+} MIRAL_1.1;
+
+MIRAL_1.3 {
+global:
   extern "C++" {'''
 
 END_NEW_STANZA = '''  };
-} MIRAL_1.1;'''
+} MIRAL_1.2;'''
 
 def _print_report():
     print OLD_STANZAS

=== modified file 'test/CMakeLists.txt'
--- test/CMakeLists.txt	2017-02-10 16:48:00 +0000
+++ test/CMakeLists.txt	2017-02-15 17:24:17 +0000
@@ -56,7 +56,7 @@
     display_reconfiguration.cpp
     active_window.cpp
     raise_tree.cpp
-)
+    workspaces.cpp)
 
 target_link_libraries(miral-test
     ${MIRTEST_LDFLAGS}

=== modified file 'test/test_server.cpp'
--- test/test_server.cpp	2017-02-14 11:49:59 +0000
+++ test/test_server.cpp	2017-02-15 17:24:17 +0000
@@ -19,7 +19,6 @@
 #include "test_server.h"
 #include "../miral/basic_window_manager.h"
 
-#include <miral/canonical_window_manager.h>
 #include <miral/set_window_managment_policy.h>
 
 #include <mir_test_framework/executable_path.h>
@@ -48,19 +47,13 @@
 char const* dummy_args[2] = { "TestServer", nullptr };
 }
 
-struct miral::TestServer::TestWindowManagerPolicy : CanonicalWindowManagerPolicy
+miral::TestServer::TestWindowManagerPolicy::TestWindowManagerPolicy(
+    WindowManagerTools const& tools, TestServer& test_fixture) :
+    CanonicalWindowManagerPolicy{tools}
 {
-    TestWindowManagerPolicy(WindowManagerTools const& tools, TestServer& test_fixture) :
-        CanonicalWindowManagerPolicy{tools}
-    {
-        test_fixture.tools = tools;
-        test_fixture.policy = this;
-    }
-
-    bool handle_keyboard_event(MirKeyboardEvent const*) override { return false; }
-    bool handle_pointer_event(MirPointerEvent const*) override { return false; }
-    bool handle_touch_event(MirTouchEvent const*) override { return false; }
-};
+    test_fixture.tools = tools;
+    test_fixture.policy = this;
+}
 
 miral::TestServer::TestServer() :
     runner{1, dummy_args}
@@ -70,6 +63,12 @@
     add_to_environment("MIR_SERVER_NO_FILE", "on");
 }
 
+auto miral::TestServer::build_window_manager_policy(WindowManagerTools const& tools)
+-> std::unique_ptr<TestWindowManagerPolicy>
+{
+    return std::make_unique<TestWindowManagerPolicy>(tools, *this);
+}
+
 void miral::TestServer::SetUp()
 {
 #if MIR_SERVER_VERSION < MIR_VERSION_NUMBER(0, 25, 0)
@@ -114,7 +113,7 @@
 
                             auto builder = [this](WindowManagerTools const& tools) -> std::unique_ptr<miral::WindowManagementPolicy>
                                 {
-                                    return std::make_unique<TestWindowManagerPolicy>(tools, *this);
+                                    return build_window_manager_policy(tools);
                                 };
 
                             auto wm = std::make_shared<miral::BasicWindowManager>(focus_controller, display_layout, persistent_surface_store, builder);

=== modified file 'test/test_server.h'
--- test/test_server.h	2017-02-14 11:49:59 +0000
+++ test/test_server.h	2017-02-15 17:24:17 +0000
@@ -21,6 +21,7 @@
 
 #include <mir/client/connection.h>
 
+#include <miral/canonical_window_manager.h>
 #include <miral/runner.h>
 #include <miral/window_manager_tools.h>
 
@@ -63,9 +64,10 @@
     void invoke_tools(std::function<void(WindowManagerTools& tools)> const& f);
     void invoke_window_manager(std::function<void(mir::shell::WindowManager& wm)> const& f);
 
-private:
     struct TestWindowManagerPolicy;
+    virtual auto build_window_manager_policy(WindowManagerTools const& tools) -> std::unique_ptr<TestWindowManagerPolicy>;
 
+private:
     WindowManagerTools tools{nullptr};
     WindowManagementPolicy* policy{nullptr};
     std::weak_ptr<mir::shell::WindowManager> window_manager;
@@ -74,6 +76,16 @@
     std::condition_variable started;
     mir::Server* server_running{nullptr};
 };
+
+struct TestServer::TestWindowManagerPolicy : CanonicalWindowManagerPolicy
+{
+    TestWindowManagerPolicy(WindowManagerTools const& tools, TestServer& test_fixture);
+
+    bool handle_keyboard_event(MirKeyboardEvent const*) override { return false; }
+    bool handle_pointer_event(MirPointerEvent const*) override { return false; }
+    bool handle_touch_event(MirTouchEvent const*) override { return false; }
+};
+
 }
 
 #endif //MIRAL_TEST_SERVER_H

=== added file 'test/workspaces.cpp'
--- test/workspaces.cpp	1970-01-01 00:00:00 +0000
+++ test/workspaces.cpp	2017-02-15 17:24:17 +0000
@@ -0,0 +1,603 @@
+/*
+ * Copyright © 2017 Canonical Ltd.
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 3,
+ * as published by the Free Software Foundation.
+ *
+ * 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/>.
+ *
+ * Authored by: Alan Griffiths <[e-mail]>
+ */
+
+#include <miral/workspace_policy.h>
+#include <miral/window_manager_tools.h>
+
+#include <mir/client/window.h>
+#include <mir/client/window_spec.h>
+#include <mir_toolkit/mir_buffer_stream.h>
+
+#include "test_server.h"
+
+#include <gmock/gmock.h>
+#include <mir/test/signal.h>
+
+
+using namespace testing;
+using namespace mir::client;
+using namespace std::chrono_literals;
+using miral::WindowManagerTools;
+
+namespace
+{
+#if MIR_CLIENT_VERSION <= MIR_VERSION_NUMBER(3, 4, 0)
+auto const mir_window_get_buffer_stream = mir_surface_get_buffer_stream;
+auto const mir_window_set_state = mir_surface_set_state;
+#endif
+
+std::string const top_level{"top level"};
+std::string const dialog{"dialog"};
+std::string const tip{"tip"};
+std::string const a_window{"a window"};
+std::string const another_window{"another window"};
+
+struct Workspaces;
+
+struct WorkspacesWindowManagerPolicy : miral::TestServer::TestWindowManagerPolicy, miral::WorkspacePolicy
+{
+    WorkspacesWindowManagerPolicy(WindowManagerTools const& tools, Workspaces& test_fixture);
+    ~WorkspacesWindowManagerPolicy();
+
+    void advise_new_window(miral::WindowInfo const& window_info) override;
+
+    MOCK_METHOD2(advise_adding_to_workspace,
+                 void(std::shared_ptr<miral::Workspace> const&, std::vector<miral::Window> const&));
+
+    MOCK_METHOD2(advise_removing_from_workspace,
+                 void(std::shared_ptr<miral::Workspace> const&, std::vector<miral::Window> const&));
+
+    MOCK_METHOD1(advise_focus_gained, void(miral::WindowInfo const&));
+
+    Workspaces& test_fixture;
+};
+
+struct Workspaces : public miral::TestServer
+{
+    auto create_window(std::string const& name) -> Window
+    {
+        auto const window = WindowSpec::for_normal_window(client_connection, 50, 50, mir_pixel_format_argb_8888)
+            .set_buffer_usage(mir_buffer_usage_software)
+            .set_name(name.c_str())
+            .create_window();
+
+        client_windows[name] = window;
+        mir_buffer_stream_swap_buffers_sync(mir_window_get_buffer_stream(window));
+
+        return window;
+    }
+
+    auto create_tip(std::string const& name, Window const& parent) -> Window
+    {
+        MirRectangle aux_rect{10, 10, 10, 10};
+        auto const window = WindowSpec::for_tip(client_connection, 50, 50, mir_pixel_format_argb_8888, parent,
+                                                &aux_rect, mir_edge_attachment_any)
+            .set_buffer_usage(mir_buffer_usage_software)
+            .set_name(name.c_str())
+            .create_window();
+
+        client_windows[name] = window;
+        mir_buffer_stream_swap_buffers_sync(mir_window_get_buffer_stream(window));
+
+        return window;
+    }
+
+    auto create_dialog(std::string const& name, Window const& parent) -> Window
+    {
+        auto const window = WindowSpec::for_dialog(client_connection, 50, 50, mir_pixel_format_argb_8888, parent)
+            .set_buffer_usage(mir_buffer_usage_software)
+            .set_name(name.c_str())
+            .create_window();
+
+        client_windows[name] = window;
+        mir_buffer_stream_swap_buffers_sync(mir_window_get_buffer_stream(window));
+
+        return window;
+    }
+
+    auto create_workspace() -> std::shared_ptr<miral::Workspace>
+    {
+        std::shared_ptr<miral::Workspace> result;
+
+        invoke_tools([&](WindowManagerTools& tools)
+            { result = tools.create_workspace(); });
+
+        return result;
+    }
+
+    void SetUp() override
+    {
+        miral::TestServer::SetUp();
+        EXPECT_CALL(policy(), advise_adding_to_workspace(_, _)).Times(AnyNumber());
+        EXPECT_CALL(policy(), advise_removing_from_workspace(_, _)).Times(AnyNumber());
+        EXPECT_CALL(policy(), advise_focus_gained(_)).Times(AnyNumber());
+
+        client_connection  = connect_client("Workspaces");
+        create_window(top_level);
+        create_dialog(dialog, client_windows[top_level]);
+        create_tip(tip, client_windows[dialog]);
+
+        EXPECT_THAT(client_windows.size(), Eq(3u));
+        EXPECT_THAT(server_windows.size(), Eq(3u));
+    }
+
+    void TearDown() override
+    {
+        client_windows.clear();
+        client_connection.reset();
+        miral::TestServer::TearDown();
+    }
+
+    Connection client_connection;
+
+    auto server_window(std::string const& key) -> miral::Window
+    {
+        std::lock_guard<decltype(mutex)> lock{mutex};
+        return server_windows[key];
+    }
+
+    auto client_window(std::string const& key) -> Window&
+    {
+        return client_windows[key];
+    }
+
+    auto windows_in_workspace(std::shared_ptr<miral::Workspace> const& workspace) -> std::vector<miral::Window>
+    {
+        std::vector<miral::Window> result;
+
+        auto enumerate = [&result](miral::Window const& window)
+            {
+                result.push_back(window);
+            };
+
+        invoke_tools([&](WindowManagerTools& tools)
+            { tools.for_each_window_in_workspace(workspace, enumerate); });
+
+        return result;
+    }
+
+    auto workspaces_containing_window(miral::Window const& window) -> std::vector<std::shared_ptr<miral::Workspace>>
+    {
+        std::vector<std::shared_ptr<miral::Workspace>> result;
+
+        auto enumerate = [&result](std::shared_ptr<miral::Workspace> const& workspace)
+            {
+                result.push_back(workspace);
+            };
+
+        invoke_tools([&](WindowManagerTools& tools)
+            { tools.for_each_workspace_containing(window, enumerate); });
+
+        return result;
+    }
+
+    auto policy() -> WorkspacesWindowManagerPolicy&
+    {
+        if (!the_policy) throw std::logic_error("the_policy isn't valid");
+        return *the_policy;
+    }
+
+private:
+    std::mutex mutable mutex;
+    std::map<std::string, Window> client_windows;
+    std::map<std::string, miral::Window> server_windows;
+    WorkspacesWindowManagerPolicy* the_policy{nullptr};
+
+    friend struct WorkspacesWindowManagerPolicy;
+
+    auto build_window_manager_policy(WindowManagerTools const& tools)
+    -> std::unique_ptr<TestWindowManagerPolicy> override
+    {
+        return std::make_unique<WorkspacesWindowManagerPolicy>(tools, *this);
+    }
+};
+
+WorkspacesWindowManagerPolicy::WorkspacesWindowManagerPolicy(WindowManagerTools const& tools, Workspaces& test_fixture) :
+TestWindowManagerPolicy(tools, test_fixture), test_fixture{test_fixture}
+{
+    test_fixture.the_policy = this;
+}
+
+WorkspacesWindowManagerPolicy::~WorkspacesWindowManagerPolicy()
+{
+    test_fixture.the_policy = nullptr;
+}
+
+
+void WorkspacesWindowManagerPolicy::advise_new_window(miral::WindowInfo const& window_info)
+{
+    miral::TestServer::TestWindowManagerPolicy::advise_new_window(window_info);
+
+    std::lock_guard<decltype(test_fixture.mutex)> lock{test_fixture.mutex};
+    test_fixture.server_windows[window_info.name()] = window_info.window();
+}
+}
+
+TEST_F(Workspaces, before_a_tree_is_added_to_workspace_it_is_empty)
+{
+    auto const workspace = create_workspace();
+
+    EXPECT_THAT(windows_in_workspace(workspace).size(), Eq(0u));
+}
+
+TEST_F(Workspaces, when_a_tree_is_added_to_workspace_all_surfaces_in_tree_are_added)
+{
+    auto const workspace = create_workspace();
+    invoke_tools([&, this](WindowManagerTools& tools)
+        { tools.add_tree_to_workspace(server_window(dialog), workspace); });
+
+    EXPECT_THAT(windows_in_workspace(workspace).size(), Eq(3u));
+}
+
+TEST_F(Workspaces, when_a_tree_is_removed_from_workspace_all_surfaces_in_tree_are_removed)
+{
+    auto const workspace = create_workspace();
+    invoke_tools([&, this](WindowManagerTools& tools)
+        { tools.add_tree_to_workspace(server_window(dialog), workspace); });
+
+    invoke_tools([&, this](WindowManagerTools& tools)
+        { tools.remove_tree_from_workspace(server_window(tip), workspace); });
+
+    EXPECT_THAT(windows_in_workspace(workspace).size(), Eq(0u));
+}
+
+TEST_F(Workspaces, given_a_tree_in_a_workspace_when_another_tree_is_added_and_removed_from_workspace_the_original_tree_remains)
+{
+    auto const workspace = create_workspace();
+    auto const original_tree = "original_tree";
+    auto const client_window = create_window(original_tree);
+    auto const original_window= server_window(original_tree);
+
+    invoke_tools([&, this](WindowManagerTools& tools)
+        { tools.add_tree_to_workspace(original_window, workspace); });
+
+    invoke_tools([&, this](WindowManagerTools& tools)
+        { tools.add_tree_to_workspace(server_window(top_level), workspace); });
+    invoke_tools([&, this](WindowManagerTools& tools)
+        { tools.remove_tree_from_workspace(server_window(top_level), workspace); });
+
+    EXPECT_THAT(windows_in_workspace(workspace), ElementsAre(original_window));
+}
+
+TEST_F(Workspaces, when_a_tree_is_added_to_a_workspace_all_surfaces_are_contained_in_the_workspace)
+{
+    auto const workspace = create_workspace();
+    invoke_tools([&, this](WindowManagerTools& tools)
+        { tools.add_tree_to_workspace(server_window(dialog), workspace); });
+
+    EXPECT_THAT(workspaces_containing_window(server_window(top_level)), ElementsAre(workspace));
+    EXPECT_THAT(workspaces_containing_window(server_window(dialog)), ElementsAre(workspace));
+    EXPECT_THAT(workspaces_containing_window(server_window(tip)), ElementsAre(workspace));
+}
+
+
+TEST_F(Workspaces, when_a_tree_is_added_to_a_workspaces_twice_surfaces_are_contained_in_one_workspace)
+{
+    auto const workspace = create_workspace();
+    invoke_tools([&, this](WindowManagerTools& tools)
+        {
+            tools.add_tree_to_workspace(server_window(dialog), workspace);
+            tools.add_tree_to_workspace(server_window(dialog), workspace);
+        });
+
+    EXPECT_THAT(workspaces_containing_window(server_window(top_level)), ElementsAre(workspace));
+    EXPECT_THAT(workspaces_containing_window(server_window(dialog)), ElementsAre(workspace));
+    EXPECT_THAT(workspaces_containing_window(server_window(tip)), ElementsAre(workspace));
+
+    EXPECT_THAT(workspaces_containing_window(server_window(top_level)).size(), Eq(1u));
+    EXPECT_THAT(workspaces_containing_window(server_window(dialog)).size(), Eq(1u));
+    EXPECT_THAT(workspaces_containing_window(server_window(tip)).size(), Eq(1u));
+}
+
+TEST_F(Workspaces, when_a_tree_is_added_to_two_workspaces_all_surfaces_are_contained_in_two_workspaces)
+{
+    auto const workspace1 = create_workspace();
+    auto const workspace2 = create_workspace();
+    invoke_tools([&, this](WindowManagerTools& tools)
+        {
+            tools.add_tree_to_workspace(server_window(dialog), workspace1);
+            tools.add_tree_to_workspace(server_window(dialog), workspace2);
+        });
+
+    EXPECT_THAT(workspaces_containing_window(server_window(top_level)).size(), Eq(2u));
+    EXPECT_THAT(workspaces_containing_window(server_window(dialog)).size(), Eq(2u));
+    EXPECT_THAT(workspaces_containing_window(server_window(tip)).size(), Eq(2u));
+}
+
+TEST_F(Workspaces, when_workspace_is_closed_surfaces_are_no_longer_contained_in_it)
+{
+    auto const workspace1 = create_workspace();
+    auto workspace2 = create_workspace();
+    invoke_tools([&, this](WindowManagerTools& tools)
+        {
+            tools.add_tree_to_workspace(server_window(dialog), workspace1);
+            tools.add_tree_to_workspace(server_window(dialog), workspace2);
+        });
+
+    workspace2.reset();
+
+    EXPECT_THAT(workspaces_containing_window(server_window(top_level)), ElementsAre(workspace1));
+    EXPECT_THAT(workspaces_containing_window(server_window(dialog)), ElementsAre(workspace1));
+    EXPECT_THAT(workspaces_containing_window(server_window(tip)), ElementsAre(workspace1));
+
+    EXPECT_THAT(workspaces_containing_window(server_window(top_level)).size(), Eq(1u));
+    EXPECT_THAT(workspaces_containing_window(server_window(dialog)).size(), Eq(1u));
+    EXPECT_THAT(workspaces_containing_window(server_window(tip)).size(), Eq(1u));
+}
+
+TEST_F(Workspaces, when_a_tree_is_added_to_a_workspace_the_policy_is_notified)
+{
+    auto const workspace = create_workspace();
+
+    EXPECT_CALL(policy(), advise_adding_to_workspace(workspace,
+         ElementsAre(server_window(top_level), server_window(dialog), server_window(tip))));
+
+    invoke_tools([&, this](WindowManagerTools& tools)
+                     { tools.add_tree_to_workspace(server_window(dialog), workspace); });
+}
+
+TEST_F(Workspaces, when_a_tree_is_added_to_a_workspaces_twice_the_policy_is_notified_once)
+{
+    auto const workspace = create_workspace();
+
+    EXPECT_CALL(policy(), advise_adding_to_workspace(workspace,
+         ElementsAre(server_window(top_level), server_window(dialog), server_window(tip))));
+
+    invoke_tools([&, this](WindowManagerTools& tools)
+        {
+            tools.add_tree_to_workspace(server_window(dialog), workspace);
+            tools.add_tree_to_workspace(server_window(dialog), workspace);
+        });
+}
+
+TEST_F(Workspaces, when_a_tree_is_removed_from_a_workspace_the_policy_is_notified)
+{
+    auto const workspace = create_workspace();
+    invoke_tools([&, this](WindowManagerTools& tools)
+        { tools.add_tree_to_workspace(server_window(dialog), workspace); });
+
+    EXPECT_CALL(policy(), advise_removing_from_workspace(workspace,
+         ElementsAre(server_window(top_level), server_window(dialog), server_window(tip))));
+
+    invoke_tools([&, this](WindowManagerTools& tools)
+        { tools.remove_tree_from_workspace(server_window(tip), workspace); });
+}
+
+TEST_F(Workspaces, when_a_tree_is_removed_from_a_workspace_twice_the_policy_is_notified_once)
+{
+    auto const workspace = create_workspace();
+    invoke_tools([&, this](WindowManagerTools& tools)
+        { tools.add_tree_to_workspace(server_window(dialog), workspace); });
+
+    EXPECT_CALL(policy(), advise_removing_from_workspace(workspace,
+         ElementsAre(server_window(top_level), server_window(dialog), server_window(tip))));
+
+    invoke_tools([&, this](WindowManagerTools& tools)
+        {
+            tools.remove_tree_from_workspace(server_window(top_level), workspace);
+            tools.remove_tree_from_workspace(server_window(tip), workspace);
+        });
+}
+
+TEST_F(Workspaces, a_child_window_is_added_to_workspace_of_parent)
+{
+    auto const workspace = create_workspace();
+    invoke_tools([&, this](WindowManagerTools& tools)
+        { tools.add_tree_to_workspace(server_window(dialog), workspace); });
+
+    EXPECT_CALL(policy(), advise_adding_to_workspace(workspace, ElementsAre(_)));
+
+    create_dialog(a_window, client_window(top_level));
+}
+
+TEST_F(Workspaces, a_closing_window_is_removed_from_workspace)
+{
+    auto const workspace = create_workspace();
+    invoke_tools([&, this](WindowManagerTools& tools)
+        { tools.add_tree_to_workspace(server_window(dialog), workspace); });
+
+    create_dialog(a_window, client_window(dialog));
+
+    EXPECT_CALL(policy(), advise_removing_from_workspace(workspace, ElementsAre(server_window(a_window))));
+
+    client_window(a_window).reset();
+}
+
+TEST_F(Workspaces, when_a_window_in_a_workspace_closes_focus_remains_in_workspace)
+{
+    auto const workspace = create_workspace();
+
+    create_window(a_window);
+    create_window(another_window);
+
+    invoke_tools([&, this](WindowManagerTools& tools)
+        {
+            tools.add_tree_to_workspace(server_window(a_window), workspace);
+            tools.add_tree_to_workspace(server_window(another_window), workspace);
+
+            tools.select_active_window(server_window(dialog));
+            tools.select_active_window(server_window(a_window));
+        });
+
+    client_window(a_window).reset();
+
+    invoke_tools([&, this](WindowManagerTools& tools)
+    {
+        EXPECT_THAT(tools.active_window(), Eq(server_window(another_window)))
+            << "tools.active_window() . . . .: " << tools.info_for(tools.active_window()).name() << "\n"
+            << "server_window(another_window): " << tools.info_for(server_window(another_window)).name();
+    });
+}
+
+TEST_F(Workspaces, with_two_applications_when_a_window_in_a_workspace_closes_focus_remains_in_workspace)
+{
+    auto const workspace = create_workspace();
+
+    create_window(another_window);
+
+    {
+        auto const another_app = connect_client("another app");
+        auto const window = WindowSpec::for_normal_window(another_app, 50, 50, mir_pixel_format_argb_8888)
+            .set_buffer_usage(mir_buffer_usage_software)
+            .set_name(a_window.c_str())
+            .create_window();
+
+        mir_buffer_stream_swap_buffers_sync(mir_window_get_buffer_stream(window));
+
+        invoke_tools([&, this](WindowManagerTools& tools)
+            {
+                tools.add_tree_to_workspace(server_window(top_level), workspace);
+                tools.add_tree_to_workspace(server_window(a_window), workspace);
+            });
+    }
+
+    invoke_tools([&, this](WindowManagerTools& tools)
+        {
+            EXPECT_THAT(tools.active_window(), Eq(server_window(dialog)))
+                << "tools.active_window(): " << tools.info_for(tools.active_window()).name() << "\n"
+                << "server_window(dialog): " << tools.info_for(server_window(dialog)).name();
+        });
+}
+
+TEST_F(Workspaces, when_a_window_in_a_workspace_hides_focus_remains_in_workspace)
+{
+    auto const workspace = create_workspace();
+
+    create_window(a_window);
+    create_window(another_window);
+
+    invoke_tools([&, this](WindowManagerTools& tools)
+        {
+            tools.add_tree_to_workspace(server_window(a_window), workspace);
+            tools.add_tree_to_workspace(server_window(another_window), workspace);
+
+            tools.select_active_window(server_window(dialog));
+            tools.select_active_window(server_window(a_window));
+        });
+
+    mir::test::Signal focus_changed;
+    EXPECT_CALL(policy(), advise_focus_gained(_)).WillOnce(InvokeWithoutArgs([&]{ focus_changed.raise(); }));
+
+    mir_window_set_state(client_window(a_window), mir_window_state_hidden);
+
+    EXPECT_TRUE(focus_changed.wait_for(1s));
+
+    invoke_tools([&, this](WindowManagerTools& tools)
+    {
+        EXPECT_THAT(tools.active_window(), Eq(server_window(another_window)))
+            << "tools.active_window() . . . .: " << tools.info_for(tools.active_window()).name() << "\n"
+            << "server_window(another_window): " << tools.info_for(server_window(another_window)).name();
+    });
+}
+
+
+TEST_F(Workspaces, with_two_applications_when_a_window_in_a_workspace_hides_focus_remains_in_workspace)
+{
+    auto const workspace = create_workspace();
+
+    create_window(another_window);
+
+    auto const another_app = connect_client("another app");
+    auto const window = WindowSpec::for_normal_window(another_app, 50, 50, mir_pixel_format_argb_8888)
+        .set_buffer_usage(mir_buffer_usage_software)
+        .set_name(a_window.c_str())
+        .create_window();
+
+    mir_buffer_stream_swap_buffers_sync(mir_window_get_buffer_stream(window));
+
+    invoke_tools([&, this](WindowManagerTools& tools)
+        {
+            tools.add_tree_to_workspace(server_window(top_level), workspace);
+            tools.add_tree_to_workspace(server_window(a_window), workspace);
+        });
+
+
+    mir::test::Signal focus_changed;
+    EXPECT_CALL(policy(), advise_focus_gained(_)).WillOnce(InvokeWithoutArgs([&]{ focus_changed.raise(); }));
+
+    mir_window_set_state(window, mir_window_state_hidden);
+
+    EXPECT_TRUE(focus_changed.wait_for(1s));
+
+    invoke_tools([&, this](WindowManagerTools& tools)
+        {
+            EXPECT_THAT(tools.active_window(), Eq(server_window(dialog)))
+                << "tools.active_window(): " << tools.info_for(tools.active_window()).name() << "\n"
+                << "server_window(dialog): " << tools.info_for(server_window(dialog)).name();
+        });
+
+    Mock::VerifyAndClearExpectations(&policy()); // before shutdown
+}
+
+TEST_F(Workspaces, focus_next_within_application_keeps_focus_in_workspace)
+{
+    auto const workspace = create_workspace();
+
+    create_window(another_window);
+    create_window(a_window);
+
+    invoke_tools([&, this](WindowManagerTools& tools)
+        {
+            tools.add_tree_to_workspace(server_window(a_window), workspace);
+            tools.add_tree_to_workspace(server_window(dialog), workspace);
+
+            tools.focus_next_within_application();
+
+            EXPECT_THAT(tools.active_window(), Eq(server_window(dialog)))
+                << "tools.active_window(): " << tools.info_for(tools.active_window()).name() << "\n"
+                << "server_window(dialog): " << tools.info_for(server_window(dialog)).name();
+
+            tools.focus_next_within_application();
+
+            EXPECT_THAT(tools.active_window(), Eq(server_window(a_window)))
+                << "tools.active_window(). : " << tools.info_for(tools.active_window()).name() << "\n"
+                << "server_window(a_window): " << tools.info_for(server_window(a_window)).name();
+        });
+}
+
+TEST_F(Workspaces, focus_next_application_keeps_focus_in_workspace)
+{
+    auto const workspace = create_workspace();
+    create_window(another_window);
+
+    auto const another_app = connect_client("another app");
+    auto const window = WindowSpec::for_normal_window(another_app, 50, 50, mir_pixel_format_argb_8888)
+        .set_buffer_usage(mir_buffer_usage_software)
+        .set_name(a_window.c_str())
+        .create_window();
+
+    mir_buffer_stream_swap_buffers_sync(mir_window_get_buffer_stream(window));
+
+    invoke_tools([&, this](WindowManagerTools& tools)
+        {
+            tools.add_tree_to_workspace(server_window(top_level), workspace);
+            tools.add_tree_to_workspace(server_window(a_window), workspace);
+
+            tools.focus_next_application();
+
+            EXPECT_THAT(tools.active_window(), Eq(server_window(dialog)))
+                << "tools.active_window(): " << tools.info_for(tools.active_window()).name() << "\n"
+                << "server_window(dialog): " << tools.info_for(server_window(dialog)).name();
+
+            tools.focus_next_application();
+
+            EXPECT_THAT(tools.active_window(), Eq(server_window(a_window)))
+                << "tools.active_window(). : " << tools.info_for(tools.active_window()).name() << "\n"
+                << "server_window(a_window): " << tools.info_for(server_window(a_window)).name();
+        });
+}