Add `.cursor(icon)` to `ElementBuilder`

[symil]

Summary

Currently the way to change the cursor's icon is through miniquad's re-exported set_mouse_cursor function. However calling it multiple times per frame can cause the cursor to flicker because calling it actually changes the cursor right away. It would be convenient to have a mechanism that wraps this and call the function once per frame max.

Motivation

It's very common to change the cursor's icon, when a button is hovered for example. Right now the workaround is to carry a variable that holds the cursor's final value and call set_mouse_cursor at the end of the frame. This is not very natural, and becomes more and more tedious as the rendering tree grows.

Proposed API

Re-export miniquad's CursorIcon in the prelude and add .cursor() to ElementBuilder:

let mut cursor = None;

if is_hovered {
    cursor = Some(CursorIcon::Pointer);
}

ui.element().cursor(cursor).empty();

It takes an Option so we can chain the functions nicely regardless of whether or not we want to display a cursor, otherwise we would have to do:

let mut elt = ui.element();
if is_hovered {
    elt = elt.cursor(CursorIcon::Pointer;
}
elt.empty();
// Very ugly!

Behavior

• The cursor is stored in the root Ply (or the root element, not sure how this works exactly yet).
• The cursor associated with each element is stored. When ui.show() is called, it takes the one with the highest z-index and displays it through set_window_cursor (defaulting to CursorIcon::Default if none was specified).
• Even though .cursor() is a member of ElementBuilder, it updates the cursor regardless of whether or not the element is hovered (contrary to CSS's cursor attribute).

[TheRedDeveloper]

1. Your syntax in the issue is... bad. Sorry.
2. We should not add a .cursor() method, this removes customization, and is actually much uglier than the more beautiful:

let mut cursor = CursorIcon::Default;

// ... in the main loop
ui.element()
  .children(|ui| {
    if ui.hovered() {
      cursor = CursorIcon::Pointer;
    }
    // ...
  });

let id = ui.element().empty();

if ui.is_hovered(id) {
    cursor = CursorIcon::Text;
}

set_mouse_cursor(cursor);

This lets you customize the cursor behavior in any way, while you set the cursor exactly once per frame. If Ply would set the cursor for you, custom behavior would have to overwrite that, causing cursor flickering.

What I do agree with:

• set_mouse_cursor and CursorIcon should be re-exported in the prelude. I'll do that.
• The flickering issue should be documented with the pattern above.

Closing this, as the proposed API adds unnecessary complexity to ElementBuilder for something that's already solvable easier with one variable and one call. You should add an issue to add set_mouse_cursor and CursorIcon to the prelude instead.

[symil]

I understand but that doesn't solve the issue of having to carry the variable through the whole component tree. If I want to change the cursor in a deeply nested element, it's painful to have to propagate the variable that holds the cursor all the way to the nested element.

[TheRedDeveloper]

Make a mutable global. You don't even need a Mutex, just thread_local! a RefCell<CursorIcon>, and .with() to borrow mut:

use std::cell::RefCell;

thread_local! {
    static CURSOR: RefCell<CursorIcon> = RefCell::new(CursorIcon::Default);
}

fn set_cursor(icon: CursorIcon) {
    CURSOR.with(|c| *c.borrow_mut() = icon);
}

fn apply_cursor() {
    CURSOR.with(|c| {
        set_mouse_cursor(*c.borrow());
        *c.borrow_mut() = CursorIcon::Default;
    });
}

Call set_cursor(CursorIcon::Pointer) from anywhere in the tree, apply_cursor() once at the end of the frame. No variable threading needed.

[symil]

I still think it's a bit of a shame to not have this system directly in the engine, changing the cursor to react to a button being hovered should be a no-brainer in my opinion. But this is a simple workaround so I'll do that thanks 👍