[gtkmm: 1/2] Expose the "destroy" signal, emitted by dispose.

[Kjell Ahlstedt <kjellahl src gnome org>]

commit cfd28feae2c123dea7272d4441d21a01847f43cc
Author: Baldvin Kovacs <baldvin kovacs gmail com>
Date:   Tue Aug 2 11:59:53 2022 +0000

    Expose the "destroy" signal, emitted by dispose.

 gtk/src/widget.hg | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
---
diff --git a/gtk/src/widget.hg b/gtk/src/widget.hg
index 0b6974cc..5182aac9 100644
--- a/gtk/src/widget.hg
+++ b/gtk/src/widget.hg
@@ -571,6 +571,30 @@ public:
 
   _WRAP_SIGNAL(bool mnemonic_activate(bool group_cycling), "mnemonic_activate")
 
+  // Use this if you are implementing an object, which is 1. a direct
+  // descendant of Gtk::Widget, 2. contains other objects, and 3. want it to
+  // work well as a managed object. The children of the object need to be
+  // unparented *both* from the handler of this signal *and* from the
+  // destructor. Reason: when your class is used as a managed object, then the
+  // C++ destructor is called too late, but when your class is managed via the
+  // standard C++ manner, then this signal is not emitted at all.
+  //
+  // When your class inherits from Gtk::Box, you do not need to worry about
+  // handling this signal, Box will do the unparenting for you. When you are
+  // implementing a custom widget that does not have contained widgets, but
+  // rather only uses custom drawing, then you also do not need to worry about
+  // handling this signal.
+  //
+  // This signal is emitted by Gtk::Widget during the dispose phase of object
+  // destruction.  See the "Reference count" section in the GObject concepts
+  // documentation (https://docs.gtk.org/gobject/concepts.html#reference-count)
+  // for the specification of the dispose and the finalize phases of object
+  // destruction. In short: the contract is that after dispose, the object is
+  // not supposed to hold any reference to other member objects. Note that
+  // dispose may be called multiple times, so your implementation of this
+  // signal must tolerate that.
+  _WRAP_SIGNAL(void destroy(), "destroy", no_default_handler)
+
 #m4begin
 dnl// Hook in special code to catch explicit uses of gtk_object_destroy() by
 dnl// GTK+ code, e.g. when receiving the GDK_DELETE event.  For details, look