discomfitor pushed a commit to branch master. http://git.enlightenment.org/core/efl.git/commit/?id=931ac66be1ccadc58194b2b4cf1e4d51851b0b12
commit 931ac66be1ccadc58194b2b4cf1e4d51851b0b12 Author: Bryce Harrington <[email protected]> Date: Tue Mar 17 19:23:48 2015 -0400 ecore_wayland: Improve API docs Summary: For calls that return pointers, specify that NULL is a potential return value. Add API documentation for some misc. routines missing it. Reviewers: zmike, cedric, devilhorns Subscribers: cedric Differential Revision: https://phab.enlightenment.org/D2180 --- src/lib/ecore_wayland/Ecore_Wayland.h | 124 +++++++++++++++++++++++++++++++--- 1 file changed, 114 insertions(+), 10 deletions(-) diff --git a/src/lib/ecore_wayland/Ecore_Wayland.h b/src/lib/ecore_wayland/Ecore_Wayland.h index ea59967..9460e95 100644 --- a/src/lib/ecore_wayland/Ecore_Wayland.h +++ b/src/lib/ecore_wayland/Ecore_Wayland.h @@ -231,8 +231,8 @@ struct _Ecore_Wl_Event_Interfaces_Bound * @ingroup Ecore * Ecore_Wl provides a wrapper and convenience functions for using the - * Wayland window system. Function groups for this part of the library - * include the following: + * Wayland protocol in implementing a window system. Function groups for + * this part of the library include the following: * * @li @ref Ecore_Wl_Init_Group * @li @ref Ecore_Wl_Display_Group @@ -327,7 +327,7 @@ EAPI void ecore_wl_sync(void); /** * Retrieves the Wayland Shm Interface used for the current Wayland connection. * - * @return The current wayland shm interface + * @return The current wayland shm interface, or NULL on error * * @ingroup Ecore_Wl_Display_Group * @since 1.2 @@ -337,7 +337,7 @@ EAPI struct wl_shm *ecore_wl_shm_get(void); /** * Retrieves the Wayland Display Interface used for the current Wayland connection. * - * @return The current wayland display interface + * @return The current wayland display interface, or NULL on error * * @ingroup Ecore_Wl_Display_Group * @since 1.2 @@ -350,7 +350,7 @@ EAPI struct wl_display *ecore_wl_display_get(void); * This interface is used by clients to request the creation of surfaces and * regions. * - * @return The current wayland compositor interface + * @return The current wayland compositor interface, or NULL on error * @since 1.8 */ @@ -364,6 +364,16 @@ EAPI struct wl_display *ecore_wl_display_get(void); * @since 1.2 */ EAPI void ecore_wl_screen_size_get(int *w, int *h); + +/** + * Retrieves the position of the current screen. + * + * @param x where to return the horizontal position. May be NULL. Returns 0 on error. + * @param y where to return the vertical position. May be NULL. Returns 0 on error. + * + * @ingroup Ecore_Wl_Display_Group + * @since 1.2 + */ EAPI void ecore_wl_pointer_xy_get(int *x, int *y); /** @@ -378,6 +388,14 @@ EAPI void ecore_wl_pointer_xy_get(int *x, int *y); * @since 1.2 */ EAPI int ecore_wl_dpi_get(void); + +/** + * Dispatch Wayland events + * + * Dispatches any events queued on the default queue. Wayland will attempt + * to read from the display fd and queue things up according to the proxy + * assignment. + */ EAPI void ecore_wl_display_iterate(void); /* @@ -436,7 +454,7 @@ EAPI void ecore_wl_input_cursor_theme_name_set(Ecore_Wl_Input *input, const char * * There's no need to call dispatch manually, since this call will do it if necessary. * - * @return The current wayland globals interface list + * @return The current wayland globals interface list, or NULL on error * * @ingroup Ecore_Wl_Display_Group * @since 1.7.6 @@ -446,7 +464,7 @@ EAPI Eina_Inlist *ecore_wl_globals_get(void); /** * Retrieves the Wayland Registry used for the current Wayland connection. * - * @return The current wayland registry + * @return The current wayland registry, or NULL on error * * @ingroup Ecore_Wl_Display_Group * @since 1.7.6 @@ -471,7 +489,7 @@ EAPI struct wl_registry *ecore_wl_registry_get(void); * @param h Height * @param buffer_type The type of the buffer to be used to create a new Ecore_Wl_Window. * - * @return The new window + * @return The new window, or NULL on failure * * @ingroup Ecore_Wl_Window_Group * @since 1.2 @@ -598,6 +616,7 @@ EAPI Ecore_Wl_Input *ecore_wl_window_keyboard_get(Ecore_Wl_Window *win); * Returns a wl_surface with no association to any wl_shell_surface. * * @param win The window which will use this newly created surface. + * @return wl_surface or NULL on error * * @ingroup Ecore_Wl_Window_Group * @since 1.8 @@ -611,7 +630,7 @@ EAPI Eina_Bool ecore_wl_window_alpha_get(Ecore_Wl_Window *win); * Returns the Ecore_Wl_Window from a wl_surface * * @param surface The surface for which to find the Ecore_Wl_Window from - * @return the Ecore_Wl_Window associated with this surface + * @return the Ecore_Wl_Window associated with this surface, or NULL if not found * * @ingroup Ecore_Wl_Window_Group * @since 1.8 @@ -710,24 +729,32 @@ EINA_DEPRECATED EAPI Eina_Bool ecore_wl_dnd_start_drag(Ecore_Wl_Dnd *dnd); EINA_DEPRECATED EAPI Eina_Bool ecore_wl_dnd_selection_has_owner(Ecore_Wl_Dnd *dnd); /** + * @return false on error, true otherwise + * * @ingroup Ecore_Wl_Dnd_Group * @since 1.8 */ EAPI Eina_Bool ecore_wl_dnd_selection_set(Ecore_Wl_Input *input, const char **types_offered); /** + * @return false if type not found or on error, true otherwise + * * @ingroup Ecore_Wl_Dnd_Group * @since 1.8 */ EAPI Eina_Bool ecore_wl_dnd_selection_get(Ecore_Wl_Input *input, const char *type); /** + * @return true if input has a selection source, false otherwise or on error + * * @ingroup Ecore_Wl_Dnd_Group * @since 1.8 */ EAPI Eina_Bool ecore_wl_dnd_selection_owner_has(Ecore_Wl_Input *input); /** + * @return false on error, true otherwise + * * @ingroup Ecore_Wl_Dnd_Group * @since 1.8 */ @@ -746,6 +773,8 @@ EAPI void ecore_wl_dnd_drag_start(Ecore_Wl_Input *input, Ecore_Wl_Window *win, E EAPI void ecore_wl_dnd_drag_end(Ecore_Wl_Input *input); /** + * @return false if type not found or on error, true otherwise + * * @ingroup Ecore_Wl_Dnd_Group * @since 1.8 */ @@ -769,6 +798,13 @@ EAPI struct wl_array *ecore_wl_dnd_drag_types_get(Ecore_Wl_Input *input); */ /* EAPI Ecore_Wl_Dnd_Source *ecore_wl_dnd_drag_source_create(Ecore_Wl_Dnd *dnd); */ +/** + * Enable/disable server mode. + * + * With this enabled, the compositor acts as a Wayland server, iterating + * the display and dispatching events. With it disabled, the process is + * handled as a client. + */ EAPI void ecore_wl_server_mode_set(Eina_Bool on); /** @@ -794,6 +830,9 @@ EAPI void ecore_wl_server_mode_set(Eina_Bool on); * The @param win must be visible, otherwise there will be no surface created * for it yet. * + * @return the allocated and initialized Ecore_Wl_Subsurf object, or + * NULL on failure + * * @ingroup Ecore_Wl_Subsurf * @since 1.8 */ @@ -802,13 +841,18 @@ EAPI Ecore_Wl_Subsurf *ecore_wl_subsurf_create(Ecore_Wl_Window *win); /** * Destroy the given subsurface, as well as the surface associated with it. * + * @param ess the subsurface + * * @ingroup Ecore_Wl_Subsurf * @since 1.8 */ EAPI void ecore_wl_subsurf_del(Ecore_Wl_Subsurf *ess); /** - * Return the wl_surface associated with this subsurface. + * Get the wl_surface for this subsurface + * + * @param ess the subsurface + * @return the wl_surface associated with this subsurface, or NULL on failure * * @ingroup Ecore_Wl_Subsurf * @since 1.8 @@ -817,6 +861,12 @@ EAPI struct wl_surface *ecore_wl_subsurf_surface_get(Ecore_Wl_Subsurf *ess); /** * Set the position of this subsurface, relative to its parent surface. + * If ess is defined and the x, y coordinates differ from the currently + * tracked position, this also schedules a sub-surface position change. + * + * @param ess the subsurface + * @param x coordinate in the parent surface + * @param y coordinate in the parent surface * * @ingroup Ecore_Wl_Subsurf * @since 1.8 @@ -825,6 +875,11 @@ EAPI void ecore_wl_subsurf_position_set(Ecore_Wl_Subsurf *ess, int x, int y); /** * Get the position of this subsurface, relative to its parent surface. + * Coordinates will be returned in x and y if non-NULL. + * + * @param ess the subsurface + * @param x coordinate in the parent surface, or NULL to ignore + * @param y coordinate in the parent surface, or NULL to ignore * * @ingroup Ecore_Wl_Subsurf * @since 1.8 @@ -832,18 +887,57 @@ EAPI void ecore_wl_subsurf_position_set(Ecore_Wl_Subsurf *ess, int x, int y); EAPI void ecore_wl_subsurf_position_get(Ecore_Wl_Subsurf *ess, int *x, int *y); /** + * Place subsurface on layer above a reference surface + * + * Moves the @param ess subsurface to just above the reference @param + * surface, changing the z-order. The reference @param surface must + * be either a sibling or parent surface, else a protocol error will + * be generated. + * + * @param ess the subsurface + * @param surface the sibling reference surface + * * @ingroup Ecore_Wl_Subsurf * @since 1.8 */ EAPI void ecore_wl_subsurf_place_above(Ecore_Wl_Subsurf *ess, struct wl_surface *surface); /** + * Place subsurface on layer below a reference surface + * + * See ecore_wl_subsurf_place_above. + * + * @param ess the subsurface + * @param surface the sibling reference surface + * * @ingroup Ecore_Wl_Subsurf * @since 1.8 */ EAPI void ecore_wl_subsurf_place_below(Ecore_Wl_Subsurf *ess, struct wl_surface *surface); /** + * Enables or disables sub-surface synchronization + * + * When synchronization is enabled, surface commits on the subsurface + * will be cached and only applied when the parent surface's state is + * applied. This ensures atomic updates of the parent and all of its + * synchronized sub-surfaces. + * + * When synchronization is disabled, commits will apply to the pending + * state directly without caching, just like a normal wl_surface. If + * there are already cached events when this is set, those events are + * applied simultaneously with the desync event. + * + * Attempting to enable synchronization when the subsurface already + * thinks it's sync'd, or desync when it believes its desync'd, will + * be trivially ignored and will not generate a Wayland event. + * + * See Wayland's set_desync documentation for further details and + * exceptional cases. + * + * @param ess the subsurface + * @param val true to enable synchronization, false to desynchronize + * * @ingroup Ecore_Wl_Subsurf * @since 1.8 */ @@ -852,8 +946,18 @@ EAPI void ecore_wl_subsurf_sync_set(Ecore_Wl_Subsurf *ess, Eina_Bool val); /** * Set an opaque region for the given subsurface. * + * This is an optimization hint to the compositor to allow it avoid + * redrawing content unnecessarily. Note that marking transparent + * content as opaque will cause repaint artifacts. + * * Use a 0x0 region size to unset the opaque region. * + * @param ess the subsurface + * @param x coordinate in the parent surface + * @param y coordinate in the parent surface + * @param w width to set as opaque + * @param h height to set as opaque + * * @ingroup Ecore_Wl_Subsurf * @since 1.8 */ --
