From ffb53a6103bcaf23a9991008dc7fee09fb803542 Mon Sep 17 00:00:00 2001 From: Isaac Freund Date: Fri, 1 Jul 2022 20:37:34 +0200 Subject: Document NULL return value of foo_from_wlr_surface() functions wlr_xdg_surface_from_wlr_surface() for example may return NULL even if the surface has the xdg surface role if the corresponding xdg surface has been destroyed. --- include/wlr/types/wlr_input_method_v2.h | 11 +++++++++++ include/wlr/types/wlr_layer_shell_v1.h | 9 +++++++++ include/wlr/types/wlr_session_lock_v1.h | 10 ++++++++++ include/wlr/types/wlr_subcompositor.h | 9 +++++++-- include/wlr/types/wlr_xdg_shell.h | 9 +++++++++ include/wlr/xwayland.h | 9 +++++++++ 6 files changed, 55 insertions(+), 2 deletions(-) diff --git a/include/wlr/types/wlr_input_method_v2.h b/include/wlr/types/wlr_input_method_v2.h index 316cecd5..8baeae57 100644 --- a/include/wlr/types/wlr_input_method_v2.h +++ b/include/wlr/types/wlr_input_method_v2.h @@ -122,9 +122,20 @@ void wlr_input_method_v2_send_done(struct wlr_input_method_v2 *input_method); void wlr_input_method_v2_send_unavailable( struct wlr_input_method_v2 *input_method); +/** + * Returns true if the surface has the input popup surface role. + */ bool wlr_surface_is_input_popup_surface_v2(struct wlr_surface *surface); + +/** + * Get a struct wlr_input_popup_surface_v2 from a struct wlr_surface. + * Asserts that the surface has the input popup surface role. + * May return NULL even if the surface has the input popup surface role if the + * corresponding input popup surface has been destroyed. + */ struct wlr_input_popup_surface_v2 *wlr_input_popup_surface_v2_from_wlr_surface( struct wlr_surface *surface); + void wlr_input_popup_surface_v2_send_text_input_rectangle( struct wlr_input_popup_surface_v2 *popup_surface, struct wlr_box *sbox); diff --git a/include/wlr/types/wlr_layer_shell_v1.h b/include/wlr/types/wlr_layer_shell_v1.h index e97c7311..3ebdbeda 100644 --- a/include/wlr/types/wlr_layer_shell_v1.h +++ b/include/wlr/types/wlr_layer_shell_v1.h @@ -140,8 +140,17 @@ uint32_t wlr_layer_surface_v1_configure(struct wlr_layer_surface_v1 *surface, */ void wlr_layer_surface_v1_destroy(struct wlr_layer_surface_v1 *surface); +/** + * Returns true if the surface has the layer surface role. + */ bool wlr_surface_is_layer_surface(struct wlr_surface *surface); +/** + * Get a struct wlr_layer_surface from a struct wlr_surface. + * Asserts that the surface has the layer surface role. + * May return NULL even if the surface has the layer surface role if the + * corresponding layer surface has been destroyed. + */ struct wlr_layer_surface_v1 *wlr_layer_surface_v1_from_wlr_surface( struct wlr_surface *surface); diff --git a/include/wlr/types/wlr_session_lock_v1.h b/include/wlr/types/wlr_session_lock_v1.h index 101fe56c..c09978c7 100644 --- a/include/wlr/types/wlr_session_lock_v1.h +++ b/include/wlr/types/wlr_session_lock_v1.h @@ -91,7 +91,17 @@ uint32_t wlr_session_lock_surface_v1_configure( struct wlr_session_lock_surface_v1 *lock_surface, uint32_t width, uint32_t height); +/** + * Returns true if the surface has the session lock surface role. + */ bool wlr_surface_is_session_lock_surface_v1(struct wlr_surface *surface); + +/** + * Get a struct wlr_session_lock_surface_v1 from a struct wlr_surface. + * Asserts that the surface has the session lock surface role. + * May return NULL even if the surface has the session lock surface role if the + * corresponding session lock surface has been destroyed. + */ struct wlr_session_lock_surface_v1 *wlr_session_lock_surface_v1_from_wlr_surface( struct wlr_surface *surface); diff --git a/include/wlr/types/wlr_subcompositor.h b/include/wlr/types/wlr_subcompositor.h index d8e57ed8..e7f6ab2f 100644 --- a/include/wlr/types/wlr_subcompositor.h +++ b/include/wlr/types/wlr_subcompositor.h @@ -63,11 +63,16 @@ struct wlr_subcompositor { } events; }; +/** + * Returns true if the surface has the subsurface role. + */ bool wlr_surface_is_subsurface(struct wlr_surface *surface); /** - * Get a subsurface from a surface. Can return NULL if the subsurface has been - * destroyed. + * Get a struct wlr_subsurface from a struct wlr_surface. + * Asserts that the surface has the subsurface role. + * May return NULL even if the surface has the subsurface role if the + * corresponding subsurface has been destroyed. */ struct wlr_subsurface *wlr_subsurface_from_wlr_surface( struct wlr_surface *surface); diff --git a/include/wlr/types/wlr_xdg_shell.h b/include/wlr/types/wlr_xdg_shell.h index 802f03a5..b4ef2e94 100644 --- a/include/wlr/types/wlr_xdg_shell.h +++ b/include/wlr/types/wlr_xdg_shell.h @@ -462,8 +462,17 @@ struct wlr_surface *wlr_xdg_surface_popup_surface_at( struct wlr_xdg_surface *surface, double sx, double sy, double *sub_x, double *sub_y); +/** + * Returns true if the surface has the xdg surface role. + */ bool wlr_surface_is_xdg_surface(struct wlr_surface *surface); +/** + * Get a struct wlr_xdg_surface from a struct wlr_surface. + * Asserts that the surface has the xdg surface role. + * May return NULL even if the surface has the xdg surface role if the + * corresponding xdg surface has been destroyed. + */ struct wlr_xdg_surface *wlr_xdg_surface_from_wlr_surface( struct wlr_surface *surface); diff --git a/include/wlr/xwayland.h b/include/wlr/xwayland.h index f1c76f69..ca35da80 100644 --- a/include/wlr/xwayland.h +++ b/include/wlr/xwayland.h @@ -273,8 +273,17 @@ void wlr_xwayland_surface_set_fullscreen(struct wlr_xwayland_surface *surface, void wlr_xwayland_set_seat(struct wlr_xwayland *xwayland, struct wlr_seat *seat); +/** + * Returns true if the surface has the xwayland surface role. + */ bool wlr_surface_is_xwayland_surface(struct wlr_surface *surface); +/** + * Get a struct wlr_xwayland_surface from a struct wlr_surface. + * Asserts that the surface has the xwayland surface role. + * May return NULL even if the surface has the xwayland surface role if the + * corresponding xwayland surface has been destroyed. + */ struct wlr_xwayland_surface *wlr_xwayland_surface_from_wlr_surface( struct wlr_surface *surface); -- cgit v1.2.3