GtkWidget documentation

[Magnus Hjorth <magnus i hjorth gmail com>]

Hi,

The GTK+ documentaion for gtk_widget_set_has_window says that widgets 
that create their own windows must in their init function call 
gtk_widget_set_has_window with has_window=TRUE.

However, it looks like in reality windowed is default and it's instead 
windowless widgets that must call gtk_widget_set_has_window with 
has_window=FALSE in their init functions.

I made a simple patch correcting this, plus filled in some signal 
documentation.

Best regards,
Magnus

diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index f02b481..b18a419 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -779,6 +779,12 @@ gtk_widget_class_init (GtkWidgetClass *klass)
   /**
    * GtkWidget::show:
    * @widget: the object which received the signal.
+   *
+   * This signal is a hook for subclasses to implement the functionality of 
+   * gtk_widget_show(). It is normally not used by applications.
+   *
+   * The default implementation sets the visible flag and calls
+   * gtk_widget_map() on the widget.
    */
   widget_signals[SHOW] =
     g_signal_new (I_("show"),
@@ -792,6 +798,12 @@ gtk_widget_class_init (GtkWidgetClass *klass)
   /**
    * GtkWidget::hide:
    * @widget: the object which received the signal.
+   *
+   * This signal is a hook for subclasses to implement the functionality of 
+   * gtk_widget_hide(). It is normally not used by applications.
+   *
+   * The default implementation clears the visible flag and calls
+   * gtk_widget_unmap() on the widget.
    */
   widget_signals[HIDE] =
     g_signal_new (I_("hide"),
@@ -805,6 +817,12 @@ gtk_widget_class_init (GtkWidgetClass *klass)
   /**
    * GtkWidget::map:
    * @widget: the object which received the signal.
+   *
+   * This signal is a hook for subclasses to implement the functionality of 
+   * gtk_widget_map(). It is normally not used by applications.
+   *
+   * The default implementation sets the widget's mapped flag and, if the
+   * widget has its own window, calls gdk_window_show on the underlying window.
    */
   widget_signals[MAP] =
     g_signal_new (I_("map"),
@@ -818,6 +836,13 @@ gtk_widget_class_init (GtkWidgetClass *klass)
   /**
    * GtkWidget::unmap:
    * @widget: the object which received the signal.
+   *
+   * This signal is a hook for subclasses to implement the functionality of 
+   * gtk_widget_unmap(). It is normally not used by applications.
+   *
+   * The default implementation clears the widget's mapped flag and,
+   * if the widget has its own window, calls gdk_window_hide on the
+   * underlying window.
    */
   widget_signals[UNMAP] =
     g_signal_new (I_("unmap"),
@@ -831,6 +856,15 @@ gtk_widget_class_init (GtkWidgetClass *klass)
   /**
    * GtkWidget::realize:
    * @widget: the object which received the signal.
+   *
+   * This signal is a hook for subclasses to implement the functionality of 
+   * gtk_widget_realize(). It is normally not used by applications.
+   *
+   * The default implementation sets the widget's realized flag, copies the 
+   * window from it's parent widget and attaches the widget's style to the window.
+   *
+   * Widgets with their own windows must override this signal, the
+   * default implementation can only be inherited for windowless widgets.
    */
   widget_signals[REALIZE] =
     g_signal_new (I_("realize"),
@@ -844,6 +878,16 @@ gtk_widget_class_init (GtkWidgetClass *klass)
   /**
    * GtkWidget::unrealize:
    * @widget: the object which received the signal.
+   *
+   * This signal is a hook for subclasses to implement the functionality of 
+   * gtk_wigdet_unrealize(). It is normally not used by applications.
+   *
+   * The default implementation unmaps the widget, unrealizes any child widgets,
+   * detaches the style, destroys the window if the widget has it's own, and 
+   * unsets the realized flag.
+   *
+   * Unlike the realize default handler, this default handler can be inherited for
+   * both windowed and windowless widgets.
    */
   widget_signals[UNREALIZE] =
     g_signal_new (I_("unrealize"),
@@ -857,7 +901,12 @@ gtk_widget_class_init (GtkWidgetClass *klass)
   /**
    * GtkWidget::size-request:
    * @widget: the object which received the signal.
-   * @requisition:
+   * @requisition: a #GtkRequisition to be filled in
+   *
+   * This signal is hook for subclasses to implement the functionality of 
+   * gtk_widget_size_request(). It is normally not used by applications.
+   *
+   * The default implementation copies the values from widget->requisition.
    */
   widget_signals[SIZE_REQUEST] =
     g_signal_new (I_("size-request"),
@@ -872,7 +921,13 @@ gtk_widget_class_init (GtkWidgetClass *klass)
   /**
    * GtkWidget::size-allocate:
    * @widget: the object which received the signal.
-   * @allocation:
+   * @allocation: position and size to be allocated to @widget
+   *
+   * This signal is a hook for subclasses to implement the functionality of 
+   * gtk_widget_size_allocate(). It is normally not used by applications.
+   *
+   * The default implementation updates widget->allocation and, if the widget
+   * has its own window, calls gdk_window_move_resize on the underlying window.
    */
   widget_signals[SIZE_ALLOCATE] = 
     g_signal_new (I_("size-allocate"),
@@ -5871,9 +5926,9 @@ gtk_widget_get_visible (GtkWidget *widget)
  * all realized widgets have a non-%NULL "window" pointer
  * (gtk_widget_get_window() never returns a %NULL window when a widget
  * is realized), but for many of them it's actually the #GdkWindow of
- * one of its parent widgets. Widgets that create a %window for
- * themselves in GtkWidget::realize() however must announce this by
- * calling this function with @has_window = %TRUE.
+ * one of its parent widgets. Widgets that do not create a %window for
+ * themselves in GtkWidget::realize() must announce this by
+ * calling this function with @has_window = %FALSE.
  *
  * This function should only be called by widget implementations,
  * and they should call it in their init() function.