From c27cd5f065140355d900fd40c9093464b14352bb Mon Sep 17 00:00:00 2001 From: Tony Crisci Date: Mon, 28 May 2018 11:16:33 -0400 Subject: 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(+) (limited to 'include') 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; -- cgit v1.2.3