clutter: Clarify clutter_stage_get_actor_at_pos docs

When a user moves their cursor the perceived behaviour is that it will
pick what is under the cursor. However this isn't how picking works.
Picking does a virtual redraw of the screen, so in some cases what gets
picked isn't the same as what the user could see on the previous frame.
It more represents what will be drawn on the next frame than what is on
screen at present.

It may be unsafe to change these semantics, and they are useful anyway.
Just document it better.

https://gitlab.gnome.org/GNOME/mutter/merge_requests/214
This commit is contained in:
Daniel van Vugt 2018-08-31 15:11:54 +08:00 committed by Marco Trevisan
parent c237bc5f45
commit 9db9793f33

View File

@ -3031,7 +3031,11 @@ clutter_stage_read_pixels (ClutterStage *stage,
* @y: Y coordinate to check
*
* Checks the scene at the coordinates @x and @y and returns a pointer
* to the #ClutterActor at those coordinates.
* to the #ClutterActor at those coordinates. The result is the actor which
* would be at the specified location on the next redraw, and is not
* necessarily that which was there on the previous redraw. This allows the
* function to perform chronologically correctly after any queued changes to
* the scene, and even if nothing has been drawn.
*
* By using @pick_mode it is possible to control which actors will be
* painted and thus available.