Reference Manual
Inti Logo
Main Page | Namespace List | Class Hierarchy | Alphabetical List | Compound List | File List | Namespace Members | Compound Members | File Members

Inti::Gtk::Object Class Reference

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

#include <inti/gtk/object.h>

Inheritance diagram for Inti::Gtk::Object:

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

Public Member Functions

Constructors
Accessors
Methods
Property Proxies
Signal Proxies

Protected Member Functions

Constructors
Signal Handlers

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 Inti, 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

Inti::Gtk::Object::Object GtkObject *  object,
bool  reference = false
[explicit, protected]
 

Construct a new Object from an existing GtkObject.

Parameters:
object A pointer to a GtkObject.
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 Inti::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 Inti's use only.

Reimplemented from Inti::G::Object.

virtual void Inti::Gtk::Object::on_destroy  )  [protected, virtual]
 

Called when the holder of a reference should release the reference that they hold.

This may result in finalization of the object if all references are released.

virtual void Inti::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 Inti::G::Object.

void Inti::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.


The documentation for this class was generated from the following file: Main Page - Footer


Generated on Sun Sep 14 20:08:17 2003 for Inti by doxygen 1.3.2 written by Dimitri van Heesch, © 1997-2002