Mir

Merge lp:~alan-griffiths/mir/placement-notification into lp:mir

placement-notification
Merge into development-branch

Proposed by Alan Griffiths on 2016-09-13

Status:	Merged
Approved by:	Alan Griffiths on 2016-09-15
Approved revision:	3707
Merged at revision:	3702
Proposed branch:	lp:~alan-griffiths/mir/placement-notification
Merge into:	lp:mir
Diff against target:	785 lines (+339/-8) 31 files modified include/client/mir/event_printer.h (+2/-1) include/client/mir/events/event_builders.h (+4/-0) include/client/mir_toolkit/events/event.h (+13/-1) include/client/mir_toolkit/events/surface_placement.h (+47/-0) include/server/mir/scene/null_surface_observer.h (+1/-0) include/server/mir/scene/surface.h (+2/-0) include/server/mir/scene/surface_observer.h (+1/-0) include/test/mir/test/doubles/stub_surface.h (+1/-0) src/client/event.cpp (+12/-0) src/client/event_printer.cpp (+14/-1) src/client/events/event_builders.cpp (+18/-3) src/client/rpc/mir_protobuf_rpc_channel.cpp (+7/-1) src/client/symbols.map (+3/-1) src/common/events/CMakeLists.txt (+1/-0) src/common/events/event.cpp (+7/-0) src/common/events/surface_placement_event.cpp (+50/-0) src/common/symbols.map (+5/-0) src/include/common/mir/events/event.h (+2/-0) src/include/common/mir/events/surface_placement_event.h (+40/-0) src/include/server/mir/scene/surface_event_source.h (+1/-0) src/include/server/mir/scene/surface_observers.h (+1/-0) src/server/scene/basic_surface.cpp (+12/-0) src/server/scene/basic_surface.h (+1/-0) src/server/scene/legacy_surface_change_notification.cpp (+4/-0) src/server/scene/legacy_surface_change_notification.h (+1/-0) src/server/scene/null_surface_observer.cpp (+1/-0) src/server/scene/surface_event_source.cpp (+5/-0) src/server/symbols.map (+2/-0) tests/acceptance-tests/test_custom_window_management.cpp (+77/-0) tests/include/mir/test/doubles/stub_scene_surface.h (+1/-0) tests/mir_test_framework/stub_surface.cpp (+3/-0)
To merge this branch:	bzr merge lp:~alan-griffiths/mir/placement-notification
Related bugs:	Link a bug report

Reviewer	Review Type	Date Requested	Status
Mir CI Bot	continuous-integration		Approve on 2016-09-15
Kevin DuBois (community)			Approve on 2016-09-15
Gerry Boland			Abstain on 2016-09-15
Chris Halse Rogers		2016-09-13	Approve on 2016-09-15
Review via email: mp+305599@code.launchpad.net

Commit Message

Plumb relative placement notifications through from a surface to the client callback

Description of the Change

Plumb relative placement notifications through from a surface to the client callback.

This doesn't contain the window management logic to generate the notification, but provided the infrastructure needed to deliver it to the client.

Mir CI Bot (mir-ci-bot) wrote on 2016-09-13:

Click here to trigger a rebuild:
https://mir-jenkins.ubuntu.com/job/mir-ci/1706/rebuild

review: Approve (continuous-integration)

Alan Griffiths (alan-griffiths) wrote on 2016-09-14:

There's an implementation of the window-management side of this in lp:~alan-griffiths/miral/placement-notification/

Mir CI Bot (mir-ci-bot) wrote on 2016-09-14:

Click here to trigger a rebuild:
https://mir-jenkins.ubuntu.com/job/mir-ci/1713/rebuild

review: Approve (continuous-integration)

Chris Halse Rogers (raof) wrote on 2016-09-14:

Is there a reason we're sending a rectangle rather than just the top-left corner coordinates? The client already knows the size of the surface.

review: Needs Information

Kevin DuBois (kdub) wrote on 2016-09-14:

The client knows the size via the 'resize' callback... I think it would be clearer if it was told its 'placement' rather than 'size' (so, I'd rather deprecate using 'resize' in favor of placement, which contains x/y and size)

Chris Halse Rogers (raof) wrote on 2016-09-14:

Well, it knows its size because that's the size of the MirSurface that
got created.

And ‘placement’ is strictly for parent-relatively-positioned
surfaces - we'd still need a resize event (or most placement events
would contain a meaningless (0,0) for top-left).

Kevin DuBois (kdub) wrote on 2016-09-14:

needs info:

I got a bit confused about what the placement was relevant to, I assume its relative to the current position, and this event is to confirm that the placement request occurred?

+ surface_placement_event.cpp ${PROJECT_SOURCE_DIR}/src/include/common/mir/events/surface_placement_event.h

why not include_directories?

review: Needs Information

Alan Griffiths (alan-griffiths) wrote on 2016-09-14:

> needs info:
>
> I got a bit confused about what the placement was relevant to, I assume its
> relative to the current position, and this event is to confirm that the
> placement request occurred?

placement requests are relative to the parent, and so is the result.

> + surface_placement_event.cpp
> ${PROJECT_SOURCE_DIR}/src/include/common/mir/events/surface_placement_event.h
>
> why not include_directories?

