GNOME Bugzilla – Bug 605333
Confusing error in documentation
Last modified: 2010-03-12 20:07:53 UTC
Hello, I am now studying GTK with the official tutorial. When I got to this page http://library.gnome.org/devel/gtk-tutorial/stable/x281.html I found something confusing there. Here it goes: 'Here are two examples of connecting a signal handler to an object, in this case, the window. Here, the "delete_event" and "destroy" signals are caught. The first is emitted when we use the window manager to kill the window, or when we use the gtk_widget_destroy() call passing in the window widget as the object to destroy. The second is emitted when, in the "delete_event" handler, we return FALSE.' I guess that the author wanted to write 'The first is emmited when we use the window manager to kill the window. The second is emmited when we use the gtk_widget_destroy() call... or when in the "delete_event" handler we return FALSE.' Instead of writing 'The first is emmited when A and the second - when B or C' he wrote 'The first is emmited when A or B and the second - when C', where A = using the window manager to kill the window, B = using gtk_widget_destroy(), C = returning FALSE in the "delete_event". I spent some time understanding what was wrong. I think it'd be nice to correct the sentence.
I'd like to add that I checked if the "delete_event" is emitted when the gtk_widget_destroy() is called. The answer is NO: "delete_event" is emmited only during an attempt to close the window via the window manager. So the tutorial page needs to be corrected.
Moving to GTK as this is an issue in GTK documentation but not in the library.gnome.org service.
Created attachment 150823 [details] [review] Spell delete-event with hyphen and don't cast to G_OBJECT
Created attachment 150824 [details] [review] Reword explanation of delete-event and destroy
Created attachment 150825 [details] [review] Remove most remaining G_OBJECT casts
I don't mind committing those fixes, but the tutorial is entirely outdated and needs a serious face-lift to become useful again.
The way I see it, it's better to improve it partially than not at all because nobody has time to rewrite it. People use it, and don't realize wrong recommendations.
I agree with Christian here: we can fix the actual tutorial until the rewrite is done
I committed the above patches.