=== New GObject APIs (bug #305560) ===
gpointer    g_object_newv_with_data           (GType           object_type,
					       guint	       n_parameters,
					       GParameter     *parameters,
                                               gpointer        data);
struct _GObjectClass {
  (...)
  GObject*   (*constructor_full) (GType                  this_type,
                                  GType                  leaf_type,
                                  guint                  n_construct_properties,
                                  GObjectConstructParam *construct_properties,
                                  gpointer               data);
  (...)
}


=== Some Scenarios ===

PyGObject's constructed from C, through g_object_new() (derived directly from GObject):

* g_object_newv(type, properties)
  - calls pyg_object_class_constructor(data=NULL)
    > object = g_type_create_instance(type);
    > wrapper = pygobject_new_full(object, sink=False);
      o self = PyObject_GC_New(tp)  (doesn't call __init__)
    > self->obj = object
    > self->ob_type->tp_init(kwargs=properties)
        # chains to parent -> pygobject_init
          * set contructor properties
    > return object
  - return object



PyGObject's constructed from C, through g_object_new() (NOT derived directly from GObject):

* g_object_newv(type, properties)
  - calls pyg_object_class_constructor(data=NULL)
    > object = g_type_create_instance(type);
    > wrapper = pygobject_new_full(object, sink=False);
      o self = PyObject_GC_New(tp)
    > self->obj = object
    > self->ob_type->tp_init(kwargs=properties)
        # chains to parent -> (say _wrap_pygtk_button_init)
          * parse arguments
          * checks that self->obj != NULL
             => set contructor properties instead of creating self->obj
    > return object
  - return object



PyGObject's constructed from python (derived directly from GObject):

*  In python land: foo = MyObject(foo=bar)
  - MyObject.__init__
    > chains to parent: GObject.tp_init(foo=bar) -> pygobject_init
      o (self->obj == NULL) => g_object_newv_with_data(type, properties, self)
        # calls pyg_object_class_constructor(type, properties=kwargs, data=self)
          * object = g_type_create_instance(type);
          * self = data
          * self->obj = object
          * pygobject_register_wrapper(self, sink=True)
          * set contructor properties taken from g_object_newv_with_data
          * return object


PyGObject's constructed from python (NOT derived directly from GObject):

*  In python land: foo = MyObject(foo=bar)
  - MyObject.__init__
    > chains to parent (say, gtk.Button.__init__(foo=bar))
      o (self->obj == NULL) => g_object_newv_with_data(type, properties=args/kwargs, self)
        # calls pyg_object_class_constructor(type, properties, data=self)
          * object = g_type_create_instance(type);
          * self = data
          * self->obj = object
          * pygobject_register_wrapper(self, sink=True)
          * set contructor properties taken from g_object_newv_with_data
          * return object


=== Tasks ===

 - Add 'sink' parameters to pygobject_new and
   pygobject_register_wrapper (introduce *_full variants)

 - Define new pygobject APIs to simplify constructors:

    * pyg_object_constructv(PyGObject *self, guint n_construct_properties,
                            GObjectConstructParam *construct_properties)
        -> if (self->obj) {
              for all construct_properties:
                  g_object_set_property(self->obj, propname, propval);
              pygobject_register_wrapper(self)
           } else
               g_object_new_with_data(type, n_construct_properties, construct_properties, self)

    * pyg_object_construct(PyGObject *self, propname, ...)
        ->  varargs, NULL terminated, just for convenience

 - Change constructors created by code generated to use
   pyg_object_constructv instead of g_object_new, and not call
   pygobject_register_wrapper

 - Make pygobject_register_wrapper not do anything if wrapper already
   registered, for compatibility with 3rd party modules (it will end
   up being called twice per object)

 - Change manually written constructors to use pyg_object_construct
   instead of g_object_new, and remove call to pygobject_register_wrapper

 - Change PyGObjectType.tp_init, make it use pyg_object_constructv

 - Write the GObject constructor_full for PyGObject

 - Pray that it works

