From c27cd5f065140355d900fd40c9093464b14352bb Mon Sep 17 00:00:00 2001 From: Tony Crisci Date: Mon, 28 May 2018 11:16:33 -0400 Subject: [PATCH 1/2] document the map/unmap xdg-shell events --- include/wlr/types/wlr_xdg_shell.h | 21 +++++++++++++++++++++ include/wlr/types/wlr_xdg_shell_v6.h | 21 +++++++++++++++++++++ 2 files changed, 42 insertions(+) diff --git a/include/wlr/types/wlr_xdg_shell.h b/include/wlr/types/wlr_xdg_shell.h index 11709c75..8b9980ad 100644 --- a/include/wlr/types/wlr_xdg_shell.h +++ b/include/wlr/types/wlr_xdg_shell.h @@ -14,6 +14,13 @@ struct wlr_xdg_shell { struct wl_listener display_destroy; struct { + /** + * The `new_surface` event signals that a client has requested to + * create a new shell surface. At this point, the surface is ready to + * be configured but not ready to be managed by the compositor by + * adding it to a list of views. The surface will be ready to be + * managed on the `map` event. + */ struct wl_signal new_surface; } events; @@ -162,7 +169,21 @@ struct wlr_xdg_surface { struct wl_signal destroy; struct wl_signal ping_timeout; struct wl_signal new_popup; + /** + * The `map` event signals that the shell surface is ready to be + * managed by the compositor and rendered on the screen. At this point, + * the surface has configured its properties, has had the opportunity + * to bind to the seat to receive input events, and has a buffer that + * is ready to be rendered. You can now safely add this surface to a + * list of views. + */ struct wl_signal map; + /** + * The `unmap` event signals that the surface is no longer in a state + * where it should be shown on the screen. This might happen if the + * surface no longer has a displayable buffer because either the + * surface has been hidden or is about to be destroyed. + */ struct wl_signal unmap; } events; diff --git a/include/wlr/types/wlr_xdg_shell_v6.h b/include/wlr/types/wlr_xdg_shell_v6.h index bce645da..34bf77b1 100644 --- a/include/wlr/types/wlr_xdg_shell_v6.h +++ b/include/wlr/types/wlr_xdg_shell_v6.h @@ -15,6 +15,13 @@ struct wlr_xdg_shell_v6 { struct wl_listener display_destroy; struct { + /** + * The `new_surface` event signals that a client has requested to + * create a new shell surface. At this point, the surface is ready to + * be configured but not ready to be managed by the compositor by + * adding it to a list of views. The surface will be ready to be + * managed on the `map` event. + */ struct wl_signal new_surface; } events; @@ -160,7 +167,21 @@ struct wlr_xdg_surface_v6 { struct wl_signal destroy; struct wl_signal ping_timeout; struct wl_signal new_popup; + /** + * The `map` event signals that the shell surface is ready to be + * managed by the compositor and rendered on the screen. At this point, + * the surface has configured its properties, has had the opportunity + * to bind to the seat to receive input events, and has a buffer that + * is ready to be rendered. You can now safely add this surface to a + * list of views. + */ struct wl_signal map; + /** + * The `unmap` event signals that the surface is no longer in a state + * where it should be shown on the screen. This might happen if the + * surface no longer has a displayable buffer because either the + * surface has been hidden or is about to be destroyed. + */ struct wl_signal unmap; } events; From 044fa52be48ff47abe6df0e5e77761f7b0598110 Mon Sep 17 00:00:00 2001 From: Tony Crisci Date: Mon, 28 May 2018 13:12:53 -0400 Subject: [PATCH 2/2] reword new_surface docs --- include/wlr/types/wlr_xdg_shell.h | 5 ++--- include/wlr/types/wlr_xdg_shell_v6.h | 5 ++--- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/include/wlr/types/wlr_xdg_shell.h b/include/wlr/types/wlr_xdg_shell.h index 8b9980ad..5eb30a16 100644 --- a/include/wlr/types/wlr_xdg_shell.h +++ b/include/wlr/types/wlr_xdg_shell.h @@ -17,9 +17,8 @@ struct wlr_xdg_shell { /** * The `new_surface` event signals that a client has requested to * create a new shell surface. At this point, the surface is ready to - * be configured but not ready to be managed by the compositor by - * adding it to a list of views. The surface will be ready to be - * managed on the `map` event. + * be configured but is not mapped or ready receive input events. The + * surface will be ready to be managed on the `map` event. */ struct wl_signal new_surface; } events; diff --git a/include/wlr/types/wlr_xdg_shell_v6.h b/include/wlr/types/wlr_xdg_shell_v6.h index 34bf77b1..2fdf49e5 100644 --- a/include/wlr/types/wlr_xdg_shell_v6.h +++ b/include/wlr/types/wlr_xdg_shell_v6.h @@ -18,9 +18,8 @@ struct wlr_xdg_shell_v6 { /** * The `new_surface` event signals that a client has requested to * create a new shell surface. At this point, the surface is ready to - * be configured but not ready to be managed by the compositor by - * adding it to a list of views. The surface will be ready to be - * managed on the `map` event. + * be configured but is not mapped or ready receive input events. The + * surface will be ready to be managed on the `map` event. */ struct wl_signal new_surface; } events;