diff options
| -rw-r--r-- | gobject/gobjectmodule.c | 76 | ||||
| -rw-r--r-- | gobject/pygboxed.c | 50 | ||||
| -rw-r--r-- | gobject/pygobject.c | 71 |
3 files changed, 197 insertions, 0 deletions
diff --git a/gobject/gobjectmodule.c b/gobject/gobjectmodule.c index f9eb6275..122efefa 100644 --- a/gobject/gobjectmodule.c +++ b/gobject/gobjectmodule.c @@ -10,6 +10,15 @@ static PyObject *gerror_exc = NULL; /* -------------- GDK threading hooks ---------------------------- */ +/** + * pyg_set_thread_block_funcs: + * @block_threads_func: a function to block Python threads. + * @unblock_threads_func: a function to unblock Python threads. + * + * an interface to allow pygtk to add hooks to handle threading + * similar to the old PyGTK 0.6.x releases. May not work quite right + * anymore. + */ static void pyg_set_thread_block_funcs (PyGThreadBlockFunc block_threads_func, PyGThreadBlockFunc unblock_threads_func) @@ -26,6 +35,13 @@ object_free(PyObject *op) PyObject_FREE(op); } +/** + * pyg_destroy_notify: + * @user_data: a PyObject pointer. + * + * A function that can be used as a GDestroyNotify callback that will + * call Py_DECREF on the data. + */ void pyg_destroy_notify(gpointer user_data) { @@ -133,6 +149,14 @@ PyTypeObject PyGParamSpec_Type = { NULL }; +/** + * pyg_param_spec_new: + * @pspec: a GParamSpec. + * + * Creates a wrapper for a GParamSpec. + * + * Returns: the GParamSpec wrapper. + */ PyObject * pyg_param_spec_new(GParamSpec *pspec) { @@ -231,6 +255,17 @@ static PyTypeObject PyGInterface_Type = { (PyObject *)0, /* tp_bases */ }; +/** + * pyg_register_interface: + * @dict: a module dictionary. + * @class_name: the class name for the wrapper class. + * @gtype: the GType of the interface. + * @type: the wrapper class for the interface. + * + * Registers a Python class as the wrapper for a GInterface. As a + * convenience it will also place a reference to the wrapper class in + * the provided module dictionary. + */ static void pyg_register_interface(PyObject *dict, const gchar *class_name, GType gtype, PyTypeObject *type) @@ -1684,6 +1719,19 @@ static PyMethodDef pygobject_functions[] = { /* ----------------- Constant extraction ------------------------ */ +/** + * pyg_constant_strip_prefix: + * @name: the constant name. + * @strip_prefix: the prefix to strip. + * + * Advances the pointer @name by strlen(@strip_prefix) characters. If + * the resulting name does not start with a letter or underscore, the + * @name pointer will be rewound. This is to ensure that the + * resulting name is a valid identifier. Hence the returned string is + * a pointer into the string @name. + * + * Returns: the stripped constant name. + */ static char * pyg_constant_strip_prefix(gchar *name, const gchar *strip_prefix) { @@ -1702,6 +1750,15 @@ pyg_constant_strip_prefix(gchar *name, const gchar *strip_prefix) return name; } +/** + * pyg_enum_add_constants: + * @module: a Python module + * @enum_type: the GType of the enumeration. + * @strip_prefix: the prefix to strip from the constant names. + * + * Adds constants to the given Python module for each value name of + * the enumeration. A prefix will be stripped from each enum name. + */ static void pyg_enum_add_constants(PyObject *module, GType enum_type, const gchar *strip_prefix) @@ -1730,6 +1787,15 @@ pyg_enum_add_constants(PyObject *module, GType enum_type, g_type_class_unref(eclass); } +/** + * pyg_flags_add_constants: + * @module: a Python module + * @flags_type: the GType of the flags type. + * @strip_prefix: the prefix to strip from the constant names. + * + * Adds constants to the given Python module for each value name of + * the flags set. A prefix will be stripped from each flag name. + */ static void pyg_flags_add_constants(PyObject *module, GType flags_type, const gchar *strip_prefix) @@ -1758,6 +1824,16 @@ pyg_flags_add_constants(PyObject *module, GType flags_type, g_type_class_unref(fclass); } +/** + * pyg_error_check: + * @error: a pointer to the GError. + * + * Checks to see if the GError has been set. If the error has been + * set, then the gobject.GError Python exception will be raised, and + * the GError cleared. + * + * Returns: True if an error was set. + */ static gboolean pyg_error_check(GError **error) { diff --git a/gobject/pygboxed.c b/gobject/pygboxed.c index 208a8a27..2bfc2300 100644 --- a/gobject/pygboxed.c +++ b/gobject/pygboxed.c @@ -127,6 +127,17 @@ PyTypeObject PyGBoxed_Type = { static GQuark boxed_type_id = 0; +/** + * pyg_register_boxed: + * @dict: the module dictionary to store the wrapper class. + * @class_name: the Python name for the wrapper class. + * @boxed_type: the GType of the boxed type being wrapped. + * @type: the wrapper class. + * + * Registers a wrapper for a boxed type. The wrapper class will be a + * subclass of gobject.GBoxed, and a reference to the wrapper class + * will be stored in the provided module dictionary. + */ void pyg_register_boxed(PyObject *dict, const gchar *class_name, GType boxed_type, PyTypeObject *type) @@ -159,6 +170,21 @@ pyg_register_boxed(PyObject *dict, const gchar *class_name, PyDict_SetItemString(dict, (char *)class_name, (PyObject *)type); } +/** + * pyg_boxed_new: + * @boxed_type: the GType of the boxed value. + * @boxed: the boxed value. + * @copy_boxed: whether the new boxed wrapper should hold a copy of the value. + * @own_ref: whether the boxed wrapper should own the boxed value. + * + * Creates a wrapper for a boxed value. If @copy_boxed is set to + * True, the wrapper will hold a copy of the value, instead of the + * value itself. If @own_ref is True, then the value held by the + * wrapper will be freed when the wrapper is deallocated. If + * @copy_boxed is True, then @own_ref must also be True. + * + * Returns: the boxed wrapper. + */ PyObject * pyg_boxed_new(GType boxed_type, gpointer boxed, gboolean copy_boxed, gboolean own_ref) @@ -300,6 +326,17 @@ PyTypeObject PyGPointer_Type = { static GQuark pointer_type_id = 0; +/** + * pyg_register_pointer: + * @dict: the module dictionary to store the wrapper class. + * @class_name: the Python name for the wrapper class. + * @pointer_type: the GType of the pointer type being wrapped. + * @type: the wrapper class. + * + * Registers a wrapper for a pointer type. The wrapper class will be + * a subclass of gobject.GPointer, and a reference to the wrapper + * class will be stored in the provided module dictionary. + */ void pyg_register_pointer(PyObject *dict, const gchar *class_name, GType pointer_type, PyTypeObject *type) @@ -332,6 +369,19 @@ pyg_register_pointer(PyObject *dict, const gchar *class_name, PyDict_SetItemString(dict, (char *)class_name, (PyObject *)type); } +/** + * pyg_pointer_new: + * @pointer_type: the GType of the pointer value. + * @pointer: the pointer value. + * + * Creates a wrapper for a pointer value. Since G_TYPE_POINTER types + * don't register any information about how to copy/free them, there + * is no guarantee that the pointer will remain valid, and there is + * nothing registered to release the pointer when the pointer goes out + * of scope. This is why we don't recommend people use these types. + * + * Returns: the boxed wrapper. + */ PyObject * pyg_pointer_new(GType pointer_type, gpointer pointer) { diff --git a/gobject/pygobject.c b/gobject/pygobject.c index 603540ec..675a67bc 100644 --- a/gobject/pygobject.c +++ b/gobject/pygobject.c @@ -34,6 +34,19 @@ sink_object(GObject *obj) } } +/** + * pygobject_register_sinkfunc: + * type: the GType the sink function applies to. + * sinkfunc: a function to remove the floating reference on an object. + * + * As Python handles reference counting for us, the "floating + * reference" code in GTK is not all that useful. In fact, it can + * cause leaks. For this reason, PyGTK removes the floating + * references on objects on construction. + * + * The sinkfunc should be able to remove the floating reference on + * instances of the given type, or any subclasses. + */ void pygobject_register_sinkfunc(GType type, void (* sinkfunc)(GObject *object)) { @@ -47,6 +60,19 @@ pygobject_register_sinkfunc(GType type, void (* sinkfunc)(GObject *object)) g_array_append_val(sink_funcs, sf); } +/** + * pygobject_register_class: + * @dict: the module dictionary. A reference to the type will be stored here. + * @type_name: not used ? + * @gtype: the GType of the GObject subclass. + * @type: the Python type object for this wrapper. + * @bases: a tuple of Python type objects that are the bases of this type. + * + * This function is used to register a Python type as the wrapper for + * a particular GObject subclass. It will also insert a reference to + * the wrapper class into the module dictionary passed as a reference, + * which simplifies initialisation. + */ void pygobject_register_class(PyObject *dict, const gchar *type_name, GType gtype, PyTypeObject *type, @@ -98,6 +124,16 @@ pygobject_register_class(PyObject *dict, const gchar *type_name, PyDict_SetItemString(dict, (char *)class_name, (PyObject *)type); } +/** + * pygobject_register_wrapper: + * @self: the wrapper instance + * + * In the constructor of PyGTK wrappers, this function should be + * called after setting the obj member. It will tie the wrapper + * instance to the GObject so that the same wrapper instance will + * always be used for this GObject instance. It will also sink any + * floating references on the GObject. + */ void pygobject_register_wrapper(PyObject *self) { @@ -112,6 +148,18 @@ pygobject_register_wrapper(PyObject *self) pyg_destroy_notify); } +/** + * pygobject_lookup_class: + * @gtype: the GType of the GObject subclass. + * + * This function looks up the wrapper class used to represent + * instances of a GObject represented by @gtype. If no wrapper class + * has been registered for the given GType, then the parent GType will + * be checked. Since a wrapper has been registered for "GObject", + * this function will always succeed. + * + * Returns: The wrapper class for the GObject. + */ PyTypeObject * pygobject_lookup_class(GType gtype) { @@ -125,6 +173,17 @@ pygobject_lookup_class(GType gtype) return type; } +/** + * pygobject_new: + * @obj: a GObject instance. + * + * This function gets a reference to a wrapper for the given GObject + * instance. If a wrapper has already been created, a new reference + * to that wrapper will be returned. Otherwise, a wrapper instance + * will be created. + * + * Returns: a reference to the wrapper for the GObject. + */ PyObject * pygobject_new(GObject *obj) { @@ -174,6 +233,18 @@ pygobject_unwatch_closure(gpointer data, GClosure *closure) self->closures = g_slist_remove (self->closures, closure); } +/** + * pygobject_watch_closure: + * @self: a GObject wrapper instance + * @closure: a GClosure to watch + * + * Adds a closure to the list of watched closures for the wrapper. + * The closure must be one returned by pyg_closure_new(). When the + * cycle GC traverses the wrapper instance, it will enumerate the + * references to Python objects stored in watched closures. If the + * cycle GC tells the wrapper to clear itself, the watched closures + * will be invalidated. + */ void pygobject_watch_closure(PyObject *self, GClosure *closure) { |