Realization

The realize and unrealize class functions are registered as signals. Realization is the process of creating GDK resources associated with the widget; including but not limited to widget->window and widget->style.

A realize method should do the following:

• Set the GTK_REALIZED flag.

• Create the widget's windows, especially widget->window which should be a child of the widget's parent's widget->window (obtained with gtk_widget_get_parent_window()).

• Place a pointer to the widget in the user data field of each window.

• For windowless widgets, widget->window should be set to the parent widget's window (obtained with gtk_widget_get_parent_window()). These widgets should also increase the reference count on widget->window by calling gdk_window_ref().

• Set widget->style using gtk_style_attach().

• Set the background of each window using gtk_style_set_background() if possible, and failing that using some color from the style. A windowless widget should not do this, since its parent already has.

The default implementation of realize is only appropriate for windowless widgets; it sets the GTK_REALIZED flag, sets widget->window to the parent widget's window, increases the reference count on the parent's window, and sets widget->style. Widgets with their own GdkWindow must override the realize method.

The "realize" signal invokes the realize method as its default handler. This signal should never be emitted directly, because there are substantial pre- and post-conditions to be enforced. gtk_widget_realize() takes care of the details. Among other things, it ensures that the widget's parent is realized; GTK+ maintains the invariant that widgets cannot be realized unless their parents are also realized.

As you might expect, the unrealize method reverses a widget's realization, freeing the resources created in realize. The default unrealize method is appropriate for all widgets; it does the following:

• Unmaps the widget if the widget is mapped; remember the GTK+ invariant that all mapped widgets are realized.

• Unrealizes all child widgets, if the widget is a container; this maintains the invariant that widgets cannot be realized unless their parents are also realized.

• Unreferences widget->style.

• Destroys widget->window (windowless widgets only unreference it).

• Unsets the GTK_REALIZED flag.

Widgets are required to chain up if they override their base class's unrealize method. This ensures that all resources are freed. Overriding the default method may be necessary if a widget has more than one GdkWindow or other special needs. All windows should be destroyed just as GtkEv destroys its event_window, that is, the window's user data field should be set to NULL before destruction:

      gdk_window_set_user_data(ev->event_window, NULL);
      gdk_window_destroy(ev->event_window);
      ev->event_window = NULL;

      

This keeps GTK+ from sending a useless GDK_DESTROY event for the window.

The "unrealize" signal is emitted via gtk_widget_unrealize(). gtk_widget_unrealize() does some internal bookkeeping which is important but not very interesting; just be careful to use this function rather than emitting the signal directly.