I don't understand the question, what has include_directories got to do with adding source files?

Alan Griffiths (alan-griffiths) wrote on 2016-09-14:

> Is there a reason we're sending a rectangle rather than just the top-left
> corner coordinates? The client already knows the size of the surface.

placement may or may not resize the surface depending on the request parameters and the parent position on the output. I think it simpler for the client to await exactly one event for the placement than to await what could be either one or two.

William Hua (attente) wrote on 2016-09-14:

> > Is there a reason we're sending a rectangle rather than just the top-left
> > corner coordinates? The client already knows the size of the surface.
>
> placement may or may not resize the surface depending on the request
> parameters and the parent position on the output. I think it simpler for the
> client to await exactly one event for the placement than to await what could
> be either one or two.

+1 for this

Can we also document what the rectangle is relative to? i.e. is it relative to the client-requested position before server-side flipping or after server-side flipping.

We might actually need two rectangles... The widgets in GTK expect both the final rectangle position as well as the intermediate position (after server-side flipping, but before server-side sliding within the display boundaries). I'm a bit uncertain as to whether or not a single rectangle is enough information to infer what GTK needs.

Alan Griffiths (alan-griffiths) wrote on 2016-09-14:

> Can we also document what the rectangle is relative to? i.e. is it relative to
> the client-requested position before server-side flipping or after server-side
> flipping.

Documented that it is relative to the parent surface.

> We might actually need two rectangles... The widgets in GTK expect both the
> final rectangle position as well as the intermediate position (after server-
> side flipping, but before server-side sliding within the display boundaries).
> I'm a bit uncertain as to whether or not a single rectangle is enough
> information to infer what GTK needs.

I'm not entirely clear what the objective of this is. As implemeted in Miral the server tries a series of transformations and selects the first satisfactory result. Some of these transformations flip, some flip twice, some resize, some slide and some combine the above. That

To provide "the intermediate" I'd need to know the rules for calculating it in each scenario. (And these will get more complex with the incorporation of the "anchored in parent" constraints.)

Mir CI Bot (mir-ci-bot) wrote on 2016-09-14:

Click here to trigger a rebuild:
https://mir-jenkins.ubuntu.com/job/mir-ci/1717/rebuild

review: Approve (continuous-integration)

Gerry Boland (gerboland) wrote on 2016-09-14:

Basic API looks suitable for Qt. But I am curious if a user repositions the surface, does the client get new SurfacePlacementEvents? Or is this just after the WM has initially sized & placed the child surface.

review: Needs Information

Alan Griffiths (alan-griffiths) wrote on 2016-09-14:

> Basic API looks suitable for Qt. But I am curious if a user repositions the
> surface, does the client get new SurfacePlacementEvents? Or is this just after
> the WM has initially sized & placed the child surface.

At present it is only providing a response to placement requests (either initial creation or clients applying a placement to an existing surface).

I don't expect users to be able to reposition e.g. menus (lp:1616818 notwithstanding). We would need to identify scenarios where it is appropriate to send notification of user actions.

Chris Halse Rogers (raof) wrote on 2016-09-15:

If toolkit authors want the extra info, sure.

+// auto const placement_event = mir::events::make_event(surface_id, placement_);

Old detritus left in?

Otherwise seems fine.

review: Approve

Alan Griffiths (alan-griffiths) wrote on 2016-09-15:

> +// auto const placement_event = mir::events::make_event(surface_id,
> placement_);
>
> Old detritus left in?

Fixed

Mir CI Bot (mir-ci-bot) wrote on 2016-09-15:

Click here to trigger a rebuild:
https://mir-jenkins.ubuntu.com/job/mir-ci/1730/rebuild

review: Approve (continuous-integration)

Gerry Boland (gerboland) on 2016-09-15:

review: Abstain

Kevin DuBois (kdub) wrote on 2016-09-15:

> > needs info:
> >
> > I got a bit confused about what the placement was relevant to, I assume its
> > relative to the current position, and this event is to confirm that the
> > placement request occurred?
>
> placement requests are relative to the parent, and so is the result.
>

Ack, and added to comments, thanks.

> > + surface_placement_event.cpp
> >
> ${PROJECT_SOURCE_DIR}/src/include/common/mir/events/surface_placement_event.h
> >
> > why not include_directories?
>
> I don't understand the question, what has include_directories got to do with
> adding source files?

Apparently adding the header thusly helps with some IDE's.

review: Approve

Mir CI Bot (mir-ci-bot) wrote on 2016-09-15:

review: Needs Fixing (continuous-integration)

Alan Griffiths (alan-griffiths) wrote on 2016-09-15:

15:09:21 11: [ FAILED ] NestedServer.animated_cursor_image_changes_are_forwarded_to_host
15:09:21 11: [ FAILED ] NestedServer.can_hide_the_host_cursor

lp:1523621

Mir CI Bot (mir-ci-bot) on 2016-09-15:

review: Approve (continuous-integration)

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk

Subscribers

People subscribed via source and target branches

to all changes:

Alan Griffiths

Emanuele Antonio Faraone

Gerry Boland

Mir development team

 === modified file 'include/client/mir/event_printer.h'
 --- include/client/mir/event_printer.h	2016-06-08 13:48:21 +0000
 +++ include/client/mir/event_printer.h	2016-09-15 08:21:15 +0000
