aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--include/wlr/types/wlr_xcursor_manager.h30
-rw-r--r--include/wlr/xcursor.h17
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);
/**