diff options
author | Drew DeVault <sir@cmpwn.com> | 2018-02-01 20:30:18 -0500 |
---|---|---|
committer | Drew DeVault <sir@cmpwn.com> | 2018-02-01 20:30:32 -0500 |
commit | 8cf622f0746c3d30774a9eace357eee1fb916db1 (patch) | |
tree | ee6cfc1e1938c3dbf656f01d28ab1d060cc28070 /include | |
parent | a43555d7f57845e5a3da519cb3dddc55c9e79c1f (diff) |
Improve xcursor docs
Diffstat (limited to 'include')
-rw-r--r-- | include/wlr/types/wlr_xcursor_manager.h | 30 | ||||
-rw-r--r-- | include/wlr/xcursor.h | 17 |
2 files changed, 36 insertions, 11 deletions
diff --git a/include/wlr/types/wlr_xcursor_manager.h b/include/wlr/types/wlr_xcursor_manager.h index 2a2c9035..c7fa83be 100644 --- a/include/wlr/types/wlr_xcursor_manager.h +++ b/include/wlr/types/wlr_xcursor_manager.h @@ -6,7 +6,7 @@ #include <wlr/xcursor.h> /** - * A scaled XCursor theme. + * An XCursor theme at a particular scale factor of the base size. */ struct wlr_xcursor_manager_theme { float scale; @@ -15,11 +15,10 @@ struct wlr_xcursor_manager_theme { }; /** - * Manage multiple XCursor themes with different scales and set `wlr_cursor` - * images. - * - * This manager can be used to display cursor images on multiple outputs having - * different scale factors. + * wlr_xcursor_manager dynamically loads xcursor themes at sizes necessary for + * use on outputs at arbitrary scale factors. You should call + * wlr_xcursor_manager_load for each output you will show your cursor on, with + * the scale factor parameter set to that output's scale factor. */ struct wlr_xcursor_manager { char *name; @@ -28,24 +27,33 @@ struct wlr_xcursor_manager { }; /** - * Create a new XCursor manager. After initialization, scaled themes need to be - * loaded with `wlr_xcursor_manager_load`. `size` is the unscaled cursor theme - * size. + * Creates a new XCursor manager with the given xcursor theme name and base size + * (for use when scale=1). */ struct wlr_xcursor_manager *wlr_xcursor_manager_create(const char *name, uint32_t size); void wlr_xcursor_manager_destroy(struct wlr_xcursor_manager *manager); +/** + * Ensures an xcursor theme at the given scale factor is loaded in the manager. + */ int wlr_xcursor_manager_load(struct wlr_xcursor_manager *manager, float scale); +/** + * Retrieves a wlr_xcursor reference for the given cursor name at the given + * scale factor, or NULL if this wlr_xcursor_manager has not loaded a cursor + * theme at the requested scale. + */ struct wlr_xcursor *wlr_xcursor_manager_get_xcursor( struct wlr_xcursor_manager *manager, const char *name, float scale); /** - * Set a `wlr_cursor` image. The manager uses all currently loaded scaled - * themes. + * Set a wlr_cursor's cursor image to the specified cursor name for all scale + * factors. wlr_cursor will take over from this point and ensure the correct + * cursor is used on each output, assuming a wlr_output_layout is attached to + * it. */ void wlr_xcursor_manager_set_cursor_image(struct wlr_xcursor_manager *manager, const char *name, struct wlr_cursor *cursor); diff --git a/include/wlr/xcursor.h b/include/wlr/xcursor.h index 42fcedb9..c7c89e02 100644 --- a/include/wlr/xcursor.h +++ b/include/wlr/xcursor.h @@ -50,6 +50,9 @@ struct wlr_xcursor { uint32_t total_delay; /* length of the animation in ms */ }; +/** + * Contanier for an Xcursor theme. + */ struct wlr_xcursor_theme { unsigned int cursor_count; struct wlr_xcursor **cursors; @@ -57,13 +60,27 @@ struct wlr_xcursor_theme { int size; }; +/** + * Loads the named xcursor theme at the given cursor size (in pixels). This is + * useful if you need cursor images for your compositor to use when a + * client-side cursors is not available or you wish to override client-side + * cursors for a particular UI interaction (such as using a grab cursor when + * moving a window around). + */ struct wlr_xcursor_theme *wlr_xcursor_theme_load(const char *name, int size); void wlr_xcursor_theme_destroy(struct wlr_xcursor_theme *theme); +/** + * Obtains a wlr_xcursor image for the specified cursor name (e.g. "left_ptr"). + */ struct wlr_xcursor *wlr_xcursor_theme_get_cursor( struct wlr_xcursor_theme *theme, const char *name); +/** + * Returns the current frame number for an animated cursor give a monotonic time + * reference. + */ int wlr_xcursor_frame(struct wlr_xcursor *cursor, uint32_t time); /** |