@@ -1,5 +1,5 @@
  /*
-- * Copyright © 2015 Canonical Ltd.
++ * Copyright © 2015-2016 Canonical Ltd.
+  *
   * This program is free software: you can redistribute it and/or modify
   * it under the terms of the GNU Lesser General Public License version 3 as
@@ -48,6 +48,7 @@
  std::ostream& operator<<(std::ostream& out, MirKeymapEvent const& event);
  std::ostream& operator<<(std::ostream& out, MirSurfaceEvent const& event);
  std::ostream& operator<<(std::ostream& out, MirInputDeviceStateEvent const& event);
++std::ostream& operator<<(std::ostream& out, MirSurfacePlacementEvent const& event);
  std::ostream& operator<<(std::ostream& out, MirEvent const& event);
+ }
 === modified file 'include/client/mir/events/event_builders.h'
 --- include/client/mir/events/event_builders.h	2016-05-26 20:59:38 +0000
 +++ include/client/mir/events/event_builders.h	2016-09-15 08:21:15 +0000
@@ -23,6 +23,7 @@
  #include "mir/geometry/size.h"
  #include "mir/geometry/point.h"
++#include "mir/geometry/rectangle.h"
  #include "mir/frontend/surface_id.h"
  #include <memory>
@@ -57,6 +58,9 @@
      MirFormFactor form_factor,
      uint32_t id);
++/// Surface placement event
++EventUPtr make_event(frontend::SurfaceId const& surface_id, geometry::Rectangle placement);
++
  // Key event
  EventUPtr make_event(MirInputDeviceId device_id, std::chrono::nanoseconds timestamp,
      std::vector<uint8_t> const& cookie, MirKeyboardAction action, xkb_keysym_t key_code,
 === modified file 'include/client/mir_toolkit/events/event.h'
 --- include/client/mir_toolkit/events/event.h	2016-09-02 13:27:43 +0000
 +++ include/client/mir_toolkit/events/event.h	2016-09-15 08:21:15 +0000
@@ -1,5 +1,5 @@
  /*
-- * Copyright © 2014 Canonical Ltd.
++ * Copyright © 2014-2016 Canonical Ltd.
+  *
   * This program is free software: you can redistribute it and/or modify it
   * under the terms of the GNU Lesser General Public License version 3,
@@ -47,6 +47,7 @@
      mir_event_type_input_configuration,
      mir_event_type_surface_output,
      mir_event_type_input_device_state,
++    mir_event_type_surface_placement,
  } MirEventType;
  typedef struct MirSurfaceEvent MirSurfaceEvent;
@@ -59,6 +60,7 @@
  typedef struct MirInputConfigurationEvent MirInputConfigurationEvent;
  typedef struct MirSurfaceOutputEvent MirSurfaceOutputEvent;
  typedef struct MirInputDeviceStateEvent MirInputDeviceStateEvent;
++typedef struct MirSurfacePlacementEvent MirSurfacePlacementEvent;
  typedef struct MirCookie MirCookie;
@@ -211,6 +213,16 @@
   */
  MirInputDeviceStateEvent const* mir_event_get_input_device_state_event(MirEvent const* event);
++/**
++ * Retrieve the MirSurfacePlacementEvent associated with a MirEvent of
++ * type mir_event_type_surface_placement. The event signifies that the
++ * the server has fulfilled a request for relative surface placement.
++ *
++ * \param [in] event The event
++ * \return           The associated MirSurfacePlacementEvent
++ */
++MirSurfacePlacementEvent const* mir_event_get_surface_placement_event(MirEvent const* event);
++
  /*
   * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   * _________________________
 === added file 'include/client/mir_toolkit/events/surface_placement.h'
 --- include/client/mir_toolkit/events/surface_placement.h	1970-01-01 00:00:00 +0000
 +++ include/client/mir_toolkit/events/surface_placement.h	2016-09-15 08:21:15 +0000
@@ -0,0 +1,47 @@
++/*
++ * Copyright © 2016 Canonical Ltd.
++ *
++ * This program is free software: you can redistribute it and/or modify it
++ * under the terms of the GNU Lesser 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 Lesser General Public License for more details.
++ *
++ * You should have received a copy of the GNU Lesser General Public License
++ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
++ *
++ * Authored by: Alan Griffiths <alan@octopull.co.uk>
++ */
++
++#ifndef MIR_TOOLKIT_SURFACE_PLACEMENT_H_
++#define MIR_TOOLKIT_SURFACE_PLACEMENT_H_
++
++#include <mir_toolkit/client_types.h>
++
++#ifdef __cplusplus
++/**
++ * \addtogroup mir_toolkit
++ * @{
++ */
++extern "C" {
++#endif
++
++typedef struct MirSurfacePlacementEvent MirSurfacePlacementEvent;
++
++/**
++ * Retrieve the relative position from a placement notification
++ *
++ * \param [in] event  The placement event
++ * \return            The position relative to the parent surface
++ */
++MirRectangle mir_surface_placement_get_relative_position(MirSurfacePlacementEvent const* event);
++
++#ifdef __cplusplus
++}
++/**@}*/
++#endif
++
++#endif //MIR_TOOLKIT_SURFACE_PLACEMENT_H_
 === modified file 'include/server/mir/scene/null_surface_observer.h'
 --- include/server/mir/scene/null_surface_observer.h	2016-08-02 19:44:59 +0000
 +++ include/server/mir/scene/null_surface_observer.h	2016-09-15 08:21:15 +0000
