Re: signal functions in a package module file

[Kevin Ryde <user42 zip com au>]

Emmanuele Bassi <ebassi gmail com> writes:
> hide_on_delete() is mostly a C convenience function because C does not
> have closures: I wouldn't bind that inside an high-level language that
> does have them.

Don't forget the principle "why can't someone else do it" -- as
Springfield's most famous sanitation inspector said.  I for instance
have to check almost every time whether it's true or false to propagate
/ not propagate.

Either way perhaps some words in the docs would be an idea, per below.
(A little verbose, but the gtk reference manual is particularly poor in
this area.  Maybe the remark about glade belongs somewhere in its docs.)

--- GtkWindow.xs        10 Jan 2008 09:51:09 +1100      1.44
+++ GtkWindow.xs        25 Jul 2008 10:11:29 +1000      
@@ -23,6 +23,54 @@
 
 MODULE = Gtk2::Window  PACKAGE = Gtk2::Window  PREFIX = gtk_window_
 
+=for position DESCRIPTION
+
+=head1 DESCRIPTION
+
+A Gtk2::Window is a top-level window displayed on the root window and
+interacting (or not) with the window manager.  It can be an
+application's main window, a dialog, or a temporary such as a popup
+menu.
+
+=head2 Delete Event and Destroy
+
+The default action for a C<delete-event> (normally from the window
+manager close button) is to destroy the window with
+C<< $window->destroy >>.  In your main window you might want to exit
+the main loop when that happens.
+
+    $toplevel->signal_connect (destroy => sub { Gtk2->main_quit });
+
+If you install a handler for C<delete-event> and return true, meaning
+"don't propagate", you can do something other than destroy the window.
+For example
+
+    $toplevel->signal_connect (delete_event => sub {
+       if (any_unsaved_documents()) {
+         popup_ask_save_before_exit_dialog();
+         return 1;  # don't propagate to default destroy
+       }
+       return 0;  # do propagate
+    });
+
+In a dialog or secondary app window you might not want to destroy but
+instead just hide ready for later re-use.  The builtin function
+C<Gtk2::Widget::hide_on_delete> is designed for that.
+
+    $dialog->signal_connect (delete_event =>
+                             \&Gtk2::Widget::hide_on_delete);
+
+The choice between destroying or hiding is normally just a matter of
+memory saved against the time to re-create, and how likely the dialog
+might be needed again.  (However if you build windows with Glade it's
+not particularly easy to re-create them there, so you'll mostly want
+to just hide in that case.)
+
+A hidden toplevel window is still in
+C<< Gtk2::Window->list_toplevels >> and that's a good place to search
+for an existing window of a desired type to C<< $window->present >>
+again.
+
 =for enum GtkWindowPosition
 =cut
 

--- GtkDialog.xs        11 Dec 2007 09:30:16 +1100      1.29
+++ GtkDialog.xs        25 Jul 2008 10:13:51 +1000      
@@ -186,6 +186,46 @@
     $dialog->show_all;
  }
 
+=head2 Delete, Close and Destroy
+
+In the default keybindings the "Esc" key calls the C<close> action
+signal.  The default in that signal is to synthesise a C<delete-event>
+like a window manager close would do.
+
+A delete-event first runs the C<response> signal with ID
+C<"delete-event">, but the handler there can't influence the default
+destroy behaviour of the C<delete-event> signal.  See L<Gtk2::Window>
+for notes on destroy vs hide.
+
+If you add your own "Close" button to the dialog, perhaps using the
+builtin C<close> response ID, you must make your C<response> signal
+handler do whatever's needed for closing.  Often a good thing is just
+to run the C<close> action signal the same as the Esc key.
+
+    sub my_response_handler {
+      my ($dialog, $response) = @_;
+      if ($response eq 'close') {
+        $self->signal_emit ('close');
+
+      } elsif ...
+    }
+
+=cut
+
+=for position post_signals
+
+Note that currently in a Perl subclass of C<Gtk2::Dialog> a class
+closure, ie. class default signal handler, for the C<response> signal
+will be called with the response ID just as an integer, it's not
+turned into an enum string like C<"ok"> the way a handler setup with
+C<signal_connect> receives.
+
+Hopefully this will change in the future, so don't count on it.  In
+the interim the easiest thing to do is install your default handler in
+C<INIT_INSTANCE> with a C<signal_connect>.  (The subtleties of what
+order handlers are called in will differ, but often that doesn't
+matter.)
+
 =cut
 
 =for enum GtkResponseType