GNOME Bugzilla – Bug 688896
Add documentation for GtkWidget::show,hide,map,unmap,realize,unrealize
Last modified: 2013-04-29 06:26:24 UTC
As mentioned in bug 668744, there are several signals on base classes that are conspicuously absent. Attaching a patch to add some documentation for several GtkWidget signals.
Created attachment 229658 [details] [review] add documentation for several GtkWidget signals
Review of attachment 229658 [details] [review]: ::: gtk/gtkwidget.c @@ +1431,3 @@ * @widget: the object which received the signal. + * + * The ::show signal is emitted when @widget is hidden, for example with shown, not hidden. @@ +1464,3 @@ + * + * The ::map signal is emitted when the #GdkWindow associated with the widget + * has been requested to be shown. Generally, this will happen after mmh, this is incorrect. the ::map signal will be emitted when the widget is going to be mapped, i.e. it is visible and all its parents up to the top level that contains it are visible. the ::mapped signal can be used to determine whether a widget will be drawn, for instance it can resume an animation that was stopped during the emission of ::unmap. @@ +1482,3 @@ + * + * The ::unmap signal is emitted when the #GdkWindow associated with @widget + * is hidden, for example with gdk_window_hide(). This normally occurs this is incorrect. ::unmap will be emitted when the widget is unmapped - which means that it has been set as hidden or if any of its parents up to the top level have been set has hidden. @@ +1499,3 @@ + * + * The ::realize signal is emitted when @widget is associated with a + * #GdkWindow. Generally, this will happen after #GtkWidget::show has been I'd remove the whole "generally" sentence, here: either we document the invariants or we don't. I'd rather have the invariants documented, to be fair - i.e. the ::realized signal is emitted when the Widget is associated with a GdkWindow, which means gtk_widget_realize() has been called, or the widget has been mapped (i.e. it is going to be drawn). @@ +1517,3 @@ + * The ::unrealize signal is emitted when the #GdkWindow associated with + * @widget is destroyed, which normally occurs during the process of hiding + * the widget and after #GtkWidget::unmap has been emitted. same as above.
Created attachment 229685 [details] [review] updated as per comment 2 Thanks for the review, I think that I fixed everything you mentioned in this updated patch. (In reply to comment #2) > ::: gtk/gtkwidget.c > @@ +1431,3 @@ > * @widget: the object which received the signal. > + * > + * The ::show signal is emitted when @widget is hidden, for example with > > shown, not hidden. Oops, fixed. > @@ +1464,3 @@ > + * > + * The ::map signal is emitted when the #GdkWindow associated with the > widget > + * has been requested to be shown. Generally, this will happen after > > mmh, this is incorrect. > > the ::map signal will be emitted when the widget is going to be mapped, i.e. it > is visible and all its parents up to the top level that contains it are > visible. > > the ::mapped signal can be used to determine whether a widget will be drawn, > for instance it can resume an animation that was stopped during the emission of > ::unmap. Thanks, I was reading too much into the information in docs/widget_system.txt. ::mapped does not exist, so I replaced it with ::map. > @@ +1482,3 @@ > + * > + * The ::unmap signal is emitted when the #GdkWindow associated with @widget > + * is hidden, for example with gdk_window_hide(). This normally occurs > > this is incorrect. > > ::unmap will be emitted when the widget is unmapped - which means that it has > been set as hidden or if any of its parents up to the top level have been set > has hidden. I fixed this and added an example use case (not very imaginatively, it involved stopping an animation). > @@ +1499,3 @@ > + * > + * The ::realize signal is emitted when @widget is associated with a > + * #GdkWindow. Generally, this will happen after #GtkWidget::show has been > > I'd remove the whole "generally" sentence, here: either we document the > invariants or we don't. > > I'd rather have the invariants documented, to be fair - i.e. the ::realized > signal is emitted when the Widget is associated with a GdkWindow, which means > gtk_widget_realize() has been called, or the widget has been mapped (i.e. it is > going to be drawn). OK, I went with this approach. > @@ +1517,3 @@ > + * The ::unrealize signal is emitted when the #GdkWindow associated with > + * @widget is destroyed, which normally occurs during the process of hiding > + * the widget and after #GtkWidget::unmap has been emitted. > > same as above. OK, and I took the same approach as for unmapped.
(In reply to comment #3) > OK, and I took the same approach as for unmapped. unmapped → realize
Review of attachment 229685 [details] [review]: Looks ok to me now