[pygtk] GObject properties

Jan Weil jagdgruende at web.de
Tue Aug 5 03:34:55 WST 2003


Jan Weil schrieb:

> 
> But could someone please enlighten me, why am I supposed to implement
> 'do_set_property' and 'do_get_property'?
> 

Once again the source was with me.
I collected my experiences as a newbie to Glib's type and object system 
approaching it from the Python site.
For me there were some pitfalls and therefore I want to share this with 
the list.
Feel free to add this wherever it may help (FAQ, examples, ?) or simply 
ignore it otherwise.
Sorry, if this belongs to the basics.

Jan

P.S. I'm still wondering why there is this '__gobject_init__' wrapper. I 
can also call gobject.GObject.__init__, right?
-------------- next part --------------

Since version 2.0 gtk+'s GtkObject is no longer a base class.
It is instead based on Glib's GObject which can also be found in the gobject
module of pygtk.
Among other things a GObject keeps a set of so-called properties.
A property is a strongly typed attribute of the object which can be
automatically initialized and (if it's writable) be set during the object's
lifetime using the set_property method. The get_property method is used to
access a property's value (if it's readable). Most importantly you can
connect to the object's 'notify' signal and thereby be notified whenever a
property is changed.

To specify the properties of an object which is derived from gobject.GObject
you define a class attribute named '__gproperties__'.
__gproperties__ is a dictionary where the keys specify the names of the
properties and the values are tuples (t) which describe the properties
containing at least four elements:
t[0]  - The property's type (gobject.TYPE_*).
t[1]  - The property's nick name (string).
t[2]  - The property's description (blurb) (string).
t[-1] - The property's flags, a bitwise or'ed combination of the following
parameter flags:

 * gobject.PARAM_CONSTRUCT
   The parameter will be set upon object construction.
 * gobject.PARAM_CONSTRUCT_ONLY 
   The parameter will only be set upon object construction.
 * gobject.PARAM_LAX_VALIDATION 
   Upon parameter conversion (see g_param_value_convert()) strict validation
   is not required.
 * gobject.PARAM_READABLE 
   The parameter is readable.
 * gobject.PARAM_WRITABLE 
   The parameter is writable.
 * gobject.PARAM_READWRITE 
   The combination of gobject.PARAM_READABLE and gobject.PARAM_WRITABLE.

Note that setting PARAM_CONSTRUCT* without PARAM_WRITABLE will fail.

The absolute length of t depends on the property's type, t[0]:
 * TYPE_BOOLEAN, TYPE_ENUM, TYPE_FLAGS, TYPE_STRING
   t[3] - default value
 * TYPE_*CHAR, TYPE_*INT*, TYPE_*LONG, TYPE_FLOAT, TYPE_DOUBLE
   t[3] - minimum
   t[4] - maximum
   t[5] - default value
 * TYPE_PARAM, TYPE_BOXED, TYPE_POINTER, TYPE_OBJECT
   no additional elements (t[3] is t[-1])

To initialize the object self.__gobject_init__ is called.
gobject.GObject.__gobject_init__ accepts keyword arguments which initialize
the object's properties, e. g. self.__gobject_init__(foo = 'bar').
These arguments are passed on to g_object_newv (internally). 
This function checks the properties' flags and initializes those properties
which have the PARAM_CONSTRUCT bit set using either the value which was passed
as a keyword argument or the default value from __gproperties__.

To actually set or get a property a Python GObject calls the class methods
'do_set_property' and 'do_get_property'. These methods are virtual which
means you'll have to implement them.
Typically most of the properties can also be controlled by a specific pair of
methods, e. g. o.set_name and o.get_name, which means the *_get_property
methods usually pass on their arguments to these class methods. Take a look
at the c source code for one of the simpler widgets like gtklabel.c for an
example.
Note that if you write these specific methods you can call the notify method
without any difficulties. All notifications are queued and signals which are
identical are emitted only once. Thereby you can be sure that the 'notify'
signal is sent whether or not the set_property method was used.



More information about the pygtk mailing list