diff options
author | James Henstridge <james@daa.com.au> | 2003-03-12 15:35:37 +0000 |
---|---|---|
committer | James Henstridge <jamesh@src.gnome.org> | 2003-03-12 15:35:37 +0000 |
commit | 40a7989166bae60a63a499d2ec74cf523ff8d118 (patch) | |
tree | b46a9e2a740cc8d0a86889fa04c6dacfde247c42 /gobject | |
parent | 5b8e99787fd98095b75e8e464b14bc8256b73166 (diff) | |
download | pygobject-40a7989166bae60a63a499d2ec74cf523ff8d118.tar.gz |
add some documentation.
2003-03-12 James Henstridge <james@daa.com.au>
* pygtype.c: add some documentation.
Diffstat (limited to 'gobject')
-rw-r--r-- | gobject/pygtype.c | 100 |
1 files changed, 100 insertions, 0 deletions
diff --git a/gobject/pygtype.c b/gobject/pygtype.c index 13218e77..173ab195 100644 --- a/gobject/pygtype.c +++ b/gobject/pygtype.c @@ -62,6 +62,14 @@ PyTypeObject PyGTypeWrapper_Type = { NULL }; +/** + * pyg_type_wrapper_new: + * type: a GType + * + * Creates a Python wrapper for a GType. + * + * Returns: the Python wrapper. + */ PyObject * pyg_type_wrapper_new(GType type) { @@ -76,6 +84,15 @@ pyg_type_wrapper_new(GType type) return (PyObject *)self; } +/** + * pyg_type_from_object: + * obj: a Python object + * + * converts a python object to a GType. Raises an exception if it + * can't perform the conversion. + * + * Returns: the corresponding GType, or 0 on error. + */ GType pyg_type_from_object(PyObject *obj) { @@ -136,6 +153,19 @@ pyg_type_from_object(PyObject *obj) /* -------------- GValue marshalling ------------------ */ +/** + * pyg_enum_get_value: + * @enum_type: the GType of the flag. + * @obj: a Python object representing the flag value + * @val: a pointer to the location to store the integer representation of the flag. + * + * Converts a Python object to the integer equivalent. The conversion + * will depend on the type of the Python object. If the object is an + * integer, it is passed through directly. If it is a string, it will + * be treated as a full or short enum name as defined in the GType. + * + * Returns: 0 on success or -1 on failure + */ gint pyg_enum_get_value(GType enum_type, PyObject *obj, gint *val) { @@ -178,6 +208,21 @@ pyg_enum_get_value(GType enum_type, PyObject *obj, gint *val) return res; } +/** + * pyg_flags_get_value: + * @flag_type: the GType of the flag. + * @obj: a Python object representing the flag value + * @val: a pointer to the location to store the integer representation of the flag. + * + * Converts a Python object to the integer equivalent. The conversion + * will depend on the type of the Python object. If the object is an + * integer, it is passed through directly. If it is a string, it will + * be treated as a full or short flag name as defined in the GType. + * If it is a tuple, then the items are treated as strings and ORed + * together. + * + * Returns: 0 on success or -1 on failure + */ gint pyg_flags_get_value(GType flag_type, PyObject *obj, gint *val) { @@ -260,6 +305,19 @@ static GQuark pyg_boxed_marshal_key = 0; #define pyg_boxed_lookup(boxed_type) \ ((PyGBoxedMarshal *)g_type_get_qdata((boxed_type), pyg_boxed_marshal_key)) + +/** + * pyg_register_boxed_custom: + * @boxed_type: the GType for boxed type + * @from_func: a function to convert GValues to Python objects + * @to_func: a function to convert Python objects to GValues + * + * The standard way of wrapping boxed types in PyGTK is to create a + * subclass of gobject.GBoxed and register it with + * pyg_register_boxed(). In some cases however, it is useful to have + * fine grained control over how a particular type is represented in + * Python. This function allows you to register such a handler. + */ void pyg_register_boxed_custom(GType boxed_type, fromvaluefunc from_func, @@ -276,6 +334,18 @@ pyg_register_boxed_custom(GType boxed_type, g_type_set_qdata(boxed_type, pyg_boxed_marshal_key, bm); } +/** + * pyg_value_from_pyobject: + * @value: the GValue object to store the converted value in. + * @obj: the Python object to convert. + * + * This function converts a Python object and stores the result in a + * GValue. The GValue must be initialised in advance with + * g_value_init(). If the Python object can't be converted to the + * type of the GValue, then an error is returned. + * + * Returns: 0 on success, -1 on error. + */ int pyg_value_from_pyobject(GValue *value, PyObject *obj) { @@ -690,6 +760,18 @@ pyg_closure_marshal(GClosure *closure, pyg_unblock_threads(); } +/** + * pyg_closure_new: + * callback: a Python callable object + * extra_args: a tuple of extra arguments, or None/NULL. + * swap_data: an alternative python object to pass first. + * + * Creates a GClosure wrapping a Python callable and optionally a set + * of additional function arguments. This is needed to attach python + * handlers to signals, for instance. + * + * Returns: the new closure. + */ GClosure * pyg_closure_new(PyObject *callback, PyObject *extra_args, PyObject *swap_data) { @@ -807,6 +889,15 @@ pyg_signal_class_closure_marshal(GClosure *closure, pyg_unblock_threads(); } +/** + * pyg_signal_class_closure_get: + * + * Returns the GClosure used for the class closure of signals. When + * called, it will invoke the method do_signalname (for the signal + * "signalname"). + * + * Returns: the closure. + */ GClosure * pyg_signal_class_closure_get(void) { @@ -1002,6 +1093,15 @@ static PyTypeObject PyGObjectDoc_Type = { (descrsetfunc)0 }; +/** + * pyg_object_descr_doc_get: + * + * Returns an object intended to be the __doc__ attribute of GObject + * wrappers. When read in the context of the object it will return + * some documentation about the signals and properties of the object. + * + * Returns: the descriptor. + */ PyObject * pyg_object_descr_doc_get(void) { |