Re: Purpose of some gtk functions.

[rob <mailingLists pangolin org uk>]

On Wed, 2001-11-21 at 22:40, erikvcl silcom com wrote:
> Hi,
>
> I've looked through the GTK documentation for the purpose and proper use
> of certain GTK functions.  The tutorial and other code shows the use of:
>
> gtk_widget_ref
> gtk_widget_unref
> gtk_widget_realize
>
> I have a general idea of what these functions do, but I was wondering if
> anybody with more GTK experience than me could clarify.

gtk_widget_ref is the same as gtk_object_ref. This is also true of
unref. It dosen't really matter which you choose.

I'll explain gtk_object_ref and unref as I asume thats what you want to
know.

Ref and unref are the functions used for reference counting.
Reference counting is a solution to the following problem.

My code consistis of two parts A and B.
Both A and B need to work with object C.
When both A and B are finished with C it (C) should be destroyed (have
the memory it uses and any other resourse freed). But if either A or B
need C it should stay around.

How do we know when both A and B are finished using C?

The solution is for object C to keep track of how many things are using
it (referencing it) and when nothing is using it to destroy itself. 

Ojbect C is created it's reference count is 1.

A starts using C and references it. C's ref count is 2.

Whatever created C stops needing it removes it's reference. C's ref
count is 1;

B starts using object C and references it. C's ref count is 2 again.
B finishes using C and removes it's reference. C's ref count is now 1.

A finishs using C and removes it's reference. C's ref count is now 0 so
it destroys itself.

That's all there is to it.
You just have to make you sure remember to call ref and unref all the
time.

*Except*

When an object is created it has a reference count of 1 but it is a
speacial reference count. This reference count can be removed by
gtk_object_sink but no other reference count will be.

C = gtk_object_new()
C's ref count = 1.

gtk_object_ref(C)
C's ref count = 2.

gtk_object_sink(C). C's speacial first ref count is removed.
C's Ref count = 1.

gtk_object_ref(C)
C's ref count = 2.

gtk_object_sink(C). C's speacial first ref count has allready been
removed.
C's Ref count = 2.

This is important if the object is added to a container widget because
the container will ref it first and then sink it. So that if it still
had it's specail first reference then it's ref count will stay the same
but if it didn't it will increase by one. 

thus

label = gtk_label_new("hello");
gtk_container_add(myContainer, label);

is correct 

whilst

label = gtk_label_new("hello");
gtk_container_add(myContainer, label);
gtk_object_unref(GTK_OBJECT(label));
  
will destroy the label.

hope that helps i'll leave gtk_widget_realise for some one else.

> Thanks,
>
> Erik.
>
> _______________________________________________
> gtk-app-devel-list mailing list
> gtk-app-devel-list gnome org
> http://mail.gnome.org/mailman/listinfo/gtk-app-devel-list
-- 

rob