Merge lp:~vanvugt/mir/stub-subfocus into lp:mir

[Daniel van Vugt]

Add a stub client API function `mir_window_subfocus' to direct future
desktop zoom and other accessibility features to follow keyboard
navigation.

Better to get toolkits using it early, even if not implemented yet.

This came out of previous discussions with the Unity team about what is required for truly accessible desktop zoom. The zoom should follow keyboard navigation (e.g. text fields and tabbing) when appropriate.

[Mir CI Bot (mir-ci-bot)]

PASSED: Continuous integration, rev:4002
https://mir-jenkins.ubuntu.com/job/mir-ci/2897/
Executed test runs:
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-mir/3829
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-0-fetch/3908
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=vivid+overlay/3898
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=xenial+overlay/3898
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=zesty/3898
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=zesty/3856
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=zesty/3856/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=xenial+overlay/3856
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=xenial+overlay/3856/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=zesty/3856
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=zesty/3856/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=cross-armhf,compiler=gcc,platform=android,release=vivid+overlay/3856
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=cross-armhf,compiler=gcc,platform=android,release=vivid+overlay/3856/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=android,release=vivid+overlay/3856
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=android,release=vivid+overlay/3856/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=mesa,release=xenial+overlay/3856
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=mesa,release=xenial+overlay/3856/artifact/output/*zip*/output.zip

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

review: Approve (continuous-integration)

[Alan Griffiths (alan-griffiths)]

Can we have a test that shows how the *feature* you envisage works with this API?

I'd be far more confident that this function is useful if it (or a follow-up branch) actually did something.

As it is we're just guessing that this is something we will use one day.

review: Needs Information

[Andreas Pokorny (andreas-pokorny)]

Shouldnt that be a mir_window_spec like API?

Apart from that I could imagine further use cases.. I.e. temporarily moving partially occluded focused windows far enough into the screen to show the "subfocus" area entirely. Then still we could also add that function after 1.0.

review: Needs Information

[Daniel van Vugt (vanvugt)]

Alan:
No not right now. It's not important enough to implement just right now, so if we're not confident about the design then forget it and we can do this in a later release.

Andreas:
No it's not related to spec. It's just a hint to the shell as to what to look at (if zoomed, and the window is visible and focused and the mouse isn't moving, but that's shell-specific policy). The subfocus area might change on any keystroke. There's no reason I can think of to synchronize that with spec-things, or to trouble the user with the spec API on this. But I like your idea for further use cases.

[Chris Halse Rogers (raof)]

Very mild disapprove.

I don't think it's a good idea to land API that we don't intend to implement at all during the same release cycle.

review: Disapprove

[Daniel van Vugt (vanvugt)]

OK, I'll save it for later

Unmerged revisions

4002. By Daniel van Vugt on 2017-01-31

Prototype

=== modified file 'include/client/mir_toolkit/mir_window.h'
--- include/client/mir_toolkit/mir_window.h	2017-01-24 16:49:18 +0000
+++ include/client/mir_toolkit/mir_window.h	2017-01-31 08:22:49 +0000
@@ -758,6 +758,19 @@
  */
 MirPersistentId* mir_window_request_persistent_id_sync(MirWindow* window);
 
+/**
+ * Provide a hint to the shell about the region of a window currently being
+ * interacted with via the keyboard or voice. This is useful during desktop
+ * zoom (etc) to notify the shell when the zoom should move to a specific
+ * region such as a text box or button that has been tabbed to. Shells may
+ * choose to ignore this information, but it is provided for future-proofing
+ * toolkits and applications to work correctly with such accessibility features.
+ *   \param [in] window  The window whose widget is being focused.
+ *   \param [in] area    The area or point to focus on within the window, or
+ *                       set this to NULL to remove the focus.
+ */
+void mir_window_subfocus(MirWindow* window, MirRectangle const* area);
+
 #ifdef __cplusplus
 }
 /**@}*/

=== modified file 'src/client/mir_surface_api.cpp'
--- src/client/mir_surface_api.cpp	2017-01-25 03:34:22 +0000
+++ src/client/mir_surface_api.cpp	2017-01-31 08:22:49 +0000
@@ -829,6 +829,11 @@
     return result;
 }
 
+void mir_window_subfocus(MirWindow*, MirRectangle const*)
+{
+    // TODO for future use
+}
+
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
 

=== modified file 'src/client/symbols.map'
--- src/client/symbols.map	2017-01-30 08:13:20 +0000
+++ src/client/symbols.map	2017-01-31 08:22:49 +0000
@@ -577,3 +577,8 @@
     mir_window_request_persistent_id;
     mir_window_request_persistent_id_sync;
 } MIR_CLIENT_0.25;
+
+MIR_CLIENT_0.27 {  # New functions in Mir 0.27 or 1.0 or whatever
+  global:
+    mir_window_subfocus;
+} MIR_CLIENT_0.26;

=== modified file 'tests/acceptance-tests/test_client_library.cpp'
--- tests/acceptance-tests/test_client_library.cpp	2017-01-30 08:13:20 +0000
+++ tests/acceptance-tests/test_client_library.cpp	2017-01-31 08:22:49 +0000
@@ -1139,6 +1139,29 @@
     mir_connection_release(connection);
 }
 
+TEST_F(ClientLibrary, can_set_subfocus)
+{
+    auto connection = mir_connect_sync(new_connection().c_str(), __PRETTY_FUNCTION__);
+
+    auto surface_spec = mir_create_normal_window_spec(connection, 800, 600);
+    mir_window_spec_set_pixel_format(surface_spec, mir_pixel_format_argb_8888);
+    auto window = mir_create_window_sync(surface_spec);
+    mir_window_spec_release(surface_spec);
+    ASSERT_THAT(window, IsValid());
+
+    // No expectations other than verifying the function is public and
+    // doesn't crash...
+    MirRectangle const area{12,34, 56,78};
+    mir_window_subfocus(window, &area);
+    mir_window_subfocus(window, NULL);
+    MirRectangle const point{98,76, 0,0};
+    mir_window_subfocus(window, &point);
+    mir_window_subfocus(window, NULL);
+
+    mir_window_release_sync(window);
+    mir_connection_release(connection);
+}
+
 TEST_F(ClientLibrary, input_method_can_specify_foreign_surface_id)
 {
     auto first_client = mir_connect_sync(new_connection().c_str(), "Regular Client");