forked from enlightenment/efl
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
This commit is contained in:
parent
d54591720e
commit
931ac66be1
|
@ -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
|
||||
*/
|
||||
|
|
Loading…
Reference in New Issue