@@ -45,6 +45,7 @@
      void keymap_changed(MirInputDeviceId id, std::string const& model, std::string const& layout, std::string const& variant, std::string const& options) override;
      void renamed(char const* name) override;
      void cursor_image_removed() override;
++    void placed_relative(geometry::Rectangle const& placement) override;
  protected:
      NullSurfaceObserver(NullSurfaceObserver const&) = delete;
 === modified file 'include/server/mir/scene/surface.h'
 --- include/server/mir/scene/surface.h	2016-08-23 03:56:40 +0000
 +++ include/server/mir/scene/surface.h	2016-09-15 08:21:15 +0000
@@ -118,6 +118,8 @@
      virtual void set_confine_pointer_state(MirPointerConfinementState state) = 0;
      virtual MirPointerConfinementState confine_pointer_state() const = 0;
++
++    virtual void placed_relative(geometry::Rectangle const& placement) = 0;
  };
+ }
+ }
 === modified file 'include/server/mir/scene/surface_observer.h'
 --- include/server/mir/scene/surface_observer.h	2016-08-02 19:44:59 +0000
 +++ include/server/mir/scene/surface_observer.h	2016-09-15 08:21:15 +0000
@@ -60,6 +60,7 @@
                                  std::string const& variant, std::string const& options) = 0;
      virtual void renamed(char const* name) = 0;
      virtual void cursor_image_removed() = 0;
++    virtual void placed_relative(geometry::Rectangle const& placement) = 0;
  protected:
      SurfaceObserver() = default;
 === modified file 'include/test/mir/test/doubles/stub_surface.h'
 --- include/test/mir/test/doubles/stub_surface.h	2016-06-27 20:44:49 +0000
 +++ include/test/mir/test/doubles/stub_surface.h	2016-09-15 08:21:15 +0000
@@ -72,6 +72,7 @@
      void rename(std::string const& title) override;
      void set_confine_pointer_state(MirPointerConfinementState state) override;
      MirPointerConfinementState confine_pointer_state() const override;
++    void placed_relative(geometry::Rectangle const& placement) override;
  };
+ }
+ }
 === modified file 'src/client/event.cpp'
 --- src/client/event.cpp	2016-06-10 16:12:34 +0000
 +++ src/client/event.cpp	2016-09-15 08:21:15 +0000
@@ -23,12 +23,14 @@
  #include "mir_toolkit/events/event.h"
  #include "mir/events/event_private.h"
++#include "mir/events/surface_placement_event.h"
  #include "mir_toolkit/events/surface_event.h"
  #include "mir_toolkit/events/resize_event.h"
  #include "mir_toolkit/events/prompt_session_event.h"
  #include "mir_toolkit/events/orientation_event.h"
  #include "mir_toolkit/events/input_device_state_event.h"
++#include "mir_toolkit/events/surface_placement.h"
  #include <cstdlib>
  #include <cstring>
@@ -340,6 +342,16 @@
      return ev->device_pointer_buttons(index);
+ }
++MirSurfacePlacementEvent const* mir_event_get_surface_placement_event(MirEvent const* event)
++{
++    return event->to_surface_placement();
++}
++
++MirRectangle mir_surface_placement_get_relative_position(MirSurfacePlacementEvent const* event)
++{
++    return event->placement();
++}
++
  // TODO: Until we opaquify the MirEvent structure and add
  // a ref count ref is implemented as copy.
  MirEvent const* mir_event_ref(MirEvent const* ev)
 === modified file 'src/client/event_printer.cpp'
 --- src/client/event_printer.cpp	2016-06-08 13:48:21 +0000
 +++ src/client/event_printer.cpp	2016-09-15 08:21:15 +0000
@@ -1,5 +1,5 @@
  /*
-- * Copyright © 2015 Canonical Ltd.
++ * Copyright © 2015-2016 Canonical Ltd.
+  *
   * This program is free software: you can redistribute it and/or modify
   * it under the terms of the GNU Lesser General Public License version 3 as
@@ -17,6 +17,8 @@
   */
  #include "mir/event_printer.h"
++
++#include "mir/events/surface_placement_event.h"
  #include "mir/logging/input_timestamp.h"
  std::ostream& mir::operator<<(std::ostream& out, MirInputEventModifier modifier)
@@ -321,6 +323,16 @@
      return out << ')';
+ }
++std::ostream& mir::operator<<(std::ostream& out, MirSurfacePlacementEvent const& event)
++{
++    auto const& placement = event.placement();
++    return out << "surface_placement_event({"
++               << placement.left << ", "
++               << placement.top << ", "
++               << placement.width << ", "
++               << placement.height << "})";
++}
++
  std::ostream& mir::operator<<(std::ostream& out, MirInputDeviceStateEvent const& event)
