Add on_exit() hook

[charlesej]

This update adds support for an on_exit() hook.

Overview of changes contained in this pull request:

• Support for users to define an on_exit() function which is called after the game loop is exited. This function can be defined with 0 parameters or 1 parameter (error_status).
• Support for users to define an on_enter() function which is called before the game loop is entered.
• Existing exit() function has been changed to use the common exiting path.

Notes:

• Felt using the name on_exit() seemed better than on_before_exit().
• Added on_enter() support for symmetry.
• Documentation still needs to be updated for this. I can add that to this pull request or open a new issue to track it.
• Could only find a few test cases for PGZeroGame (in test_event_dispatch.py). If you would like test cases for these changes, I can add them to this pull request or open a new issue to track them.

System details (used for testing):

• os: windows 10
• python: 3.5.0
• pygame: 1.9.4
• pgzero: master branch at ef963be
• numpy: 1.15.4

Resolves #51.

[lordmauve]

Thanks!

I think my suggestion "on_before_exit()" may have been inspired by "onbeforeunload" in Javascript:
https://developer.mozilla.org/en-US/docs/Web/API/WindowEventHandlers/onbeforeunload

Javascript has "onunload" and "onbeforeunload", with "onbeforeunload" offering the ability to prompt for confirmation. So perhaps I was thinking that on_before_exit() would offer the ability to cancel.

In any case, that sounds like quite an advanced feature for a Pygame Zero game, and I can think of various use case for on_exit() as defined, so I'm happy to go with that.

[lordmauve]

I feel like on_enter() means that "there is more than one way to do it" because we also promote using the module scope to set up the initial game state.

[charlesej]

I think an on_enter() function is useful for encapsulating start up code, but I understand your point.

Would you like me to remove it?

[lordmauve]

I don't think we should bother with exit statuses. What you've done makes perfect sense for a general app development framework, but for Pygame Zero I think this adds unnecessary complexity.

We pay a cost for any additional complexity. It makes the documentation longer and adds terms that beginners may not be familiar with (and are unlikely to need). Here I suspect they will not know what an exit status is, and there are very few cases where it would be useful for them.

There is a very slightly stronger case that you can pair up exit(n) with on_exit(n), so you can signal different exit conditions. But there are other ways to deal with this, eg. setting global flags.

I guess our expectations differ. I expect exit() to be very rarely used, because most games don't need to manage their own quitting. Meanwhile on_exit() would be used rarely, eg to save scores or game state.

[penguintutor]

It looks like this issue has stalled. I've seen someone else asking for this feature on reddit.

I don't see much need for a status code for most users. Perhaps there is someone that it may be helpful to, but it think a simple on_exit() would be sufficient.

I'm happy to have a go at making the changes and creating a pull-request, if that will help.

[Mambouna]

As nothing more has happened, I'd pick it up if you want any more changes @lordmauve.

I think one question about an on_enter() function would be how variables defined within should interact with other functions. From how I've used PGZero so far in classes, we make use of global variables a lot simply because it's an easy workflow to understand. Adding on_enter() would mean that this has to be done more explicitely. I think this could be good in some ways, but it might also add more common error points for beginners since working with Actors for example doesn't go wrong easily even if one does not declare global for them in update() or draw().