From b8fcf708d0de7991d507c509f1b631e84cf532ad Mon Sep 17 00:00:00 2001 From: Stefan Kost Date: Wed, 7 Feb 2007 22:15:34 +0000 Subject: [PATCH] Unify spelling of GObject and GType. Improve some wording. Update the * gobject/tut_gobject.xml: * gobject/tut_gsignal.xml: * gobject/tut_gtype.xml: * gobject/tut_howto.xml: * gobject/tut_tools.xml: Unify spelling of GObject and GType. Improve some wording. Update the usage of private data. Make tables use row-spans and add id's to them. svn path=/trunk/; revision=5327 --- docs/reference/ChangeLog | 10 ++++ docs/reference/gobject/tut_gobject.xml | 85 +++++++++++++++++++++------------- docs/reference/gobject/tut_gsignal.xml | 6 +-- docs/reference/gobject/tut_gtype.xml | 50 +++++++++++--------- docs/reference/gobject/tut_howto.xml | 29 +++++------- docs/reference/gobject/tut_tools.xml | 30 ++++++------ 6 files changed, 122 insertions(+), 88 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 79aa28c..383a3ca 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,13 @@ +2007-02-08 Stefan Kost + + * gobject/tut_gobject.xml: + * gobject/tut_gsignal.xml: + * gobject/tut_gtype.xml: + * gobject/tut_howto.xml: + * gobject/tut_tools.xml: + Unify spelling of GObject and GType. Improve some wording. Update the + usage of private data. Make tables use row-spans and add id's to them. + 2007-01-30 Matthias Clasen * gobject/tmpl/gsignal.sgml: Correct a typo. diff --git a/docs/reference/gobject/tut_gobject.xml b/docs/reference/gobject/tut_gobject.xml index 01c7a98..95f9b7f 100644 --- a/docs/reference/gobject/tut_gobject.xml +++ b/docs/reference/gobject/tut_gobject.xml @@ -17,8 +17,8 @@ Generic per-object properties with set/get function pairs Easy use of signals - All the GTK+ objects and all of the objects in GNOME libraries which use the GLib type - system inherit from GObject which is why it is important to understand + All the GNOME libraries which use the GLib type system (like Gtk+ and GStreamer) + inherit from GObject which is why it is important to understand the details of how it works. @@ -207,7 +207,7 @@ MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL); - First call to g_object_new for target type + First call to g_object_new for target type target type's base_init function On the inheritance tree of classes from fundamental type to target type. base_init is invoked once for each class structure. @@ -217,7 +217,7 @@ MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL); - First call to g_object_new for target type + target type's class_init function On target type's class structure @@ -227,19 +227,19 @@ MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL); - First call to g_object_new for target type + interface' base_init function On interface' vtable - First call to g_object_new for target type + interface' interface_init function On interface' vtable - Each call to g_object_new for target type + Each call to g_object_new for target type target type's class constructor method: GObjectClass->constructor On object's instance @@ -250,7 +250,7 @@ MamanBar *bar = g_object_new (MAMAN_TYPE_BAR, NULL); - Each call to g_object_new for target type + type's instance_init function On the inheritance tree of classes from fundamental type to target type. the instance_init provided for each type is invoked once for each instance @@ -359,11 +359,12 @@ void g_object_run_dispose (GObject *object); Function's parameters Remark - + - Last call to g_object_unref for an instance - of target type + Last call to g_object_unref for an instance + of target type + target type's dispose class function GObject instance @@ -376,9 +377,9 @@ void g_object_run_dispose (GObject *object); - Last call to g_object_unref for an instance + target type's finalize class function GObject instance @@ -392,31 +393,35 @@ void g_object_run_dispose (GObject *object); - Last call to g_object_unref for the last - instance of target type + Last call to g_object_unref for the last + instance of target type + interface' interface_finalize function On interface' vtable Never used in practice. Unlikely you will need it. - Last call to g_object_unreffor the last - instance of target type + interface' base_finalize function On interface' vtable Never used in practice. Unlikely you will need it. - Last call to g_object_unref for the last - instance of target type + target type's class_finalize function On target type's class structure Never used in practice. Unlikely you will need it. - Last call to g_object_unref for the last - instance of target type + type's base_finalize function - On the inheritance tree of classes from fundamental type to target type. + On the inheritance tree of classes from fundamental type to target type. base_init is invoked once for each class structure. Never used in practice. Unlikely you will need it. @@ -649,11 +654,11 @@ g_object_set_property (G_OBJECT (bar), "papa-number", &val); g_value_transform will try to transform the input signed char into an unsigned int. Of course, the success of the transformation depends on the availability of the required transform function. In practice, there will almost always be a transformation - - Its behaviour might not be what you expect but it is up to you to actually avoid - relying on these transformations. - - + + Its behaviour might not be what you expect but it is up to you to actually avoid + relying on these transformations. + + which matches and conversion will be caried out if needed. @@ -691,9 +696,9 @@ g_object_set_property (G_OBJECT (bar), "papa-number", &val); Once the property has been set by the object's set_property class method, the code path returns to g_object_set_property which calls - g_object_notify_queue_thaw. This function makes sure that - the "notify" signal is emitted on the object's instance with the changed property as - parameter unless notifications were frozen by g_object_freeze_notify. + g_object_notify_queue_thaw. This function makes sure that + the "notify" signal is emitted on the object's instance with the changed property as + parameter unless notifications were frozen by g_object_freeze_notify. @@ -704,6 +709,14 @@ g_object_set_property (G_OBJECT (bar), "papa-number", &val); change notification is thawn: no property change is lost for the "notify" signal. Signal can only be delayed by the notification freezing mechanism. + + + It sounds like a tedious task to set up GValues everytime when one wants to modify a property. + In practice one will rarely do this. The functions g_object_set_property + and g_object_get_property + are meant to be used by language bindings. For application there is an easier way and + that is described next. + Accessing multiple properties at once @@ -721,6 +734,8 @@ g_object_set (G_OBJECT (foo), "maman-name", "test", NULL); + This saves us from managing the GValues that we were needing to handle when using + g_object_set_property. The code above will trigger one notify signal emission for each property modified. @@ -729,12 +744,20 @@ g_object_set (G_OBJECT (foo), and g_object_get_valist (vararg version) can be used to get numerous properties at once. + + + These high level functions have one drawback - they don't provide a return result. + One should pay attention to the argument types and ranges when using them. + A know source of errors is to e.g. pass a gfloat instead of a gdouble and thus + shifting all subsequent parameters by four bytes. Also forgetting the terminating + NULL will lead to unexpected behaviour. + Really attentive readers now understand how g_object_new, g_object_newv and g_object_new_valist work: they parse the user-provided variable number of parameters and invoke - g_object_set on each pair of parameters only after the object has been successfully constructed. + g_object_set on the parameters only after the object has been successfully constructed. Of course, the "notify" signal will be emitted for each property set. diff --git a/docs/reference/gobject/tut_gsignal.xml b/docs/reference/gobject/tut_gsignal.xml index 59e27b9..55e646c 100644 --- a/docs/reference/gobject/tut_gsignal.xml +++ b/docs/reference/gobject/tut_gsignal.xml @@ -496,9 +496,9 @@ void g_signal_emit_by_name (gpointer instance, If a detail is provided by the user to the emission function, it is used during emission to match - against the closures which also provide a detail. The closures which provided a detail will not - be invoked (even though they are connected to a signal which is being emitted) if their detail - does not match the detail provided by the user. + against the closures which also provide a detail. + If the closures' detail does not match the detail provided by the user, they will not be invoked + (even though they are connected to a signal which is being emitted). This completely optional filtering mechanism is mainly used as an optimization for signals diff --git a/docs/reference/gobject/tut_gtype.xml b/docs/reference/gobject/tut_gtype.xml index d24798a..c9e97be 100644 --- a/docs/reference/gobject/tut_gtype.xml +++ b/docs/reference/gobject/tut_gtype.xml @@ -240,7 +240,7 @@ struct _GTypeValueTable For example: maman_object_method. Create a macro named PREFIX_OBJECT_TYPE which always - returns the Gtype for the associated object type. For an object of type + returns the GType for the associated object type. For an object of type Bar in a libray prefixed by maman, use: MAMAN_BAR_TYPE. It is common although not a convention to implement this macro using either a global @@ -551,7 +551,7 @@ The class initialization process is entirely implemented in (the concept of destruction is sometimes partly refered to as finalization - in Gtype) is the symmetric process of the initialization: interfaces are + in GType) is the symmetric process of the initialization: interfaces are destroyed first. Then, the most derived class_finalize (ClassFinalizeFunc) function is invoked. The @@ -583,7 +583,7 @@ The class initialization process is entirely implemented in The instanciation/finalization process can be summarized as follows: - +
GType Instantiation/Finalization @@ -599,18 +599,18 @@ The class initialization process is entirely implemented in - First call to g_type_create_instance for target type + First call to g_type_create_instance for target type type's base_init function On the inheritance tree of classes from fundamental type to target type. base_init is invoked once for each class structure. - First call to g_type_create_instance for target type + target type's class_init function On target type's class structure - First call to g_type_create_instance for target type + interface initialization, see @@ -621,18 +621,18 @@ The class initialization process is entirely implemented in On object's instance - Last call to g_type_free_instance for target type + Last call to g_type_free_instance for target type interface destruction, see - Last call to g_type_free_instance for target type + target type's class_finalize function On target type's class structure - Last call to g_type_free_instance for target type + type's base_finalize function On the inheritance tree of classes from fundamental type to target type. base_finalize is invoked once for each class structure. @@ -648,8 +648,10 @@ The class initialization process is entirely implemented in Non-instantiable classed types: Interfaces. - GType's Interfaces are very similar to Java's interfaces. To declare one of these - you have to register a non-instantiable classed type which derives from + GType's Interfaces are very similar to Java's interfaces. They allow + to describe a common API that several classes will adhere to. + To declare an interfacce you have to register a non-instantiable + classed type which derives from GTypeInterface. The following piece of code declares such an interface. #define MAMAN_IBAZ_TYPE (maman_ibaz_get_type ()) @@ -820,7 +822,7 @@ maman_ibaz_base_init (gpointer g_iface) The above process can be summarized as follows: -
+
Interface Initialization @@ -837,8 +839,9 @@ maman_ibaz_base_init (gpointer g_iface) - First call to g_type_create_instance for type - implementing interface + First call to g_type_create_instance for type + implementing interface + interface' base_init function On interface' vtable Register interface' signals here (use a local static @@ -846,8 +849,9 @@ maman_ibaz_base_init (gpointer g_iface) twice.). - First call to g_type_create_instance for type - implementing interface + interface' interface_init function On interface' vtable @@ -891,8 +895,8 @@ maman_ibaz_base_init (gpointer g_iface) - The above process can be summarized as follows: -
+ The above process can be summarized as follows: +
Interface Finalization @@ -908,14 +912,16 @@ maman_ibaz_base_init (gpointer g_iface) - Last call to g_type_free_instance for type - implementing interface + Last call to g_type_free_instance for type + implementing interface + interface' interface_finalize function On interface' vtable - Last call to g_type_free_instancefor type - implementing interface + interface' base_finalize function On interface' vtable diff --git a/docs/reference/gobject/tut_howto.xml b/docs/reference/gobject/tut_howto.xml index f015a00..7be693a 100644 --- a/docs/reference/gobject/tut_howto.xml +++ b/docs/reference/gobject/tut_howto.xml @@ -107,7 +107,6 @@ * Potentially, include other headers on which this header depends. */ - /* * Type macros. */ @@ -144,7 +143,7 @@ GType maman_bar_get_type (void); struct _MamanBar { GObject parent; - /* private */ + /*< private >*/ int hsize; }; @@ -160,7 +159,7 @@ typedef struct _MamanBarPrivate MamanBarPrivate; struct _MamanBar { GObject parent; - /* private */ + /*< private >*/ MamanBarPrivate *priv; }; @@ -420,12 +419,12 @@ bar_dispose (GObject *obj) { MamanBar *self = (MamanBar *)obj; - if (self->private->dispose_has_run) { + if (self->priv->dispose_has_run) { /* If dispose did already run, return. */ return; } /* Make sure dispose does not run twice. */ - object->private->dispose_has_run = TRUE; + object->priv->dispose_has_run = TRUE; /* * In dispose, you are supposed to free all types referenced from this @@ -443,12 +442,6 @@ bar_finalize (GObject *obj) { MamanBar *self = (MamanBar *)obj; - /* - * Here, complete object destruction. - * You might not need to do much... - */ - g_free (self->private); - /* Chain up to the parent class */ G_OBJECT_CLASS (parent_class)->finalize (obj); } @@ -460,6 +453,9 @@ bar_class_init (BarClass *klass) gobject_class->dispose = bar_dispose; gobject_class->finalize = bar_finalize; + + parent_class = g_type_class_peek_parent (klass); + g_type_class_add_private(klass,sizeof(MamanBarPrivate)); } static void @@ -467,10 +463,9 @@ maman_bar_init (GTypeInstance *instance, gpointer g_class) { MamanBar *self = (MamanBar *)instance; - self->private = g_new0 (MamanBarPrivate, 1); - self->private->dispose_has_run = FALSE; + self->priv = G_TYPE_INSTANCE_GET_PRIVATE(self, BT_TYPE_PATTERN, BtPatternPrivate); + self->priv->dispose_has_run = FALSE; - parent_class = g_type_class_peek_parent (klass); } @@ -1101,9 +1096,9 @@ maman_bar_get_type (void) Interface Properties - Starting from version 2.4 of glib, gobject interfaces can also have properties. + Starting from version 2.4 of glib, GObject interfaces can also have properties. Declaration of the interface properties is similar to declaring the properties of - ordinary gobject types as explained in , + ordinary GObject types as explained in , except that g_object_interface_install_property is used to declare the properties instead of g_object_class_install_property. @@ -1591,7 +1586,7 @@ klass->write_signal_id = If you have doubts about which method to use, I would advise you to use the second one which involves g_signal_new rather than g_signal_newv: - it is better to write code which looks like the vast majority of other GTK+/Gobject code than to + it is better to write code which looks like the vast majority of other GTK+/GObject code than to do it your own way. However, now, you know why. diff --git a/docs/reference/gobject/tut_tools.xml b/docs/reference/gobject/tut_tools.xml index 4651035..f240c91 100644 --- a/docs/reference/gobject/tut_tools.xml +++ b/docs/reference/gobject/tut_tools.xml @@ -1,29 +1,29 @@ - - Several useful developer tools have been build around GObject technology. - The next sections briefly introduce them and link to the respective project pages. - + + Several useful developer tools have been build around GObject technology. + The next sections briefly introduce them and link to the respective project pages. + GObject builder - Writing gobjects can be a tedious task. It requires a lot of typing and just - doing a copy/paste requires a great deal of care. - One obvious idea is to use some sort of templates for the class skeletons. - and then run them through a special tool to generate the real C files. - GOB/ (or GOB2) is such - a tool. It is a preprocessor which can be used to build GObjects - with inline C code so that there is no need to edit the generated C code. - The syntax is inspired by Java and Yacc or Lex. The implementation is - intentionally kept simple: the inline C code provided by the user - is not parsed. + Writing GObjects can be a tedious task. It requires a lot of typing and just + doing a copy/paste requires a great deal of care. + One obvious idea is to use some sort of templates for the class skeletons. + and then run them through a special tool to generate the real C files. + GOB/ (or GOB2) is such + a tool. It is a preprocessor which can be used to build GObjects + with inline C code so that there is no need to edit the generated C code. + The syntax is inspired by Java and Yacc or Lex. The implementation is + intentionally kept simple: the inline C code provided by the user + is not parsed. - Graphical inspection of Gobjects + Graphical inspection of GObjects Yet another tool that you may find helpful when working with -- 2.7.4