Design of cursor visibility and cursor position API

[proneon267]

As per our discussion until now, here is what I think the API should look like:

Window by Window Basis:

# As a getter:
print(window.cursor_position)
# Returns the current cursor position relative to the specified window as a position tuple (x,y).

print(window.cursor_visible)
# Returns the current cursor visibility for the specified window as a Boolean.

# As a setter:
window.cursor_position = (x, y)
# Sets the cursor position relative to the specified window.

window.cursor_visible = True/False
# Sets the cursor visibility for the specified window.

App wide Basis:

# As a getter:
print(app.cursor_position)
# Returns the current absolute cursor position as a position tuple (x,y).

print(app.cursor_visible)
# Returns the current cursor visibility for the whole app as a Boolean.

# As a setter:
app.cursor_position = (x, y)
# Sets the absolute cursor position.

app.cursor_visible = True/False
# Sets the cursor visibility for the whole app.

Here, I can see the usefulness of exposure of cusor_visibility and cursor_position both as window basis and app wide basis.

cursor_visibility on a window basis can allow the users to interact with the other windows of the app while preventing interaction on a particular window.

cursor_visibility on an app wide basis can allow the developers to prevent user interaction for the whole app. This is useful when the app doesn't want the user to do something while a process or task is running which would be hampered by any user interaction.

cursor_position on a window basis can be used to implement a "first time app use guide". This would allow the developer to move the cursor to a particular position to point out a feature on the app. This would be useful as the app developer would want to move the cursor with respect to particular window on which the feature is located.

cursor_position on an app wide basis can be used to point out certain things on the user's screen which is not related to the app itself, like a feature on the user's system.

@freakboy3742 Let me know how do you feel about this.

[freakboy3742]

First off - I'll flag that broadly speaking, I'm not a huge fan of the general idea of cursor control APIs. From a UX perspective, apps should keep their hands off the position of the cursor; and the only time an app should care about the position of a cursor is (a) the position at the time of a click event on a widget like a canvas, and (b) enter/exit region events.

Broad cursor visibility is also needed for use cases like full screen presentation apps - but outside that sort of case, apps should not be making the cursor arbitrarily invisible. The cursor is a key UX element. Making that element invisible is, generally speaking, a bad UX move.

Continuing specific discussion points from #1864:

1. If we were to add a cursor position API - what is the use case for a window level API for setting the position of a cursor? There is only one cursor. The cursor is not window specific. Why is the position of the cursor a window-specific feature? I don't understand how "first time app use guide" is an answer to this; and app.cursor_position = (window.position.x + 10, window.position.y + 20) would seem to address the "window relative position" question.
2. What is the use case for window level API for cursor visibility. Again, the making the cursor disappear is, generally speaking, a bad idea from a UX perspective.

I've also had an in-person discussion with @mhsmith; and he made the good point that cursor visibility is arguably a style question. In CSS, cursor is a property that can control both which cursor is used when hovering over a widget, as well as hiding the cursor on a per-widget basis.

In terms of the specific API proposal - you've covered the public interface API; but there's no mention of the backend API. However it's probably better to wait until we have a concrete public interface before we work out how the backends will implement that API.

[proneon267]

The true use of cursor position system would be to detect hover over a widget and do some operations during that event, like it's done in CSS.

Addressing the questions:

1.Yes, there is only 1 cursor but there will be multiple windows:
Suppose there are 2 windows in an app: window1 and window2. Now, there is a widget on window1.
So, the developer wants to point the cursor to this widget, so he can do:

window1.cursor_position = window.widget.position

While you could do:

app.cursor_position = (window1.position.x + widget.position.y, window1.position.y + widget.position.y)

But, clearly the second approach is more verbose.
Window based cursor positioning system will take the burden off the developer to manually calculating the appropriate position. Moreover, it will improve readability of the code.

This is not a new idea. Most of the toolkits provide both the window relative and global cursor positioning API. Maybe I am not the most qualified one to suggest use cases for this API but clearly there is a need for such API, hence they exist in most toolkits.

2.Apps contain windows. Apps are not windows. Hiding the cursor app wide will be a bad UX decision as the user won't be able to differentiate between a non responding app and a app that doesn't want to take user interaction.

cursor visibility on an window basis provides more fine grained control to the developer. They can choose to show/hide cursor on a specific window or hide entirely for all the windows of their app.

Use case for window level cursor visibility would be an app having multiple windows and the developer wants to hide the cursor on a specific window, rather than app wide.

[proneon267]

I agree with you :-) . That seems logical and would work in the app. Should we make cursor visibility an app wide API only? Also, what about cursor position? Thinking about it a bit more, it seems like there isn't a very good use case for it. The only use case would be a "on_enter/on_exit widget" API where the cursor position would be used internally. Should we also just leave out the cursor position API too?

[freakboy3742]

I'm pretty sure I've been saying consistently that cursor visibility should be an app-wide API only... so... yes - cursor visibility should be an app-wide API only.

I'm also very sceptical whether a set position API is needed at all. Any event being captured that was based on cursor position will either be provided the cursor position as part of the event (e.g., a mouse move event on a canvas), or doesn't require an explicit position because the mouse being in the right place is implicit in the event firing in the first place (e.g., on-enter/exit).

[proneon267]

I agree with you. Well then, is the PR needed at all? There was already, show_cursor() and hide_cursor(). Is another property cursor_visible needed? If not, should I close that PR and implement the backend in terms of the already present API?

[freakboy3742]

That would seem to be the right approach to me.

(and this is why a design discussion is valuable :-)

[proneon267]

Thanks for helping me :)