Document event order when using views (on_draw, on_update)

[DigiDuncan]

Enhancement request:

Make Window and View's on_draw() call self.clear() instead of pass.

What should be added/changed?

See above 😅
It's possible this only makes sense to do for Window and not View, as @einarf points out here:

What I'm not sure about right now is how the on_draw / on_update events work with views. As far as I remember both the window and view methods can be called in a frame.
That in turn can case games to clear the window twice

What would it help with?

Since on_draw() is likely to be overriden anyway, this gives a resonable default in which it doesn't appear like methods like arcade.set_background_color() (which require a screen to be cleared to have noticeable effect) do anything.

[einarf]

We have to look into how on_draw / on_update events trigger. It can run for both the view and the window. You can return return pyglet.event.EVENT_HANDLED from these to ensure the window methods is not called I think, but this is not something we have exposed in arcade.

[DragonMoffon]

From my understanding, both the window's on_draw and the view's on_draw are called. Annoyingly the view's on_draw is called first.

This is also true for update and on_update. the call order is view's update, window's update, view's on_update, and finally window's on_update.

You would need a special Window only event called "begin_draw" or something.

[einarf]

If anything... this issue leads to fixing lacking docs about events.

[einarf]

Changed this into a documentation task.

Pyglet is using a stack to dispatch event. When you activate a view all the on_ methods for the view will be called since its on the top os the stack. Then the window events are triggered.

To avoid the window on_draw to be called the View's on_draw needs to return True to signal to the event dispacher that the event is handled.

[DragonMoffon]

Im looking into making the order of the draws and updates more consistent. With proper documentation and the like.