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.