[AD] set_window_close_button_callback_hook_button()

[Ben Davis <bnd25@xxxxxxxxxx>]

Hi.

First I shall quote from api.txt:
                                                          "But this is
   guaranteed to never happen in a series for which major and minor version
   numbers are fixed; in other words, two versions that differ from each
   other only by the revision (3rd) number will be strictly API compatible."

Allegro versions up to 4.1.4 had set_window_close_button() and 
set_window_close_hook(). In Allegro 4.1.5, these functions were removed and 
set_close_button_callback() was added. The rationale was that calling exit() 
from inside the handler was a bad idea.

On Windows, we were calling exit() from inside the handler. But there was a 
warning message in place for that exact reason! Furthermore, I don't see how 
this action is any different from the one carried out when Ctrl+Alt+End is 
pressed.

As for Linux, it was originally proposed that we call exit() without warning 
the user, because window managers kill the application immediately when the 
close button is pressed anyway. This is nonsense. Now that I have some Linux 
experience, I know that Allegro wouldn't get a chance to hook this function; 
and for those window managers that don't kill the app, I believe the same 
warning as in Windows should have been implemented.

Now, I'm not saying we actually want this feature (the default close button 
behaviour). Ctrl+Alt+End is considered an emergency resort, whereas clicking 
the close box is not. However, I am pointing out that this behaviour was not 
fundamentally broken and the claims that it was were unfounded.

Now, let's divide people into the following groups:

Group A: people who have never used any of the functions.
Group B: Users who didn't like the default behaviour and disabled
         the close button by calling set_window_close_button(0).
Group C: Users who registered their own handler with
         set_window_close_hook(), and may also have disabled and
         enabled the button while leaving a function registered.

If you can think of any other groups, propose them.

First let's dispel the myth that Allegro uses callbacks rather than hooks. 
Allegro contains functions called hook_config_section() and 
install_keyboard_hooks(), and the latter has been there since Allegro 3.11 (I 
can't vouch for the former). Now if you're complaining about inconsistency in 
terminology, what a great idea it would be to remove the draw_sprite() 
function! Who's with me?

The only remaining motivation for renaming a function would be if its 
functionality changed in such a way as to break Allegro programs. In this 
case, the only change is in the default behaviour. Let's have a look at how 
the above groups are affected by the change that was made.

Group A: They notice that the close box behaves more nicely. Yay!
Group B: They have to modify their source code. They remove the
         function, then Allegro does what they want.
Group C: All the set_window_close_*() calls must be replaced! This
         must be done intelligently, since we will need to pass
         the callback function multiple times.

Allow me to propose an alternative change that could have been made - and 
still can for future versions:

set_window_close_button() will enable or disable the close button, as before. 
It will default to enabled. HOWEVER, the button isn't _actually_ enabled 
unless a callback has been specified; until then, it'll appear greyed out, or 
be inoperative, depending on the window manager or whatever.

set_window_close_hook() will set a callback function. The close button will 
light up (or become operative), provided it is "enabled" as defined for the 
last function. If NULL is specified here, the close button will appear greyed 
out or be inoperative, even though it's "enabled" as defined for the last 
function.

Let's see how this change would have affected the above groups:

Group A: They notice that the close box behaves more nicely. Yay!
Group B: Their code works as before. No changes necessary.
Group C: Their code works as before. No changes necessary.

Amazing! We've removed the problematic feature - the default close button 
functionality - without breaking API or making anyone's programs malfunction.

Now, this system is slightly more elaborate than would be necessary if we 
were implementing the system from scratch. However, the developers made a 
commitment to maintaining API compatibility across all versions with the same 
major and minor version numbers, e.g. between all 4.1.x versions. It is 
saddening to see this commitment being broken for no good reason.

<plug> This API change has affected DUMB ( http://dumb.sf.net/ ); people 
download Allegro 4.1.5 WIP, then realise to their dismay that DUMB's example 
players don't compile. Commenting set_window_close_hook() out in each file is 
tedious. They get bored and go and use one of DUMB's archnemeses, JGMOD or 
FMOD. :P </plug>

The damage has already been done, but it's not too late to limit it. I 
propose that the above change be made. For those who have gone on to the new 
API, we can arrange for set_close_button_callback() to be a synonym for 
set_window_close_hook().

Any objections?

Thanks,

A slightly less than gruntled Ben.