+ {
      out << "input_device_state(ts="
@@ -367,6 +379,7 @@
          PRINT_EVENT(input);
          PRINT_EVENT(input_device_state);
          PRINT_EVENT(keymap);
++        PRINT_EVENT(surface_placement);
      case mir_event_type_prompt_session_state_change:
          return out << *mir_event_get_prompt_session_event(&event);
      default:
 === modified file 'src/client/events/event_builders.cpp'
 --- src/client/events/event_builders.cpp	2016-06-10 16:12:34 +0000
 +++ src/client/events/event_builders.cpp	2016-09-15 08:21:15 +0000
@@ -1,5 +1,5 @@
  /*
-- * Copyright © 2015 Canonical Ltd.
++ * Copyright © 2015-2016 Canonical Ltd.
+  *
   * This program is free software: you can redistribute it and/or modify it
   * under the terms of the GNU Lesser General Public License version 3,
@@ -16,12 +16,13 @@
   * Author: Robert Carr <robert.carr@canonical.com>
   */
++#include "mir/events/event_builders.h"
++
  #define MIR_LOG_COMPONENT "event-builders"
--
  #include "mir/log.h"
--#include "mir/events/event_builders.h"
  #include "mir/events/event_private.h"
++#include "mir/events/surface_placement_event.h"
  #include "mir/cookie/blob.h"
  #include "mir/input/xkb_mapper.h"
  #include "mir/input/keymap.h"
@@ -140,6 +141,20 @@
      return make_uptr_event(e);
+ }
++mir::EventUPtr mev::make_event(frontend::SurfaceId const& surface_id, geometry::Rectangle placement)
++{
++    auto e = new_event<MirSurfacePlacementEvent>();
++
++    e->set_id(surface_id.as_value());
++    e->set_placement({
++        placement.left().as_int(),
++        placement.top().as_int(),
++        placement.size.width.as_uint32_t(),
++        placement.size.height.as_uint32_t()});
++
++    return make_uptr_event(e);
++}
++
  namespace
