Memory Management.
------------------

In Inti memory management is not simple but it is easy, if you follow a few rules.

* Most of the time you should create objects dynamically on the heap using operator new.
	
		Gtk::Button *button = new Button("Button");
	
* Occasionally you can create transient objects on the stack.
	
		Gtk::MessageDialog dialog(GTK_MESSAGE_ERROR, GTK_BUTTONS_CLOSE, this);
		dialog.set_message("Failed to read icon file: %s", error.message());
		dialog.set_position(GTK_WIN_POS_CENTER);
		dialog.run();
		dialog.dispose();
		
* Never, ever call operator delete on an Inti object. Operator delete is called internally
  by Inti when the wrapped GTK+ C object is destroyed.

* Inti objects are referenced counted and it is this reference count that controls an object's
  lifetime and destruction. To increase an object's reference count call ref(). To decrease an
  object's reference count call unref(). An object is only destroyed when it's reference count
  becomes zero.
	  
* The Inti reference counting rules are the same as those used by GTK+.

* Each time you call ref() on an object you must call unref(), but you don't always need to call ref().

* Objects derived directly from G::Object are created with a reference count of one which you own.
  You don't need to call ref() on these objects to use them but you must call unref() when your
  finished.

		Gtk::Style *style = new Gtk::Style;
		... // use style
		style->unref();
	  		
* Objects derived directly from Gtk::Object are created with a floating reference count of one.
  The floating reference count keeps an object alive until it gets claimed. To claim ownership
  of a floating object call ref(). If an object is floating ref() will also call gtk_object_sink()
  to clear the floating reference count. You don't need to call gtk_object_sink() so there is no
  sink() function. If you pass a floating object to an owner object through an API method or add
  it to a container and don't need to hold a reference to it you don't need to call ref(). The
  object it's being added to will reference and sink the object and dereference it when its no
  longer required. For example:

		Gtk::Adjustment *adjustment = new Gtk::Adjustment(0.0, 100.0, 1.0, 1.0, 10.0);
		scroll_window->set_vadjustment(adjustment);

* Objects derived from Gtk::Widget can be added to container objects. You don't need to call ref()
  or unref() on these objects unless you specially want to hold onto a reference.

* To make memory management easier Inti has the built-in smart pointer class Pointer<>. Some class
  accessor functions return a raw C++ pointer and some return an Inti smart pointer. Raw C++ 
  pointers are returned when the object being pointed to has its reference count managed by the 
  container or parent object. You must not unref() an object through such pointer unless you first
  called ref(). For example:

		Gtk::Widget *widget = container->get_child(); // do not unref()

* A function returns a smart pointer to an object if either the object being pointed to was newly
  created and must be unreferenced or if the object's reference count was incremented. The smart
  pointer will call unref() on the object when it goes out of scope. For example:
  
		Pointer<Atk::Object> accessible = widget->ref_accessible();


The Inti Development Team.
	
