[perl-Gtk2] Gtk2::Gdk::Window: add docs on subclassing and not using Glib::Object::new()

[Torsten SchÃnfeld <tsch src gnome org>]

commit 0aea077229b3857118ea54b9367c140d12cd69e1
Author: Kevin Ryde <user42 zip com au>
Date:   Wed Aug 31 09:19:59 2011 +1000

    Gtk2::Gdk::Window: add docs on subclassing and not using Glib::Object::new()
    
    https://bugzilla.gnome.org/show_bug.cgi?id=639559

 xs/GdkWindow.xs |   23 +++++++++++++++++++++++
 1 files changed, 23 insertions(+), 0 deletions(-)
---
diff --git a/xs/GdkWindow.xs b/xs/GdkWindow.xs
index fc614ca..98d1c5a 100644
--- a/xs/GdkWindow.xs
+++ b/xs/GdkWindow.xs
@@ -193,6 +193,29 @@ gtk2perl_gdk_window_invalidate_maybe_recurse_func (GdkWindow *window,
 
 MODULE = Gtk2::Gdk::Window	PACKAGE = Gtk2::Gdk::Window	PREFIX = gdk_window_
 
+=for position DESCRIPTION
+
+=head1 DESCRIPTION
+
+C<Gtk2::Gdk::Window> is a low-level window-system window.  One of
+these is created when a widget is "realized".
+
+As of Gtk 2.22 a window can only be created by
+C<< Gtk2::Gdk::Window->new() >>, C<foreign_new()>, etc.
+C<Glib::Object::new()> doesn't work (segfaults on using the resulting
+window object).  It's not possible to subclass C<Gtk2::Gdk::Window>
+with L<Glib::Object::Subclass> and the C<Glib::Type> system, since
+only C<gdk_window_new()> does the actual window creation, and that
+function always makes a C<GdkWindow>.  (The Perl-Gtk
+C<< Gtk2::Gdk::Window->new() >> wrapper ignores the class name
+argument.)
+
+It may work to create a Perl level subclass and re-bless a
+C<< Gtk2::Gdk::Window->new() >> into that.  But like any such
+re-blessing it's not preserved when the object is returned from a Gtk
+function etc (that just gives the base Gtk class).
+
+=cut
 
 BOOT:
 #if GTK_CHECK_VERSION (2, 18, 0)