+ {
  // Never exposed in old event, so lets avoid leaking it in to a header now.
 === modified file 'src/client/rpc/mir_protobuf_rpc_channel.cpp'
 --- src/client/rpc/mir_protobuf_rpc_channel.cpp	2016-08-03 06:48:47 +0000
 +++ src/client/rpc/mir_protobuf_rpc_channel.cpp	2016-09-15 08:21:15 +0000
@@ -1,5 +1,5 @@
  /*
-- * Copyright © 2012 Canonical Ltd.
++ * Copyright © 2012-2016 Canonical Ltd.
+  *
   * This program is free software: you can redistribute it and/or modify it
   * under the terms of the GNU Lesser General Public License version 3,
@@ -34,6 +34,7 @@
  #include "mir/events/event_builders.h"
  #include "mir/events/event_private.h"
  #include "mir/events/serialization.h"
++#include "mir/events/surface_placement_event.h"
  #include "mir_protobuf.pb.h"  // For Buffer frig
  #include "mir_protobuf_wire.pb.h"
@@ -398,6 +399,11 @@
                          if (auto map = surface_map.lock())
                              map->with_surface_do(mf::SurfaceId(e->to_surface_output()->surface_id()), send_e);
                          break;
++                    case mir_event_type_surface_placement:
++                        if (auto map = surface_map.lock())
++                            map->with_surface_do(mf::SurfaceId(e->to_surface_placement()->id()), send_e);
++                        break;
++
                      default:
                          event_sink->handle_event(*e);
+                     }
 === modified file 'src/client/symbols.map'
 --- src/client/symbols.map	2016-09-09 09:55:33 +0000
 +++ src/client/symbols.map	2016-09-15 08:21:15 +0000
@@ -420,10 +420,12 @@
  MIR_CLIENT_0.25 {  # New functions in Mir 0.25
    global:
      mir_connection_create_spec_for_tip;
--    mir_output_get_current_mode_index;
++    mir_event_get_surface_placement_event;
++    mir_output_get_current_mode_index;
      mir_output_get_preferred_mode_index;
      mir_output_get_subpixel_arrangement;
      mir_connection_cancel_base_display_configuration_preview;
++    mir_surface_placement_get_relative_position;
      mir_display_output_type_name;
      mir_output_type_name;
  } MIR_CLIENT_0.24;
 === modified file 'src/common/events/CMakeLists.txt'
 --- src/common/events/CMakeLists.txt	2016-06-02 05:33:50 +0000
 +++ src/common/events/CMakeLists.txt	2016-09-15 08:21:15 +0000
@@ -28,6 +28,7 @@
    orientation_event.cpp
    resize_event.cpp
    surface_output_event.cpp
++  surface_placement_event.cpp       ${PROJECT_SOURCE_DIR}/src/include/common/mir/events/surface_placement_event.h
+ )
  add_library(
 === modified file 'src/common/events/event.cpp'
 --- src/common/events/event.cpp	2016-06-10 16:12:34 +0000
 +++ src/common/events/event.cpp	2016-09-15 08:21:15 +0000
@@ -32,6 +32,7 @@
  #include "mir/events/surface_event.h"
  #include "mir/events/surface_output_event.h"
  #include "mir/events/input_device_state_event.h"
++#include "mir/events/surface_placement_event.h"
  MirEvent::MirEvent(MirEventType type) :
      type_(type)
@@ -64,6 +65,8 @@
          return to_keymap()->clone();
      case mir_event_type_input_device_state:
          return to_input_device_state()->clone();
++    case mir_event_type_surface_placement:
++        return mir::event::deep_copy<MirSurfacePlacementEvent>(this);
      case mir_event_type_input:
          break;
+     }
@@ -105,6 +108,8 @@
          return MirKeymapEvent::deserialize(bytes);
      case mir_event_type_input_device_state:
          return MirInputDeviceStateEvent::deserialize(bytes);
++    case mir_event_type_surface_placement:
++        return mir::event::deserialize_from<MirSurfacePlacementEvent>(bytes);
      case mir_event_type_input:
          break;
+     }
@@ -138,6 +143,8 @@
          return MirKeymapEvent::serialize(event);
      case mir_event_type_input_device_state:
          return MirInputDeviceStateEvent::serialize(event);
++    case mir_event_type_surface_placement:
++        return mir::event::serialize_from<MirSurfacePlacementEvent>(event);
      case mir_event_type_input:
          break;
+     }
 === added file 'src/common/events/surface_placement_event.cpp'
 --- src/common/events/surface_placement_event.cpp	1970-01-01 00:00:00 +0000
 +++ src/common/events/surface_placement_event.cpp	2016-09-15 08:21:15 +0000
@@ -0,0 +1,50 @@
++/*
++ * Copyright © 2016 Canonical Ltd.
++ *
++ * This program is free software: you can redistribute it and/or modify it
++ * under the terms of the GNU Lesser 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 Lesser General Public License for more details.
++ *
++ * You should have received a copy of the GNU Lesser General Public License
++ * along with this program. If not, see <http://www.gnu.org/licenses/>.
++ *
++ * Authored by: Alan Griffiths <alan@octopull.co.uk>
++ */
++
++#include "mir/events/surface_placement_event.h"
++
++MirSurfacePlacementEvent::MirSurfacePlacementEvent() :
++    MirEvent(mir_event_type_surface_placement)
++{
++}
++
++int MirSurfacePlacementEvent::id() const
++{
++    return id_;
++}
++
++void MirSurfacePlacementEvent::set_id(int const id)
++{
++    id_ = id;
++}
++
++MirRectangle MirSurfacePlacementEvent::placement() const
++{
++    return placement_;
++}
++
++void MirSurfacePlacementEvent::set_placement(MirRectangle const& placement)
++{
++    placement_ = placement;
++}
++
++MirSurfacePlacementEvent const* MirEvent::to_surface_placement() const
++{
++    return static_cast<MirSurfacePlacementEvent const*>(this);
++}
++
 === modified file 'src/common/symbols.map'
 --- src/common/symbols.map	2016-09-09 09:55:33 +0000
 +++ src/common/symbols.map	2016-09-15 08:21:15 +0000
@@ -390,6 +390,11 @@
  MIR_COMMON_0.25 {
    global:
      extern "C++" {
++      MirSurfacePlacementEvent::MirSurfacePlacementEvent*;
++      MirSurfacePlacementEvent::id*;
++      MirSurfacePlacementEvent::set_id*;
++      MirSurfacePlacementEvent::placement*;
++      MirSurfacePlacementEvent::set_placement*;
        mir::output_type_name*;
      };
  } MIR_COMMON_0.24;
 === modified file 'src/include/common/mir/events/event.h'
 --- src/include/common/mir/events/event.h	2016-05-26 02:12:27 +0000
 +++ src/include/common/mir/events/event.h	2016-09-15 08:21:15 +0000
@@ -61,6 +61,8 @@
      MirInputDeviceStateEvent* to_input_device_state();
      MirInputDeviceStateEvent const* to_input_device_state() const;
++    MirSurfacePlacementEvent const* to_surface_placement() const;
++
      MirEvent* clone() const;
      static mir::EventUPtr deserialize(std::string const& bytes);
 === added file 'src/include/common/mir/events/surface_placement_event.h'
 --- src/include/common/mir/events/surface_placement_event.h	1970-01-01 00:00:00 +0000
 +++ src/include/common/mir/events/surface_placement_event.h	2016-09-15 08:21:15 +0000
@@ -0,0 +1,40 @@
++/*
++ * Copyright © 2016 Canonical Ltd.
++ *
++ * This program is free software: you can redistribute it and/or modify it
++ * under the terms of the GNU Lesser 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 Lesser General Public License for more details.
++ *
++ * You should have received a copy of the GNU Lesser General Public License
++ * along with this program. If not, see <http://www.gnu.org/licenses/>.
++ *
++ * Authored by: Alan Griffiths <alan@octopull.co.uk>
++ */
++
++#ifndef MIR_SURFACE_PLACEMENT_EVENT_H
++#define MIR_SURFACE_PLACEMENT_EVENT_H
++
++#include "mir/events/event.h"
++#include "mir_toolkit/client_types.h"
++
++struct MirSurfacePlacementEvent : MirEvent
++{
++    MirSurfacePlacementEvent();
++
++    int id() const;
++    void set_id(int id);
++
++    MirRectangle placement() const;
++    void set_placement(MirRectangle const& placement);
++
++private:
++    int id_{0};
++    MirRectangle placement_;
++};
++
++#endif //MIR_SURFACE_PLACEMENT_EVENT_H
 === modified file 'src/include/server/mir/scene/surface_event_source.h'
 --- src/include/server/mir/scene/surface_event_source.h	2016-01-29 08:18:22 +0000
 +++ src/include/server/mir/scene/surface_event_source.h	2016-09-15 08:21:15 +0000
@@ -49,6 +49,7 @@
      void client_surface_close_requested() override;
      void keymap_changed(MirInputDeviceId id, std::string const& model, std::string const& layout,
                          std::string const& variant, std::string const& options) override;
++    void placed_relative(geometry::Rectangle const& placement) override;
  private:
      frontend::SurfaceId const id;
 === modified file 'src/include/server/mir/scene/surface_observers.h'
 --- src/include/server/mir/scene/surface_observers.h	2016-08-02 19:44:59 +0000
 +++ src/include/server/mir/scene/surface_observers.h	2016-09-15 08:21:15 +0000
@@ -49,6 +49,7 @@
                          std::string const& variant, std::string const& options) override;
      void renamed(char const*) override;
      void cursor_image_removed() override;
