GDK objects have either reference counting or destruction,
but not both. Pixmaps, fonts, graphics contexts, and
colormaps are purely reference counted. (gdk_gc_destroy() exists but is deprecated
--- it's just a wrapper for
gdk_gc_unref().) In general, reference counting is
analagous to GtkObject
reference counting. That is, objects start with a reference
count of one; when the reference count reaches 0 then the
object is destroyed.
Cursors and images are not reference counted; they simply
have a destroy function. Some types represent static
objects that are never destroyed;
GdkVisual is the main example.
GdkWindow is the strange
case; it's reference counted, but
gdk_window_destroy()must be
called at some point. The reference counting applies to the
client-side GdkWindow
handle;
gdk_window_destroy() applies to the actual
server-side object. See the
section called
GdkWindow for an explanation of the
distinction.
gdk_window_destroy() unreferences the client-side
handle after it destroys the server-side object. It's safe
to call any of the
GdkWindow functions on a destroyed window that still
has a reference count greater than zero; they will all
return immediately without taking any action.
In practice this means that one section of code should
"own" the GdkWindow; it
will create the window, and hold the initial reference
(remember that objects are created with a reference count
of one). It will also call
gdk_window_destroy() eventually, destroying the
server-side object and removing the initial reference
count. If no other code increases the count, the
client-side handle will be freed. If some other code has
increased the reference count with
gdk_window_ref(), the client-side handle will remain
safe to use but attempts to use it will have no effect.
When the reference count is eventually decremented to zero,
the client-side handle will be freed.
In GTK+, windows are generally created and destroyed by the
same widget; if other widgets want to draw on the window,
they increase the window's reference count.
