GFC Logo GFC Title Logo
Reference Manual
Main Page  |  Namespace List  |  Alphabetical List  |  Class List  |  File List

GFC::Gtk::Object Class Reference

A GtkObject C++ wrapper class. More...

#include <gfc/gtk/object.hh>

Inheritance diagram for GFC::Gtk::Object:

GFC::G::Object GFC::G::TypeInstance GFC::Trackable GFC::Gtk::Adjustment GFC::Gtk::CellRenderer GFC::Gtk::FileFilter GFC::Gtk::Tooltips GFC::Gtk::TreeViewColumn GFC::Gtk::Widget GFC::Gtk::CellRendererPixbuf GFC::Gtk::CellRendererText GFC::Gtk::CellRendererToggle GFC::Gtk::Calendar GFC::Gtk::Container GFC::Gtk::DrawingArea GFC::Gtk::Entry GFC::Gtk::Invisible GFC::Gtk::Misc GFC::Gtk::ProgressBar GFC::Gtk::Range GFC::Gtk::Ruler GFC::Gtk::Separator List of all members.

Signal Prototypes

Public Member Functions

Constructors
Accessors
Methods
Signal Proxies

Protected Member Functions

Constructors

Detailed Description

A GtkObject C++ wrapper class.

Object is the base class for all widgets, and for a few non-widget objects such as Adjustment. Object predates G::Object; non-widgets that derive from Gtk::Object rather than G::Object do so for backward compatibility reasons. The most interesting difference between Gtk::Object and G::Object is the "floating" reference count. A G::Object is created with a reference count of 1, owned by the creator of the G::Object. (The owner of a reference is the code section that has the right to call G::Object::unref() in order to remove that reference.) A Gtk::Object is created with a reference count of 1 also, but it isn't owned by anyone. Calling G::Object::unref() on the newly-created Gtk::Object is incorrect. Instead, the initial reference count of a Gtk::Object is "floating". The floating reference can be removed by anyone at any time, by calling sink(). Sinking an object does nothing if the object is already sunk (has no floating reference).

When you add a widget to its parent container, the parent GTK+ container will do this:

    g_object_ref (G_OBJECT (child_widget));
    gtk_object_sink (GTK_OBJECT (child_widget));
This means that the container now owns a reference to the child widget (since it called g_object_ref()), and the child widget has no floating reference. If you want to hold onto a reference to the child widget you would have to reference then sink the child widget yourself. In GFC, Gtk::Object::ref() does this for you, by sinking any widget with a floating reference.

The purpose of the floating reference is to keep the child widget alive until you add it to a parent container:

    Gtk::Button *button = new Gtk::Button;
    // button has one floating reference to keep it alive.
    
    container->add(*button);
    // button has one non-floating reference owned by the container.

Gtk::Window is a special case, because GTK+ itself will ref/sink it on creation. That is, after constructing a new Gtk::Window it will have one reference which is owned by GTK+, and is not a floating reference.

One more factor comes into play: the "destroy" signal, emitted by the Gtk::Object::dispose() method. The "destroy" signal asks all code owning a reference to an object to release said reference. So, for example, if you call Gtk::Object::dispose() on a Gtk::Window, GTK+ will release the reference count that it owns; if you call Gtk::Object::dispose() on a Button, then the button will be removed from its parent container and the parent container will release its reference to the button. Because these references are released, calling dispose() should result in freeing all memory associated with an object, unless some buggy code fails to release its references in response to the "destroy" signal. Freeing memory (referred to as finalization) only happens if the reference count reaches zero.

Some simple rules for handling Gtk::Object's:


Constructor & Destructor Documentation

GFC::Gtk::Object::Object GtkObject *  object,
bool  owns_reference = false
[explicit, protected]
 

Construct a new Object from an existing GtkObject.

Parameters:
object A pointer to a GtkObject.
owns_reference Set false if the initial reference count is floating, set true if it's not.

The object can be a newly created GtkObject or an existing GtkObject (see G::Object::Object).


Member Function Documentation

virtual void GFC::Gtk::Object::dispose  )  [virtual]
 

Emits the "destroy" signal notifying all reference holders that they should release the object.

See the overview documentation at the top of the page for more details. The memory for the object itself won't be deleted until its reference count actually drops to 0; dispose() merely asks reference holders to release their references, it does not free the object. This method is declared virtual for GFC's use only.

Reimplemented from GFC::G::Object.

virtual void GFC::Gtk::Object::ref  )  [virtual]
 

Increases the reference count of the object.

This method calls G::Object::ref() first and then sink() to sink the object if it has a floating reference.

Reimplemented from GFC::G::Object.

void GFC::Gtk::Object::sink  ) 
 

Removes the floating reference from an object, if it exists; otherwise does nothing.

The ref() method calls this function to sink any object with a floating reference. So as a rule you shouldn't need to call this method at all.


Member Data Documentation

const DestroySignalType GFC::Gtk::Object::destroy_signal [static, protected]
 

Destroy signal (see sig_destroy()).

Calls a slot with the signature:

             void function();


The documentation for this class was generated from the following file:
Generated on Tue Aug 24 00:34:41 2004 for GFC-UI by doxygen 1.3.8