++    void placed_relative(geometry::Rectangle const& placement) override;
  };
+ }
 === modified file 'src/server/scene/basic_surface.cpp'
 --- src/server/scene/basic_surface.cpp	2016-08-24 02:09:08 +0000
 +++ src/server/scene/basic_surface.cpp	2016-09-15 08:21:15 +0000
@@ -134,6 +134,13 @@
          { observer->cursor_image_removed(); });
+ }
++void ms::SurfaceObservers::placed_relative(geometry::Rectangle const& placement)
++{
++    for_each([&](std::shared_ptr<SurfaceObserver> const& observer)
++                 { observer->placed_relative(placement); });
++}
++
++
  struct ms::CursorStreamImageAdapter
+ {
      CursorStreamImageAdapter(ms::BasicSurface &surface)
@@ -933,3 +940,8 @@
+ {
      return confine_pointer_state_;
+ }
++
++void ms::BasicSurface::placed_relative(geometry::Rectangle const& placement)
++{
++    observers.placed_relative(placement);
++}
 === modified file 'src/server/scene/basic_surface.h'
 --- src/server/scene/basic_surface.h	2016-08-24 02:09:08 +0000
 +++ src/server/scene/basic_surface.h	2016-09-15 08:21:15 +0000
@@ -150,6 +150,7 @@
      void set_confine_pointer_state(MirPointerConfinementState state) override;
      MirPointerConfinementState confine_pointer_state() const override;
++    void placed_relative(geometry::Rectangle const& placement) override;
  private:
      bool visible(std::unique_lock<std::mutex>&) const;
 === modified file 'src/server/scene/legacy_surface_change_notification.cpp'
 --- src/server/scene/legacy_surface_change_notification.cpp	2016-08-02 19:44:59 +0000
 +++ src/server/scene/legacy_surface_change_notification.cpp	2016-09-15 08:21:15 +0000
@@ -80,6 +80,10 @@
+ {
+ }
++void ms::LegacySurfaceChangeNotification::placed_relative(geometry::Rectangle const& /*placement*/)
++{
++}
++
  void ms::LegacySurfaceChangeNotification::reception_mode_set_to(mi::InputReceptionMode /*mode*/)
+ {
      notify_scene_change();
 === modified file 'src/server/scene/legacy_surface_change_notification.h'
 --- src/server/scene/legacy_surface_change_notification.h	2016-08-02 19:44:59 +0000
 +++ src/server/scene/legacy_surface_change_notification.h	2016-09-15 08:21:15 +0000
@@ -49,6 +49,7 @@
                          std::string const& variant, std::string const& options) override;
      void renamed(char const*) override;
      void cursor_image_removed() override;
++    void placed_relative(geometry::Rectangle const& placement) override;
  private:
      std::function<void()> const notify_scene_change;
 === modified file 'src/server/scene/null_surface_observer.cpp'
 --- src/server/scene/null_surface_observer.cpp	2016-08-02 19:44:59 +0000
 +++ src/server/scene/null_surface_observer.cpp	2016-09-15 08:21:15 +0000
@@ -39,3 +39,4 @@
+ }
  void ms::NullSurfaceObserver::renamed(char const*) {}
  void ms::NullSurfaceObserver::cursor_image_removed() {}
++void ms::NullSurfaceObserver::placed_relative(geometry::Rectangle const& /*placement*/)  {}
 === modified file 'src/server/scene/surface_event_source.cpp'
 --- src/server/scene/surface_event_source.cpp	2016-01-29 08:18:22 +0000
 +++ src/server/scene/surface_event_source.cpp	2016-09-15 08:21:15 +0000
@@ -87,3 +87,8 @@
+ {
      event_sink->handle_event(*mev::make_event(id, device_id, model, layout, variant, options));
+ }
++
++void ms::SurfaceEventSource::placed_relative(geometry::Rectangle const& placement)
++{
++    event_sink->handle_event(*mev::make_event(id, placement));
++}
 === modified file 'src/server/symbols.map'
 --- src/server/symbols.map	2016-08-26 19:01:27 +0000
 +++ src/server/symbols.map	2016-09-15 08:21:15 +0000
