Reference Counting.
-------------------

The Inti C++ wrapper classes use the GTK+ reference counting system and its rules. The wrapper classes
do not increment or decrement their GObject instance's reference count. When you create a new wrapper 
class its reference count is that of the wrapped GObject instance. Its the programmers responsibility
the handle the reference counting correctly. Most of the time you wont have to do any thing.


Life cycle of a G::Object.
--------------------------

In Inti its the GTK+ GObject instance that controls the life cycle of a G::Object. When the
GObject instance is destroyed the C++ wrapper class gets destroyed as well. Each GObject instance
can only have one wrapper class and the wrapper class cannot persist beyond the lifetime of the
wrapped GObject instance. Reference counting is used to keep a G::Object alive so it can be used.
Inti uses the same reference counting rules as GTK+. To increment an object's reference count
call ref() and to decrement it call unref();

Smart Pointers.
---------------

The Inti smart pointer Inti::Pointer<> is a stack-based object that controls your interaction with
a heap-based object. Every object inherits a referenced bool flag from ReferencedBase. The
the inherited accessor function is_referenced() returns true if referenced is set to true and returns 
false if it is set to false. The referenced flag is set by an objects protected constructor and represents
whether or not Inti owns its initial reference count of 1.

	SomeObject(GtkSomeObject *object, bool reference = true or false);

An object's protected constructor supplies a default value for the 'reference' argument and so can usually
be ignored. For an object derived from G::Object but not derived from Gtk::Object (e.g. Gtk::Style) Inti
owns the initial reference and referenced is set to true. These objects must be explicitly unreferenced.
Objects derived from Gtk::Object are initially in a floating state and no one owns the initial reference
so referenced is set to false. These objects don't need to be explicitly unreferenced if they are added
to a container or passed by argument to another object which takes over ownership of the initial reference
count. Such objects will sink and later dereference the object for you. There are a few notable exceptions.
Gtk::Window is a toplevel window and is always owned by GTK+ so it only needs to be unreferenced if you
referenced it. Gtk::ItemFactory is never in the floating state so must be explicitly unreferenced.

The referenced flag lets Inti::Pointer<> know whether it should assume responsibility for an object's
initial reference count. When assigning a Inti object pointer to a Inti::Pointer<> if is_referenced() is
true an object's reference count is not incremented but it is decremented when the Inti::Pointer<> goes out
of scope. This means that the Inti::Pointer<> has taken over the ownership of the initial reference count.
When is_referenced() is false an object's reference count is both incremented and decremented leaving the
ownership of the initial reference count unaffected. Without the referenced flag Inti would need two
smart pointer classes, one for each case and you would have to decide which one to use.

If the GTK+ object reference counting rules sound a bit confusing they are, initially, but its something
you just have to learn. Once you do it's easy. 

The point of the above explanation is simply this, Inti::Pointer<> knows what to do and when to do it. 
So, for convenience or if in doubt, use a smart pointer to avoid memory leaks. If you don't objects you
create will have to be explicitly unreferenced.

Object pointers returned from accessor functions are only returned as a Inti::Pointer<> when the object
pointer must be unreferenced. This isn't very often. Methods occasionally require a Inti::Pointer<> as
an argument.

The Inti Development Team.

