Four methods are provided to show and hide widgets. show and hide are rarely overridden; the
default implementations almost always suffice. show_all and hide_all are overridden by container
widgets; they show or hide the container and all its
children. Their default implementation simply shows the
widget itself: no non-container should need to change
this. "show" and "hide" are registered as signals, but the
_all variants are not.
The default implementation of
show sets the
GTK_VISIBLE flag, and maps the widget if its
parent is mapped. When containers are mapped, they map
any children with the
GTK_VISIBLE flag set. Thus, the show implementation ensures that a
widget will be mapped eventually. (When a widget is
finally mapped, the
GTK_MAPPED flag is set in addition to GTK_VISIBLE.)
The default hide
implementation does the opposite: it unsets the GTK_VISIBLE flag, and unmaps
the widget if GTK_MAPPED
is set.
The default map and unmap implementations are much
more frequently overridden. The default implementations
should suffice for windowless widgets and widgets with a
single window (widget->window). Widgets with
additional subwindows or other special needs may need to
override the defaults.
The map method is responsible for putting a widget on the
screen. The default implementation sets the GTK_MAPPED flag, and calls gdk_window_show() on widget->window for widgets that
have a window. If a widget has subwindows, or needs to
take any special action when it appears on the screen, it
must override the map method. (It may optionally chain up
to the default method, however.) Container widgets are
required to override the map method, because they must
iterate over their children and map each child widget
with the GTK_VISIBLE flag
set (i.e., each child widget that's been shown).
The unmap method is simply the reverse of the map method;
it undoes anything the map method did. By default, it
unsets the GTK_MAPPED
flag and calls
gdk_window_hide() to hide
widget->window. Container widgets must override
the method to unmap their child windows.
Keep in mind that none of these methods are invoked
directly; they are invoked by calling gtk_widget_show(),
gtk_widget_map(), and so on. These functions may
perform special actions before and after invocation. Here
is a summary:
-
gtk_widget_show() "queues a
resize" on the widget before emitting the show
signal. This means notifying the widget's parent
container that it should rearrange its layout.
-
gtk_widget_hide() does the
same, since a newly-invisible widget implies
recalculating the layout just as a newly-visible one
does.
-
gtk_widget_show_all() and
gtk_widget_hide_all() don't
do anything special, they simply invoke the
corresponding class function.
-
gtk_widget_map() realizes
the widget before emitting the
"map" signal, if the widget is not realized.
This maintains an important invariant (all mapped
widgets are also realized). After emitting the
signal, gtk_widget_map()
queues a draw for windowless widgets; widgets with
windows will receive an expose event when the window
appears on the screen, so queueing a draw is not
necessary.
-
gtk_widget_unmap() redraws
part of the parent widget if a windowless child is
unmapped (remember that windowless widgets draw on
their parent's
widget->window).