@@ -840,5 +840,7 @@
   global:
    extern "C++" {
      mir::Server::override_the_seat_report*;
++    mir::scene::NullSurfaceObserver::placed_relative*;
++    non-virtual?thunk?to?mir::scene::NullSurfaceObserver::placed_relative*;
    };
  } MIR_SERVER_0.24;
 === modified file 'tests/acceptance-tests/test_custom_window_management.cpp'
 --- tests/acceptance-tests/test_custom_window_management.cpp	2016-08-31 10:46:40 +0000
 +++ tests/acceptance-tests/test_custom_window_management.cpp	2016-09-15 08:21:15 +0000
@@ -18,6 +18,9 @@
  #include "mir/geometry/rectangle.h"
  #include "mir/scene/session.h"
++#include "mir_toolkit/events/surface_placement.h"
++#include "mir/events/event_builders.h"
++#include "mir/scene/surface.h"
  #include "mir_toolkit/mir_client_library.h"
@@ -517,3 +520,77 @@
      mir_surface_release_sync(parent);
      mir_connection_release(connection);
+ }
++
++namespace
++{
++struct PlacementCheck
++{
++    PlacementCheck(MirRectangle const& placement) : expected_rect{placement} {}
++
++    void check(MirSurfacePlacementEvent const* placement_event)
++    {
++        EXPECT_THAT(mir_surface_placement_get_relative_position(placement_event).top, Eq(expected_rect.top));
++        EXPECT_THAT(mir_surface_placement_get_relative_position(placement_event).left, Eq(expected_rect.left));
++        EXPECT_THAT(mir_surface_placement_get_relative_position(placement_event).height, Eq(expected_rect.height));
++        EXPECT_THAT(mir_surface_placement_get_relative_position(placement_event).width, Eq(expected_rect.width));
++
++        received.raise();
++    }
++
++    ~PlacementCheck()
++    {
++        EXPECT_TRUE(received.wait_for(400ms));
++    }
++
++private:
++    MirRectangle const& expected_rect;
++    mt::Signal received;
++};
++
++void surface_placement_event_callback(MirSurface* /*surface*/, MirEvent const* event, void* context)
++{
++    if (mir_event_get_type(event) == mir_event_type_surface_placement)
++    {
++        auto const placement_event = mir_event_get_surface_placement_event(event);
++        static_cast<PlacementCheck*>(context)->check(placement_event);
++    }
++}
++}
++
++TEST_F(CustomWindowManagement, when_the_window_manager_places_a_surface_the_notification_reaches_the_client)
++{
++    int const width{800};
++    int const height{600};
++    MirPixelFormat const format{mir_pixel_format_bgr_888};
++    MirRectangle placement{42, 15, 24, 7};
++    geom::Rectangle placement_{{42, 15}, {24, 7}};
++
++    std::shared_ptr<ms::Surface> scene_surface;
++
++    auto capture_scene_surface = [&](
++        std::shared_ptr<ms::Session> const& session,
++        ms::SurfaceCreationParameters const& params,
++        std::function<mf::SurfaceId(std::shared_ptr<ms::Session> const& session, ms::SurfaceCreationParameters const& params)> const& build)
++        ->  mf::SurfaceId
++        {
++            auto const result = build(session, params);
++            scene_surface = session->surface(result);
++            return result;
++        };
++
++    EXPECT_CALL(window_manager, add_surface(_,_,_)).WillOnce(Invoke(capture_scene_surface));
++
++    start_server();
++    auto connection = mir_connect_sync(new_connection().c_str(), __PRETTY_FUNCTION__);
++
++    PlacementCheck placement_check{placement};
++    auto surface_spec = mir_connection_create_spec_for_normal_surface(connection, width, height, format);
++    mir_surface_spec_set_event_handler(surface_spec, &surface_placement_event_callback, &placement_check);
++    auto surface = mir_surface_create_sync(surface_spec);
++    mir_surface_spec_release(surface_spec);
++
++    scene_surface->placed_relative(placement_);
++
++    mir_surface_release_sync(surface);
++    mir_connection_release(connection);
++}
 === modified file 'tests/include/mir/test/doubles/stub_scene_surface.h'
 --- tests/include/mir/test/doubles/stub_scene_surface.h	2016-08-10 10:43:39 +0000
 +++ tests/include/mir/test/doubles/stub_scene_surface.h	2016-09-15 08:21:15 +0000
@@ -108,6 +108,7 @@
      void set_confine_pointer_state(MirPointerConfinementState /*state*/) override {}
      MirPointerConfinementState confine_pointer_state() const override { return {}; }
++    void placed_relative(geometry::Rectangle const& /*placement*/) override {}
  };
+ }
 === modified file 'tests/mir_test_framework/stub_surface.cpp'
 --- tests/mir_test_framework/stub_surface.cpp	2016-06-27 20:44:49 +0000
 +++ tests/mir_test_framework/stub_surface.cpp	2016-09-15 08:21:15 +0000
@@ -209,6 +209,9 @@
      return {};
+ }
++void mtd::StubSurface::placed_relative(geometry::Rectangle const& /*placement*/)
++{
++}
  namespace
+ {